Documentation for new SSL functions

Reviewed-by: Ben Laurie <ben@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>

4 files changed, 180 insertions, 0 deletions

diff --git a/doc/ssl/SSL_CTX_has_client_custom_ext.pod b/doc/ssl/SSL_CTX_has_client_custom_ext.pod
new file mode 100644
index 0000000000..3a1079d2b1
--- /dev/null
+++ b/doc/ssl/SSL_CTX_has_client_custom_ext.pod
@@ -0,0 +1,28 @@
+=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
diff --git a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod
new file mode 100644
index 0000000000..59ab293c0a
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod
@@ -0,0 +1,59 @@
+=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
diff --git a/doc/ssl/SSL_CTX_set_ctlog_list_file.pod b/doc/ssl/SSL_CTX_set_ctlog_list_file.pod
new file mode 100644
index 0000000000..ddad842739
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_ctlog_list_file.pod
@@ -0,0 +1,57 @@
+=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
diff --git a/doc/ssl/SSL_get0_peer_scts.pod b/doc/ssl/SSL_get0_peer_scts.pod
new file mode 100644
index 0000000000..a2a1a29906
--- /dev/null
+++ b/doc/ssl/SSL_get0_peer_scts.pod
@@ -0,0 +1,36 @@
+=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