doc/ssl/SSL_CTX_set_ct_validation_callback.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,
   6 SSL_get_ct_validation_callback, SSL_CTX_get_ct_validation_callback -
   7 control Certificate Transparency policy
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/ssl.h>
  12
  13  int SSL_set_ct_validation_callback(SSL *s, ct_validation_cb callback, void *arg);
  14  int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, ct_validation_cb callback, void *arg);
  15  ct_validation_cb SSL_get_ct_validation_callback(const SSL *s);
  16  ct_validation_cb SSL_CTX_get_ct_validation_callback(const SSL_CTX *ctx);
  17
  18 =head1 DESCRIPTION
  19
  20 SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() set
  21 the function that is called when Certificate Transparency validation needs to
  22 occur. It is the responsibility of this function to examine the signed
  23 certificate timestamps (SCTs) that are passed to it and determine whether they
  24 are sufficient to allow the connection to continue. If they are, the function
  25 must return 1, otherwise it must return 0.
  26
  27 An arbitrary piece of user data, B<arg>, can be passed in when setting the
  28 callback. This will be passed to the callback whenever it is invoked. Ownership
  29 of this userdata remains with the caller.
  30
  31 If no callback is set, SCTs will not be requested and Certificate Transparency
  32 validation will not occur.
  33
  34 =head1 NOTES
  35
  36 If a callback is set, OCSP stapling will be enabled. This is because one
  37 possible source of SCTs is the OCSP response from a server.
  38
  39 =head1 RESTRICTIONS
  40
  41 Certificate Transparency validation cannot be enabled and so a callback cannot
  42 be set if a custom client extension handler has been registered to handle SCT
  43 extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>).
  44
  45 If an SCT callback is enabled, a handshake may fail if the peer does
  46 not provide a certificate, which can happen when using opportunistic
  47 encryption with anonymous (B<aNULL>) cipher-suites enabled on both ends.
  48 SCTs should only be used when the application requires an authenticated
  49 connection, and wishes to perform additional validation on that identity.
  50
  51 =head1 RETURN VALUES
  52
  53 SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback()
  54 return 1 if the B<callback> is successfully set. They return 0 if an error
  55 occurs, e.g. a custom client extension handler has been setup to handle SCTs.
  56
  57 SSL_CTX_get_ct_validation_callback() and SSL_get_ct_validation_callback()
  58 return the current callback, or NULL if no callback is set.
  59
  60 =head1 SEE ALSO
  61
  62 L<ssl(3)>,
  63 L<ct_validation_cb(3)>
  64
  65 =cut