diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2016-02-06 03:17:23 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2016-02-06 18:18:28 +0000 |
commit | 696178edff89f8df0382af0edbd0f723790a86cc (patch) | |
tree | 78902d2aab053ab4df3d4b56db74cc07d8f289af /doc/ssl | |
parent | f3ac50038df0e0739d3bc3da11fdce0dc2939e22 (diff) |
Add SSL_get0_verified_chain() to return verified chain of peer
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_get_peer_cert_chain.pod | 27 |
1 files changed, 21 insertions, 6 deletions
diff --git a/doc/ssl/SSL_get_peer_cert_chain.pod b/doc/ssl/SSL_get_peer_cert_chain.pod index 4d3e6d5b09..649de145ba 100644 --- a/doc/ssl/SSL_get_peer_cert_chain.pod +++ b/doc/ssl/SSL_get_peer_cert_chain.pod @@ -2,31 +2,45 @@ =head1 NAME -SSL_get_peer_cert_chain - get the X509 certificate chain of the peer +SSL_get_peer_cert_chain, SSL_get0_verified_chain - get the X509 certificate +chain of the peer =head1 SYNOPSIS #include <openssl/ssl.h> STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); + STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl); =head1 DESCRIPTION SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates -forming the certificate chain of the peer. If called on the client side, +forming the certificate chain sent by the peer. If called on the client side, the stack also contains the peer's certificate; if called on the server side, the peer's certificate must be obtained separately using L<SSL_get_peer_certificate(3)>. If the peer did not present a certificate, NULL is returned. +NB: SSL_get_peer_chain() returns the peer chain as sent by the peer: it +only consists of certificates the peer has sent (in the order the peer +has sent them) it is B<not> a verified chain. + +SSL_get0_verified_chain() returns the B<verified> certificate chain +of the peer including the peer's end entity certificate. It must be called +after a session has been successfully established. If peer verification was +not successful (as indicated by SSL_get_verify_result() not returning +X509_V_OK) the chain may be incomplete or invalid. + =head1 NOTES The peer certificate chain is not necessarily available after reusing a session, in which case a NULL pointer is returned. -The reference count of the STACK_OF(X509) object is not incremented. -If the corresponding session is freed, the pointer must not be used -any longer. +The reference count of each certificate in the returned STACK_OF(X509) object +is not incremented and the returned stack may be invalidated by renegotiation. +If applications wish to use any certificates in the returned chain +indefinitely they must increase the reference counts using X509_up_ref() or +obtain a copy of the whole chain with X509_chain_up_ref(). =head1 RETURN VALUES @@ -47,6 +61,7 @@ The return value points to the certificate chain presented by the peer. =head1 SEE ALSO -L<ssl(3)>, L<SSL_get_peer_certificate(3)> +L<ssl(3)>, L<SSL_get_peer_certificate(3)>, L<X509_up_ref(3)>, +L<X509_chain_up_ref(3)> =cut |