diff options
author | Rob Percival <robpercival@google.com> | 2016-03-03 18:39:30 +0000 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-03-04 10:50:11 -0500 |
commit | 238d692c6a9b07ce04d896481783478086fedc6d (patch) | |
tree | f26e8a7e9d639632f391bb1c9f5cf3e1687b5eff /doc/ssl | |
parent | 2508c047eb116df36c3189f767313cb65fd5283c (diff) |
Documentation for new SSL functions
Reviewed-by: Ben Laurie <ben@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CTX_has_client_custom_ext.pod | 28 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_ct_validation_callback.pod | 59 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_ctlog_list_file.pod | 57 | ||||
-rw-r--r-- | doc/ssl/SSL_get0_peer_scts.pod | 36 |
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 |