1=pod 2 3=head1 NAME 4 5SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), 12 void *arg); 13 void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 14 15 int (*cert_cb)(SSL *ssl, void *arg); 16 17=head1 DESCRIPTION 18 19SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback, 20B<arg> value is pointer which is passed to the application callback. 21 22When cert_cb() is NULL, no callback function is used. 23 24cert_cb() is the application defined callback. It is called before a 25certificate will be used by a client or server. The callback can then inspect 26the passed B<ssl> structure and set or clear any appropriate certificates. If 27the callback is successful it B<MUST> return 1 even if no certificates have 28been set. A zero is returned on error which will abort the handshake with a 29fatal internal error alert. A negative return value will suspend the handshake 30and the handshake function will return immediately. 31L<SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to 32indicate, that the handshake was suspended. The next call to the handshake 33function will again lead to the call of cert_cb(). It is the job of the 34cert_cb() to store information about the state of the last call, 35if required to continue. 36 37=head1 NOTES 38 39An application will typically call SSL_use_certificate() and 40SSL_use_PrivateKey() to set the end entity certificate and private key. 41It can add intermediate and optionally the root CA certificates using 42SSL_add1_chain_cert(). 43 44It might also call SSL_certs_clear() to delete any certificates associated 45with the B<SSL> object. 46 47The certificate callback functionality supersedes the (largely broken) 48functionality provided by the old client certificate callback interface. 49It is B<always> called even is a certificate is already set so the callback 50can modify or delete the existing certificate. 51 52A more advanced callback might examine the handshake parameters and set 53whatever chain is appropriate. For example a legacy client supporting only 54TLSv1.0 might receive a certificate chain signed using SHA1 whereas a 55TLSv1.2 or later client which advertises support for SHA256 could receive a 56chain using SHA256. 57 58Normal server sanity checks are performed on any certificates set 59by the callback. So if an EC chain is set for a curve the client does not 60support it will B<not> be used. 61 62=head1 RETURN VALUES 63 64SSL_CTX_set_cert_cb() and SSL_set_cert_cb() do not return values. 65 66=head1 SEE ALSO 67 68L<ssl(7)>, L<SSL_use_certificate(3)>, 69L<SSL_add1_chain_cert(3)>, 70L<SSL_get_client_CA_list(3)>, 71L<SSL_clear(3)>, L<SSL_free(3)> 72 73=head1 COPYRIGHT 74 75Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved. 76 77Licensed under the OpenSSL license (the "License"). You may not use 78this file except in compliance with the License. You can obtain a copy 79in the file LICENSE in the source distribution or at 80L<https://www.openssl.org/source/license.html>. 81 82=cut 83