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 =head1 RETURN VALUES
  46
  47 SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback()
  48 return 1 if the B<callback> is successfully set. They return 0 if an error
  49 occurs, e.g. a custom client extension handler has been setup to handle SCTs.
  50
  51 SSL_CTX_get_ct_validation_callback() and SSL_get_ct_validation_callback()
  52 return the current callback, or NULL if no callback is set.
  53
  54 =head1 SEE ALSO
  55
  56 L<ssl(3)>,
  57 L<ct_validation_cb(3)>
  58
  59 =cut