Documentation for new SSL functions

=pod

=head1 NAME

SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular

client extension type

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type);

=head1 DESCRIPTION

SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a

client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext().

=head1 RETURN VALUES

Returns 1 if a handler has been set, 0 otherwise.

=head1 SEE ALSO

L<ssl(3)>,

L<SSL_CTX_add_client_custom_ext(3)>

=cut

=pod

=head1 NAME

SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback,

SSL_get_ct_validation_callback, SSL_CTX_get_ct_validation_callback -

control Certificate Transparency policy

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_set_ct_validation_callback(SSL *s, ct_validation_cb callback, void *arg);

 int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, ct_validation_cb callback, void *arg);

 ct_validation_cb SSL_get_ct_validation_callback(const SSL *s);

 ct_validation_cb SSL_CTX_get_ct_validation_callback(const SSL_CTX *ctx);

=head1 DESCRIPTION

SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() set

the function that is called when Certificate Transparency validation needs to

occur. It is the responsibility of this function to examine the signed

certificate timestamps (SCTs) that are passed to it and determine whether they

are sufficient to allow the connection to continue. If they are, the function

must return 1, otherwise it must return 0.

An arbitrary piece of user data, B<arg>, can be passed in when setting the

callback. This will be passed to the callback whenever it is invoked. Ownership

of this userdata remains with the caller.

If no callback is set, SCTs will not be requested and Certificate Transparency

validation will not occur.

=head1 NOTES

If a callback is set, OCSP stapling will be enabled. This is because one

possible source of SCTs is the OCSP response from a server.

=head1 RESTRICTIONS

Certificate Transparency validation cannot be enabled and so a callback cannot

be set if a custom client extension handler has been registered to handle SCT

extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>).

=head1 RETURN VALUES

SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback()

return 1 if the B<callback> is successfully set. They return 0 if an error

occurs, e.g. a custom client extension handler has been setup to handle SCTs.

SSL_CTX_get_ct_validation_callback() and SSL_get_ct_validation_callback()

return the current callback, or NULL if no callback is set.

=head1 SEE ALSO

L<ssl(3)>,

L<ct_validation_cb(3)>

=cut

=pod

=head1 NAME

SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file -

load a Certificate Transparency log list from a file

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx);

 int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path);

=head1 DESCRIPTION

SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency

(CT) logs from the default file location, "ct_log_list.cnf", found in the

directory where OpenSSL is installed.

SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a given path.

The expected format of the log list file is:

 enabled_logs=foo,bar

 [foo]

 description = Log 1

 key = <base64-encoded public key here>

 [bar]

 description = Log 2

 key = <base64-encoded public key here>

=head1 NOTES

These functions will not clear the existing CT log list - it will be appended

to.

SSL_CTX_set_default_ctlog_list_file() will not report errors if it fails for

any reason. Use SSL_CTX_set_ctlog_list_file() if you want errors to be reported.

If an error occurs whilst parsing a particular log entry in the file, that log

entry will be skipped.

=head1 RETURN VALUES

SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file()

return 1 if the log list is successfully loaded, and 0 if an error occurs. In

the case of an error, the log list may have been partially loaded.

=head1 SEE ALSO

L<ssl(3)>,

L<ct_validation_cb(3)>

=cut

=pod

=head1 NAME

SSL_get0_peer_scts - get SCTs received

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s);

=head1 DESCRIPTION

SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have

been received. If this is the first time that this function has been called for

a given B<SSL> instance, it will examine the TLS extensions, OCSP response and

the peer's certificate for SCTs. Future calls will return the same SCTs.

=head1 RESTRICTIONS

If no Certificate Transparency validation callback has been set (using

B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>),

this function is not guarantee to return all of the SCTs that the peer is

capable of sending.

=head1 RETURN VALUES

SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs.

=head1 SEE ALSO

L<ssl(3)>,

L<SSL_CTX_set_ct_validation_callback(3)>

=cut