diff options
author | Matt Caswell <matt@openssl.org> | 2017-03-24 16:01:50 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2017-03-28 15:15:41 +0100 |
commit | b31db50528ccfd493b3be73f55c53f4606943d28 (patch) | |
tree | b4871183ce3c4f3d988c669623b342cc8dfed2e6 /doc | |
parent | 43708c1545c1ba71984bdc6e5ec47de65002d2fd (diff) |
Provide documentation for missing SSL_SESSION_* functions
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3052)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/SSL_SESSION_free.pod | 17 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get0_id_context.pod | 17 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get0_peer.pod | 38 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get_compress_id.pod | 39 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get_ex_data.pod | 47 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get_time.pod | 2 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_print.pod | 47 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_set1_id.pod | 11 |
8 files changed, 213 insertions, 5 deletions
diff --git a/doc/man3/SSL_SESSION_free.pod b/doc/man3/SSL_SESSION_free.pod index eca4117cba..b288baf2d2 100644 --- a/doc/man3/SSL_SESSION_free.pod +++ b/doc/man3/SSL_SESSION_free.pod @@ -2,16 +2,26 @@ =head1 NAME -SSL_SESSION_free - free an allocated SSL_SESSION structure +SSL_SESSION_new, +SSL_SESSION_up_ref, +SSL_SESSION_free - create, free and manage SSL_SESSION structures =head1 SYNOPSIS #include <openssl/ssl.h> + SSL_SESSION *SSL_SESSION_new(void); + int SSL_SESSION_up_ref(SSL_SESSION *ses); void SSL_SESSION_free(SSL_SESSION *session); =head1 DESCRIPTION +SSL_SESSION_new() creates a new SSL_SESSION structure and returns a pointer to +it. + +SSL_SESSION_up_ref() increments the reference count on the given SSL_SESSION +structure. + SSL_SESSION_free() decrements the reference count of B<session> and removes the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated memory, if the reference count has reached 0. @@ -44,7 +54,10 @@ incorrect reference counts and therefore program failures. =head1 RETURN VALUES -SSL_SESSION_free() does not provide diagnostic information. +SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure +or NULL on error. + +SSL_SESSION_up_ref returns 1 on success or 0 on error. =head1 SEE ALSO diff --git a/doc/man3/SSL_SESSION_get0_id_context.pod b/doc/man3/SSL_SESSION_get0_id_context.pod index 0e526c9762..69619a72b4 100644 --- a/doc/man3/SSL_SESSION_get0_id_context.pod +++ b/doc/man3/SSL_SESSION_get0_id_context.pod @@ -2,7 +2,9 @@ =head1 NAME -SSL_SESSION_get0_id_context - get the SSL ID context associated with a session +SSL_SESSION_get0_id_context, +SSL_SESSION_set1_id_context +- get and set the SSL ID context associated with a session =head1 SYNOPSIS @@ -10,9 +12,14 @@ SSL_SESSION_get0_id_context - get the SSL ID context associated with a session const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, unsigned int *len) + int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); =head1 DESCRIPTION +See L<SSL_CTX_set_session_id_context(3)> for further details on session ID +contexts. + SSL_SESSION_get0_id_context() returns the ID context associated with the SSL/TLS session B<s>. The length of the ID context is written to B<*len> if B<len> is not NULL. @@ -20,6 +27,14 @@ B<*len> if B<len> is not NULL. The value returned is a pointer to an object maintained within B<s> and should not be released. +SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in +B<sid_ctx> and associates it with the session B<s>. The length of the ID context +is given by B<sid_ctx_len> which must not exceed SSL_MAX_SID_CTX_LENGTH bytes. + +=head1 RETURN VALUES + +SSL_SESSION_set1_id_context() returns 1 on success or 0 on error. + =head1 SEE ALSO L<ssl(7)>, diff --git a/doc/man3/SSL_SESSION_get0_peer.pod b/doc/man3/SSL_SESSION_get0_peer.pod new file mode 100644 index 0000000000..570bb0713a --- /dev/null +++ b/doc/man3/SSL_SESSION_get0_peer.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_peer +- get details about peer's certificate for a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_peer() returns the peer certificate associated with the session +B<s> or NULL if no peer certificate is available. The caller should not free the +returned value (unless L<X509_up_ref(3)> has also been called). + +=head1 RETURN VALUES + +SSL_SESSION_get0_peer() returns a pointer to the peer certificate or NULL if +no peer certificat is available. + +=head1 SEE ALSO + +L<ssl(7)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/SSL_SESSION_get_compress_id.pod b/doc/man3/SSL_SESSION_get_compress_id.pod new file mode 100644 index 0000000000..0bdccb4b76 --- /dev/null +++ b/doc/man3/SSL_SESSION_get_compress_id.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_compress_id +- get details about the compression associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s); + +=head1 DESCRIPTION + +If compression has been negotiated for an ssl session then +SSL_SESSION_get_compress_id() will return the id for the compression method or +0 otherwise. The only built-in supported compression method is zlib which has an +id of 1. + +=head1 RETURN VALUES + +SSL_SESSION_get_compress_id() returns the id of the compression method or 0 if +none. + +=head1 SEE ALSO + +L<ssl(7)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/SSL_SESSION_get_ex_data.pod b/doc/man3/SSL_SESSION_get_ex_data.pod new file mode 100644 index 0000000000..f44c4e8e1f --- /dev/null +++ b/doc/man3/SSL_SESSION_get_ex_data.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_set_ex_data, +SSL_SESSION_get_ex_data +- get and set application specific data on a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); + void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); + +=head1 DESCRIPTION + +SSL_SESSION_set_ex_data() enables an application to store arbitrary application +specific data B<data> in an SSL_SESSION structure B<ss>. The index B<idx> should +be a value previously returned from a call to L<CRYPTO_get_ex_new_index(3)>. + +SSL_SESSION_get_ex_data() retrieves application specific data previously stored +in an SSL_SESSION structure B<s>. The B<idx> value should be the same as that +used when originally storing the data. + +=head1 RETURN VALUES + +SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure. + +SSL_SESSION_get_ex_data() returns the previously stored value or NULL on +failure. NULL may also be a valid value. + +=head1 SEE ALSO + +L<ssl(7)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/SSL_SESSION_get_time.pod b/doc/man3/SSL_SESSION_get_time.pod index ca08937eef..e98d128b02 100644 --- a/doc/man3/SSL_SESSION_get_time.pod +++ b/doc/man3/SSL_SESSION_get_time.pod @@ -3,7 +3,7 @@ =head1 NAME SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, -SSL_SESSION_set_timeout +SSL_SESSION_set_timeout, SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout - retrieve and manipulate session time and timeout settings diff --git a/doc/man3/SSL_SESSION_print.pod b/doc/man3/SSL_SESSION_print.pod new file mode 100644 index 0000000000..957411a771 --- /dev/null +++ b/doc/man3/SSL_SESSION_print.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_print, +SSL_SESSION_print_fp, +SSL_SESSION_print_keylog +- printf information about a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x); + +=head1 DESCRIPTION + +SSL_SESSION_print() prints summary information about the session provided in +B<ses> to the BIO B<fp>. + +SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it +to the FILE B<fp>. + +SSL_SESSION_print_keylog() prints session information to the provided BIO <bp> +in NSS keylog format. + +=head1 RETURN VALUES + +SSL_SESSION_print(), SSL_SESSION_print_fp() and SSL_SESSION_print_keylog return +1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(7)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/SSL_SESSION_set1_id.pod b/doc/man3/SSL_SESSION_set1_id.pod index c75bb4be90..f69c83bf2a 100644 --- a/doc/man3/SSL_SESSION_set1_id.pod +++ b/doc/man3/SSL_SESSION_set1_id.pod @@ -2,22 +2,31 @@ =head1 NAME -SSL_SESSION_set1_id - set the SSL session ID +SSL_SESSION_get_id, +SSL_SESSION_set1_id +- get and set the SSL session ID =head1 SYNOPSIS #include <openssl/ssl.h> + const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s, + unsigned int *len) int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, unsigned int sid_len); =head1 DESCRIPTION +SSL_SESSION_get_id() returns a pointer to the internal session id value for the +session B<s>. The length of the id in bytes is stored in B<*len>. The length may +be 0. The caller should not free the returned pointer directly. + SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session to B<sid> of length B<sid_len>. =head1 RETURN VALUES +SSL_SESSION_get_id() returns a pointer to the session id value. SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>. |