diff options
Diffstat (limited to 'upstream/debian-unstable/man3/SSL_get0_peer_rpk.3ssl')
| -rw-r--r-- | upstream/debian-unstable/man3/SSL_get0_peer_rpk.3ssl | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/SSL_get0_peer_rpk.3ssl b/upstream/debian-unstable/man3/SSL_get0_peer_rpk.3ssl new file mode 100644 index 00000000..8d01f6bb --- /dev/null +++ b/upstream/debian-unstable/man3/SSL_get0_peer_rpk.3ssl @@ -0,0 +1,149 @@ +.\" -*- 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_GET0_PEER_RPK 3SSL" +.TH SSL_GET0_PEER_RPK 3SSL 2024-04-04 3.2.2-dev 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_add_expected_rpk, +SSL_get_negotiated_client_cert_type, +SSL_get_negotiated_server_cert_type, +SSL_get0_peer_rpk, +SSL_SESSION_get0_peer_rpk \- raw public key (RFC7250) support +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/ssl.h> +\& +\& int SSL_add_expected_rpk(SSL *s, EVP_PKEY *rpk); +\& int SSL_get_negotiated_client_cert_type(const SSL *s); +\& int SSL_get_negotiated_server_cert_type(const SSL *s); +\& EVP_PKEY *SSL_get0_peer_rpk(const SSL *s); +\& EVP_PKEY *SSL_SESSION_get0_peer_rpk(const SSL_SESSION *ss); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBSSL_add_expected_rpk()\fR adds a DANE TLSA record matching public key \fBrpk\fR +to SSL \fBs\fR's DANE validation policy. +.PP +\&\fBSSL_get_negotiated_client_cert_type()\fR returns the connection's negotiated +client certificate type. +.PP +\&\fBSSL_get_negotiated_server_cert_type()\fR returns the connection's negotiated +server certificate type. +.PP +\&\fBSSL_get0_peer_rpk()\fR returns the peer's raw public key from SSL \fBs\fR. +.PP +\&\fBSSL_SESSION_get0_peer_rpk()\fR returns the peer's raw public key from +SSL_SESSION \fBss\fR. +.SH NOTES +.IX Header "NOTES" +Raw public keys are used in place of certificates when the option is +negotiated. +\&\fBSSL_add_expected_rpk()\fR may be called multiple times to configure +multiple trusted keys, this makes it possible to allow for key rotation, +where a peer might be expected to offer an "old" or "new" key and the +endpoint must be able to accept either one. +.PP +When raw public keys are used, the certificate verify callback is called, and +may be used to inspect the public key via \fBX509_STORE_CTX_get0_rpk\fR\|(3). +Raw public keys have no subject, issuer, validity dates nor digital signature +to verify. They can, however, be matched verbatim or by their digest value, this +is done by specifying one or more TLSA records, see \fBSSL_CTX_dane_enable\fR\|(3). +.PP +The raw public key is typically taken from the certificate assigned to the +connection (e.g. via \fBSSL_use_certificate\fR\|(3)), but if a certificate is not +configured, then the public key will be extracted from the assigned +private key. +.PP +The \fBSSL_add_expected_rpk()\fR function is a wrapper around +\&\fBSSL_dane_tlsa_add\fR\|(3). +When DANE is enabled via \fBSSL_dane_enable\fR\|(3), the configured TLSA records +will be used to validate the peer's public key or certificate. +If DANE is not enabled, then no validation will occur. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBSSL_add_expected_rpk()\fR returns 1 on success and 0 on failure. +.PP +\&\fBSSL_get0_peer_rpk()\fR and \fBSSL_SESSION_get0_peer_rpk()\fR return the peer's raw +public key as an EVP_PKEY or NULL when the raw public key is not available. +.PP +\&\fBSSL_get_negotiated_client_cert_type()\fR and \fBSSL_get_negotiated_server_cert_type()\fR +return one of the following values: +.IP TLSEXT_cert_type_x509 4 +.IX Item "TLSEXT_cert_type_x509" +.PD 0 +.IP TLSEXT_cert_type_rpk 4 +.IX Item "TLSEXT_cert_type_rpk" +.PD +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBSSL_CTX_dane_enable\fR\|(3), +\&\fBSSL_CTX_set_options\fR\|(3), +\&\fBSSL_dane_enable\fR\|(3), +\&\fBSSL_get_verify_result\fR\|(3), +\&\fBSSL_set_verify\fR\|(3), +\&\fBSSL_use_certificate\fR\|(3), +\&\fBX509_STORE_CTX_get0_rpk\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. |