1=pod 2 3=head1 NAME 4 5SSL_set1_client_cert_type, 6SSL_set1_server_cert_type, 7SSL_CTX_set1_client_cert_type, 8SSL_CTX_set1_server_cert_type, 9SSL_get0_client_cert_type, 10SSL_get0_server_cert_type, 11SSL_CTX_get0_client_cert_type, 12SSL_CTX_get0_server_cert_type - certificate type (RFC7250) support 13 14=head1 SYNOPSIS 15 16 #include <openssl/ssl.h> 17 18 int SSL_set1_client_cert_type(SSL *s, const unsigned char *val, size_t len); 19 int SSL_set1_server_cert_type(SSL *s, const unsigned char *val, size_t len); 20 int SSL_CTX_set1_client_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len); 21 int SSL_CTX_set1_server_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len); 22 int SSL_get0_client_cert_type(const SSL *s, unsigned char **val, size_t *len); 23 int SSL_get0_server_cert_type(const SSL *s, unsigned char **val, size_t *len); 24 int SSL_CTX_get0_client_cert_type(const SSL_CTX *ctx, unsigned char **val, size_t *len); 25 int SSL_CTX_get0_server_cert_type(const SSL_CTX *s, unsigned char **val, size_t *len); 26 27=head1 DESCRIPTION 28 29The SSL_set1_client_cert_type() and SSL_CTX_set1_client_cert_type() functions 30set the values for the client certificate type extension. 31The SSL_get0_client_cert_type() and SSL_CTX_get0_client_cert_type() functions 32retrieve the local values to be used in the client certificate type extension. 33 34The SSL_set1_server_cert_type() and SSL_CTX_set1_server_cert_type() functions 35set the values for the server certificate type extension. 36The SSL_get0_server_cert_type() and SSL_CTX_get0_server_cert_type() functions 37retrieve the local values to be used in the server certificate type extension. 38 39=head1 NOTES 40 41The certificate type extensions are used to negotiate the certificate type to 42be used in the handshake. 43These extensions let each side know what its peer is able to accept. 44 45The client certificate type is sent from the client to the server to indicate 46what certificate types the client is able to present. 47Values are configured in preference order. 48On the server, this setting determines which certificate types the server is 49willing to accept. 50The server ultimately chooses what type to request (if any) from the values 51that are mutually supported. 52By default (if no explicit settings are specified), only X.509 certificates 53are supported. 54 55The server certificate type is sent from the client to the server to indicate 56what certificate types the client accepts. 57Values are configured in preference order. 58On the server, this setting determines which certificate types the server is 59willing to present. 60The server ultimately chooses what type to use from the values that are 61mutually supported. 62By default (if no explicit settings are specified), only X.509 certificates 63are supported. 64 65Having RPK specified first means that side will attempt to send (or request) 66RPKs if its peer also supports RPKs, otherwise X.509 certificate will be used 67if both have specified that (or have not configured these options). 68 69The two supported values in the B<val> array are: 70 71=over 4 72 73=item TLSEXT_cert_type_x509 74 75Which corresponds to an X.509 certificate normally used in TLS. 76 77=item TLSEXT_cert_type_rpk 78 79Which corresponds to a raw public key. 80 81=back 82 83If B<val> is set to a non-NULL value, then the extension is sent in the handshake. 84If b<val> is set to a NULL value (and B<len> is 0), then the extension is 85disabled. The default value is NULL, meaning the extension is not sent, and 86X.509 certificates are used in the handshake. 87 88Raw public keys may be used in place of certificates when specified in the 89certificate type and negotiated. 90Raw public keys have no subject, issuer, validity dates or digital signature. 91 92Use the L<SSL_get_negotiated_client_cert_type(3)> and 93L<SSL_get_negotiated_server_cert_type(3)> functions to get the negotiated cert 94type values (at the conclusion of the handshake, or in callbacks that happen 95after the TLS ServerHello has been processed). 96 97=head1 RETURN VALUES 98 99All functions return 1 on success and 0 on failure. 100 101The memory returned from the get0 functions must not be freed. 102 103=head1 EXAMPLES 104 105To use raw public keys on the server, set up the SSL_CTX and SSL as follows: 106 107 SSL_CTX *ctx; 108 SSL *ssl; 109 unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 }; 110 EVP_PKEY *rpk; 111 112 /* Assign rpk to an EVP_PKEY from a file or other means */ 113 114 if ((ctx = SSL_CTX_new(TLS_server_method())) == NULL) 115 /* error */ 116 if ((ssl = SSL_new(ctx)) == NULL) 117 /* error */ 118 if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type))) 119 /* error */ 120 121 /* A certificate does not need to be specified when using raw public keys */ 122 if (!SSL_use_PrivateKey(ssl, rpk)) 123 /* error */ 124 125 /* Perform SSL_accept() operations */ 126 127To connect to this server, set the client SSL_CTX and SSL as follows: 128 129 /* Connect function */ 130 131 SSL_CTX *ctx; 132 SSL *ssl; 133 const char *dane_tlsa_domain = "smtp.example.com"; 134 unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 }; 135 EVP_PKEY *rpk; 136 int verify_result; 137 138 /* Assign rpk to an EVP_PKEY from a file or other means */ 139 140 if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) 141 /* error */ 142 if (SSL_CTX_dane_enable(ctx) <= 0) 143 /* error */ 144 if ((ssl = SSL_new(ctx)) == NULL) 145 /* error */ 146 /* 147 * The `dane_tlsa_domain` arguments sets the default SNI hostname. 148 * It may be set to NULL when enabling DANE on the server side. 149 */ 150 if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) 151 /* error */ 152 if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type))) 153 /* error */ 154 if (!SSL_add_expected_rpk(ssl, rpk)) 155 /* error */ 156 157 /* Do SSL_connect() handshake and handle errors here */ 158 159 /* Optional: verify the peer RPK */ 160 verify_result = SSL_get_verify_result(ssl); 161 if (verify_result == X509_V_OK) { 162 /* The server's raw public key matched the TLSA record */ 163 } else if (verify_result == X509_V_ERR_DANE_NO_MATCH) { 164 /* 165 * The server's raw public key, or public key in certificate, did not 166 * match the TLSA record 167 */ 168 } else if (verify_result == X509_V_ERR_RPK_UNTRUSTED) { 169 /* 170 * No TLSA records of the correct type are available to verify the 171 * server's raw public key. This would not happen in this example, 172 * as a TLSA record is configured. 173 */ 174 } else { 175 /* Some other verify error */ 176 } 177 178To validate client raw public keys, code from the client example may need to be 179incorporated into the server side. 180 181=head1 SEE ALSO 182 183L<SSL_get0_peer_rpk(3)>, 184L<SSL_get_negotiated_client_cert_type(3)>, 185L<SSL_get_negotiated_server_cert_type(3)>, 186L<SSL_use_certificate(3)> 187 188=head1 HISTORY 189 190These functions were added in OpenSSL 3.2. 191 192=head1 COPYRIGHT 193 194Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. 195 196=cut 197