From b31db50528ccfd493b3be73f55c53f4606943d28 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 24 Mar 2017 16:01:50 +0000 Subject: [PATCH] Provide documentation for missing SSL_SESSION_* functions Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/3052) --- doc/man3/SSL_SESSION_free.pod | 17 ++++++++- doc/man3/SSL_SESSION_get0_id_context.pod | 17 ++++++++- doc/man3/SSL_SESSION_get0_peer.pod | 38 +++++++++++++++++++ doc/man3/SSL_SESSION_get_compress_id.pod | 39 ++++++++++++++++++++ doc/man3/SSL_SESSION_get_ex_data.pod | 47 ++++++++++++++++++++++++ doc/man3/SSL_SESSION_get_time.pod | 2 +- doc/man3/SSL_SESSION_print.pod | 47 ++++++++++++++++++++++++ doc/man3/SSL_SESSION_set1_id.pod | 11 +++++- 8 files changed, 213 insertions(+), 5 deletions(-) create mode 100644 doc/man3/SSL_SESSION_get0_peer.pod create mode 100644 doc/man3/SSL_SESSION_get_compress_id.pod create mode 100644 doc/man3/SSL_SESSION_get_ex_data.pod create mode 100644 doc/man3/SSL_SESSION_print.pod 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 + 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 and removes the B structure pointed to by B 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 for further details on session ID +contexts. + SSL_SESSION_get0_id_context() returns the ID context associated with the SSL/TLS session B. The length of the ID context is written to B<*len> if B is not NULL. @@ -20,6 +27,14 @@ B<*len> if B is not NULL. The value returned is a pointer to an object maintained within B and should not be released. +SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in +B and associates it with the session B. The length of the ID context +is given by B 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, 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 + + X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_peer() returns the peer certificate associated with the session +B or NULL if no peer certificate is available. The caller should not free the +returned value (unless L 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 + +=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. + +=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 + + 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 + +=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. + +=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 + + 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 in an SSL_SESSION structure B. The index B should +be a value previously returned from a call to L. + +SSL_SESSION_get_ex_data() retrieves application specific data previously stored +in an SSL_SESSION structure B. The B 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, +L + +=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. + +=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 + + 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 to the BIO B. + +SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it +to the FILE B. + +SSL_SESSION_print_keylog() prints session information to the provided BIO +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 + +=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. + +=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 + 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. 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/TLS session to B of length B. =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. -- 2.25.1