SSL_CTX_set_cert_cb.pod 3.0 KB

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