wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openssl/doc/man3/SSL_CTX_add_session.pod

83 lines
2.5 KiB
Text
Raw Normal View History

Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
=pod
=head1 NAME
SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c);
=head1 DESCRIPTION
SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The
reference count for session B<c> is incremented by 1. If a session with
the same session id already exists, the old session is removed by calling
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-17 19:21:33 +00:00
L<SSL_SESSION_free(3)>.
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>.
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-17 19:21:33 +00:00
L<SSL_SESSION_free(3)> is called once for B<c>.
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
SSL_add_session() and SSL_remove_session() are synonyms for their
SSL_CTX_*() counterparts.
=head1 NOTES
When adding a new session to the internal session cache, it is examined
whether a session with the same session id already exists. In this case
it is assumed that both sessions are identical. If the same session is
stored in a different SSL_SESSION object, The old session is
removed and replaced by the new session. If the session is actually
identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
is a no-op, and the return value is 0.
Correct and enhance the behaviour of "internal" session caching as it relates to SSL_CTX flags and the use of "external" session caching. The existing flag, "SSL_SESS_CACHE_NO_INTERNAL_LOOKUP" remains but is supplemented with a complimentary flag, "SSL_SESS_CACHE_NO_INTERNAL_STORE". The bitwise OR of the two flags is also defined as "SSL_SESS_CACHE_NO_INTERNAL" and is the flag that should be used by most applications wanting to implement session caching *entirely* by its own provided callbacks. As the documented behaviour contradicted actual behaviour up until recently, and since that point behaviour has itself been inconsistent anyway, this change should not introduce any compatibility problems. I've adjusted the relevant documentation to elaborate about how this works. Kudos to "Nadav Har'El" <nyh@math.technion.ac.il> for diagnosing these anomalies and testing this patch for correctness. PR: 311
2002-10-29 00:33:04 +00:00
If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
flag then the internal cache will not be populated automatically by new
sessions negotiated by the SSL/TLS implementation, even though the internal
cache will be searched automatically for session-resume requests (the
Close a whole bunch of documentation-related tickets: 298 424 656 882 939 1630 1807 2263 2294 2311 2424 2623 2637 2686 2697 2921 2922 2940 3055 3112 3156 3177 3277
2014-07-03 02:42:40 +00:00
latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
Correct and enhance the behaviour of "internal" session caching as it relates to SSL_CTX flags and the use of "external" session caching. The existing flag, "SSL_SESS_CACHE_NO_INTERNAL_LOOKUP" remains but is supplemented with a complimentary flag, "SSL_SESS_CACHE_NO_INTERNAL_STORE". The bitwise OR of the two flags is also defined as "SSL_SESS_CACHE_NO_INTERNAL" and is the flag that should be used by most applications wanting to implement session caching *entirely* by its own provided callbacks. As the documented behaviour contradicted actual behaviour up until recently, and since that point behaviour has itself been inconsistent anyway, this change should not introduce any compatibility problems. I've adjusted the relevant documentation to elaborate about how this works. Kudos to "Nadav Har'El" <nyh@math.technion.ac.il> for diagnosing these anomalies and testing this patch for correctness. PR: 311
2002-10-29 00:33:04 +00:00
application can use SSL_CTX_add_session() directly to have full control
over the sessions that can be resumed if desired.
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
=head1 RETURN VALUES
The following values are returned by all functions:
=over 4
POD: Fix item numbering Newer pod2man considers =item [1-9] part of a numbered list, while =item 0 starts an unnumbered list. Add a zero effect formatting mark to override this. doc/apps/smime.pod around line 315: Expected text after =item, not a number ... PR#3146
2013-10-21 09:03:01 +00:00
=item Z<>0
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
The operation failed. In case of the add operation, it was tried to add
the same (identical) session twice. In case of the remove operation, the
session was not found in the cache.
POD: Fix item numbering Newer pod2man considers =item [1-9] part of a numbered list, while =item 0 starts an unnumbered list. Add a zero effect formatting mark to override this. doc/apps/smime.pod around line 315: Expected text after =item, not a number ... PR#3146
2013-10-21 09:03:01 +00:00
=item Z<>1
Fix nits in pod files. Add doc-nit-check to help find future issues. Make podchecker be almost clean. Remove trailing whitespace. Tab expansion Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-20 12:11:46 +00:00
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
The operation succeeded.
=back
=head1 SEE ALSO
Fix referenses in section 3 manuals Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1900)
2016-11-11 08:33:09 +00:00
L<ssl(7)>,
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-17 19:21:33 +00:00
L<SSL_CTX_set_session_cache_mode(3)>,
L<SSL_SESSION_free(3)>
Documenting session caching, 2nd step.
2001-02-04 18:05:27 +00:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 15:44:05 +00:00
=head1 COPYRIGHT
Copyright 2001-2016 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
Reference in a new issue Copy permalink