From 238d692c6a9b07ce04d896481783478086fedc6d Mon Sep 17 00:00:00 2001 From: Rob Percival Date: Thu, 3 Mar 2016 18:39:30 +0000 Subject: [PATCH] Documentation for new SSL functions Reviewed-by: Ben Laurie Reviewed-by: Rich Salz --- doc/ssl/SSL_CTX_has_client_custom_ext.pod | 28 +++++++++ .../SSL_CTX_set_ct_validation_callback.pod | 59 +++++++++++++++++++ doc/ssl/SSL_CTX_set_ctlog_list_file.pod | 57 ++++++++++++++++++ doc/ssl/SSL_get0_peer_scts.pod | 36 +++++++++++ 4 files changed, 180 insertions(+) create mode 100644 doc/ssl/SSL_CTX_has_client_custom_ext.pod create mode 100644 doc/ssl/SSL_CTX_set_ct_validation_callback.pod create mode 100644 doc/ssl/SSL_CTX_set_ctlog_list_file.pod create mode 100644 doc/ssl/SSL_get0_peer_scts.pod 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 + + 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 using SSL_CTX_add_client_custom_ext(). + +=head1 RETURN VALUES + +Returns 1 if a handler has been set, 0 otherwise. + +=head1 SEE ALSO + +L, +L + +=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 + + 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, 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). + +=head1 RETURN VALUES + +SSL_CTX_set_ct_validation_callback() and SSL_set_ct_validation_callback() +return 1 if the B 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, +L + +=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 + + 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 = + + [bar] + description = Log 2 + key = + +=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, +L + +=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 + + 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 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 or B), +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, +L + +=cut -- 2.25.1