diff options
author | Hugo Landau <hlandau@openssl.org> | 2022-03-04 12:53:50 +0000 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2022-03-14 09:59:54 +0100 |
commit | 2a9219514263454896bdda800b4b811843338bc7 (patch) | |
tree | 1bda11dd387c2e5e5a26fb08778bb7ec22fea5d3 | |
parent | 2823e2e1d39479a7835d176862ec15e47a1bdecd (diff) |
Add manpages for SSL_get_certificate, SSL_get_private_key
This is as I understand these functions from reading the code.
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17815)
-rw-r--r-- | doc/build.info | 6 | ||||
-rw-r--r-- | doc/man3/SSL_get_certificate.pod | 73 | ||||
-rw-r--r-- | util/missingssl.txt | 2 |
3 files changed, 79 insertions, 2 deletions
diff --git a/doc/build.info b/doc/build.info index 4e1db237d7..46dabeb9a6 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2415,6 +2415,10 @@ DEPEND[html/man3/SSL_get_all_async_fds.html]=man3/SSL_get_all_async_fds.pod GENERATE[html/man3/SSL_get_all_async_fds.html]=man3/SSL_get_all_async_fds.pod DEPEND[man/man3/SSL_get_all_async_fds.3]=man3/SSL_get_all_async_fds.pod GENERATE[man/man3/SSL_get_all_async_fds.3]=man3/SSL_get_all_async_fds.pod +DEPEND[html/man3/SSL_get_certificate.html]=man3/SSL_get_certificate.pod +GENERATE[html/man3/SSL_get_certificate.html]=man3/SSL_get_certificate.pod +DEPEND[man/man3/SSL_get_certificate.3]=man3/SSL_get_certificate.pod +GENERATE[man/man3/SSL_get_certificate.3]=man3/SSL_get_certificate.pod DEPEND[html/man3/SSL_get_ciphers.html]=man3/SSL_get_ciphers.pod GENERATE[html/man3/SSL_get_ciphers.html]=man3/SSL_get_ciphers.pod DEPEND[man/man3/SSL_get_ciphers.3]=man3/SSL_get_ciphers.pod @@ -3327,6 +3331,7 @@ html/man3/SSL_free.html \ html/man3/SSL_get0_peer_scts.html \ html/man3/SSL_get_SSL_CTX.html \ html/man3/SSL_get_all_async_fds.html \ +html/man3/SSL_get_certificate.html \ html/man3/SSL_get_ciphers.html \ html/man3/SSL_get_client_random.html \ html/man3/SSL_get_current_cipher.html \ @@ -3920,6 +3925,7 @@ man/man3/SSL_free.3 \ man/man3/SSL_get0_peer_scts.3 \ man/man3/SSL_get_SSL_CTX.3 \ man/man3/SSL_get_all_async_fds.3 \ +man/man3/SSL_get_certificate.3 \ man/man3/SSL_get_ciphers.3 \ man/man3/SSL_get_client_random.3 \ man/man3/SSL_get_current_cipher.3 \ diff --git a/doc/man3/SSL_get_certificate.pod b/doc/man3/SSL_get_certificate.pod new file mode 100644 index 0000000000..a57917c813 --- /dev/null +++ b/doc/man3/SSL_get_certificate.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_get_certificate, SSL_get_privatekey - retrieve TLS/SSL certificate and +private key + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_get_certificate(const SSL *s); + EVP_PKEY *SSL_get_privatekey(const SSL *s); + +=head1 DESCRIPTION + +SSL_get_certificate() returns a pointer to an B<X509> object representing a +certificate used as the local peer's identity. + +Multiple certificates can be configured; for example, a server might have both +RSA and ECDSA certificates. The certificate which is returned by +SSL_get_certificate() is determined as follows: + +=over 4 + +=item + +If it is called before certificate selection has occurred, it returns the most +recently added certificate, or NULL if no certificate has been added. + +=item + +After certificate selection has occurred, it returns the certificate which was +selected during the handshake, or NULL if no certificate was selected (for +example, on a client where no client certificate is in use). + +=back + +Certificate selection occurs during the handshake; therefore, the value returned +by SSL_get_certificate() during any callback made during the handshake process +will depend on whether that callback is made before or after certificate +selection occurs. + +A specific use for SSL_get_certificate() is inside a callback set via a call to +L<SSL_CTX_set_tlsext_status_cb(3)>. This callback occurs after certificate +selection, where it can be used to examine a server's chosen certificate, for +example for the purpose of identifying a certificate's OCSP responder URL so +that an OCSP response can be obtained. + +SSL_get_privatekey() returns a pointer to the B<EVP_PKEY> object corresponding +to the certificate returned by SSL_get_certificate(), if any. + +=head1 RETURN VALUES + +These functions return pointers to their respective objects, or NULL if no such +object is available. Returned objects are owned by the SSL object and should not +be freed by users of these functions. + +=head1 SEE ALSO + +L<ssl(7)>, L<SSL_CTX_set_tlsext_status_cb(3)> + +=head1 COPYRIGHT + +Copyright 2001-2022 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut + diff --git a/util/missingssl.txt b/util/missingssl.txt index ef13fca84a..6adf6c5117 100644 --- a/util/missingssl.txt +++ b/util/missingssl.txt @@ -22,12 +22,10 @@ SSL_certs_clear(3) SSL_copy_session_id(3) SSL_dup_CA_list(3) SSL_get0_dane(3) -SSL_get_certificate(3) SSL_get_current_compression(3) SSL_get_current_expansion(3) SSL_get_finished(3) SSL_get_peer_finished(3) -SSL_get_privatekey(3) SSL_set_SSL_CTX(3) SSL_set_debug(3) SSL_set_not_resumable_session_callback(3) |