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