.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SSL_SET1_SERVER_CERT_TYPE 3ssl"
.TH SSL_SET1_SERVER_CERT_TYPE 3ssl 2024-04-28 3.3.0 OpenSSL
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SSL_set1_client_cert_type,
SSL_set1_server_cert_type,
SSL_CTX_set1_client_cert_type,
SSL_CTX_set1_server_cert_type,
SSL_get0_client_cert_type,
SSL_get0_server_cert_type,
SSL_CTX_get0_client_cert_type,
SSL_CTX_get0_server_cert_type \- certificate type (RFC7250) support
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& int SSL_set1_client_cert_type(SSL *s, const unsigned char *val, size_t len);
\& int SSL_set1_server_cert_type(SSL *s, const unsigned char *val, size_t len);
\& int SSL_CTX_set1_client_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len);
\& int SSL_CTX_set1_server_cert_type(SSL_CTX *ctx, const unsigned char *val, size_t len);
\& int SSL_get0_client_cert_type(const SSL *s, unsigned char **val, size_t *len);
\& int SSL_get0_server_cert_type(const SSL *s, unsigned char **val, size_t *len);
\& int SSL_CTX_get0_client_cert_type(const SSL_CTX *ctx, unsigned char **val, size_t *len);
\& int SSL_CTX_get0_server_cert_type(const SSL_CTX *s, unsigned char **val, size_t *len);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_set1_client_cert_type()\fR and \fBSSL_CTX_set1_client_cert_type()\fR functions
set the values for the client certificate type extension.
The \fBSSL_get0_client_cert_type()\fR and \fBSSL_CTX_get0_client_cert_type()\fR functions
retrieve the local values to be used in the client certificate type extension.
.PP
The \fBSSL_set1_server_cert_type()\fR and \fBSSL_CTX_set1_server_cert_type()\fR functions
set the values for the server certificate type extension.
The \fBSSL_get0_server_cert_type()\fR and \fBSSL_CTX_get0_server_cert_type()\fR functions
retrieve the local values to be used in the server certificate type extension.
.SH NOTES
.IX Header "NOTES"
The certificate type extensions are used to negotiate the certificate type to
be used in the handshake.
These extensions let each side know what its peer is able to accept.
.PP
The client certificate type is sent from the client to the server to indicate
what certificate types the client is able to present.
Values are configured in preference order.
On the server, this setting determines which certificate types the server is
willing to accept.
The server ultimately chooses what type to request (if any) from the values
that are mutually supported.
By default (if no explicit settings are specified), only X.509 certificates
are supported.
.PP
The server certificate type is sent from the client to the server to indicate
what certificate types the client accepts.
Values are configured in preference order.
On the server, this setting determines which certificate types the server is
willing to present.
The server ultimately chooses what type to use from the values that are
mutually supported.
By default (if no explicit settings are specified), only X.509 certificates
are supported.
.PP
Having RPK specified first means that side will attempt to send (or request)
RPKs if its peer also supports RPKs, otherwise X.509 certificate will be used
if both have specified that (or have not configured these options).
.PP
The two supported values in the \fBval\fR array are:
.IP TLSEXT_cert_type_x509 4
.IX Item "TLSEXT_cert_type_x509"
Which corresponds to an X.509 certificate normally used in TLS.
.IP TLSEXT_cert_type_rpk 4
.IX Item "TLSEXT_cert_type_rpk"
Which corresponds to a raw public key.
.PP
If \fBval\fR is set to a non-NULL value, then the extension is sent in the handshake.
If b<val> is set to a NULL value (and \fBlen\fR is 0), then the extension is
disabled. The default value is NULL, meaning the extension is not sent, and
X.509 certificates are used in the handshake.
.PP
Raw public keys may be used in place of certificates when specified in the
certificate type and negotiated.
Raw public keys have no subject, issuer, validity dates or digital signature.
.PP
Use the \fBSSL_get_negotiated_client_cert_type\fR\|(3) and
\&\fBSSL_get_negotiated_server_cert_type\fR\|(3) functions to get the negotiated cert
type values (at the conclusion of the handshake, or in callbacks that happen
after the TLS ServerHello has been processed).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
All functions return 1 on success and 0 on failure.
.PP
The memory returned from the get0 functions must not be freed.
.SH EXAMPLES
.IX Header "EXAMPLES"
To use raw public keys on the server, set up the SSL_CTX and SSL as follows:
.PP
.Vb 4
\& SSL_CTX *ctx;
\& SSL *ssl;
\& unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 };
\& EVP_PKEY *rpk;
\&
\& /* Assign rpk to an EVP_PKEY from a file or other means */
\&
\& if ((ctx = SSL_CTX_new(TLS_server_method())) == NULL)
\&     /* error */
\& if ((ssl = SSL_new(ctx)) == NULL)
\&     /* error */
\& if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type)))
\&     /* error */
\&
\& /* A certificate does not need to be specified when using raw public keys */
\& if (!SSL_use_PrivateKey(ssl, rpk))
\&     /* error */
\&
\& /* Perform SSL_accept() operations */
.Ve
.PP
To connect to this server, set the client SSL_CTX and SSL as follows:
.PP
.Vb 1
\& /* Connect function */
\&
\& SSL_CTX *ctx;
\& SSL *ssl;
\& const char *dane_tlsa_domain = "smtp.example.com";
\& unsigned char cert_type[] = { TLSEXT_cert_type_rpk, TLSEXT_cert_type_x509 };
\& EVP_PKEY *rpk;
\& int verify_result;
\&
\& /* Assign rpk to an EVP_PKEY from a file or other means */
\&
\& if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
\&     /* error */
\& if (SSL_CTX_dane_enable(ctx) <= 0)
\&     /* error */
\& if ((ssl = SSL_new(ctx)) == NULL)
\&     /* error */
\& /*
\&  * The \`dane_tlsa_domain\` arguments sets the default SNI hostname.
\&  * It may be set to NULL when enabling DANE on the server side.
\&  */
\& if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
\&     /* error */
\& if (!SSL_set1_server_cert_type(ssl, cert_type, sizeof(cert_type)))
\&     /* error */
\& if (!SSL_add_expected_rpk(ssl, rpk))
\&     /* error */
\&
\& /* Do SSL_connect() handshake and handle errors here */
\&
\& /* Optional: verify the peer RPK */
\& verify_result = SSL_get_verify_result(ssl);
\& if (verify_result == X509_V_OK) {
\&     /* The server\*(Aqs raw public key matched the TLSA record */
\& } else if (verify_result == X509_V_ERR_DANE_NO_MATCH) {
\&     /*
\&      * The server\*(Aqs raw public key, or public key in certificate, did not
\&      * match the TLSA record
\&      */
\& } else if (verify_result == X509_V_ERR_RPK_UNTRUSTED) {
\&     /*
\&      * No TLSA records of the correct type are available to verify the
\&      * server\*(Aqs raw public key. This would not happen in this example,
\&      * as a TLSA record is configured.
\&      */
\& } else {
\&     /* Some other verify error */
\& }
.Ve
.PP
To validate client raw public keys, code from the client example may need to be
incorporated into the server side.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_get0_peer_rpk\fR\|(3),
\&\fBSSL_get_negotiated_client_cert_type\fR\|(3),
\&\fBSSL_get_negotiated_server_cert_type\fR\|(3),
\&\fBSSL_use_certificate\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
These functions were added in OpenSSL 3.2.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.