|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_generate_session_id, SSL_set_generate_session_id,
|
|
Packit |
c4476c |
SSL_has_matching_session_id, GEN_SESSION_CB
|
|
Packit |
c4476c |
- manipulate generation of SSL session IDs (server only)
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ssl.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef int (*GEN_SESSION_CB)(SSL *ssl, unsigned char *id,
|
|
Packit |
c4476c |
unsigned int *id_len);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb);
|
|
Packit |
c4476c |
int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb);
|
|
Packit |
c4476c |
int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id,
|
|
Packit |
c4476c |
unsigned int id_len);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_generate_session_id() sets the callback function for generating
|
|
Packit |
c4476c |
new session ids for SSL/TLS sessions for B<ctx> to be B<cb>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set_generate_session_id() sets the callback function for generating
|
|
Packit |
c4476c |
new session ids for SSL/TLS sessions for B<ssl> to be B<cb>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_has_matching_session_id() checks, whether a session with id B<id>
|
|
Packit |
c4476c |
(of length B<id_len>) is already contained in the internal session cache
|
|
Packit |
c4476c |
of the parent context of B<ssl>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
When a new session is established between client and server, the server
|
|
Packit |
c4476c |
generates a session id. The session id is an arbitrary sequence of bytes.
|
|
Packit |
c4476c |
The length of the session id is between 1 and 32 bytes. The session id is not
|
|
Packit |
c4476c |
security critical but must be unique for the server. Additionally, the session id is
|
|
Packit |
c4476c |
transmitted in the clear when reusing the session so it must not contain
|
|
Packit |
c4476c |
sensitive information.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Without a callback being set, an OpenSSL server will generate a unique
|
|
Packit |
c4476c |
session id from pseudo random numbers of the maximum possible length.
|
|
Packit |
c4476c |
Using the callback function, the session id can be changed to contain
|
|
Packit |
c4476c |
additional information like e.g. a host id in order to improve load balancing
|
|
Packit |
c4476c |
or external caching techniques.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The callback function receives a pointer to the memory location to put
|
|
Packit |
c4476c |
B<id> into and a pointer to the maximum allowed length B<id_len>. The
|
|
Packit |
c4476c |
buffer at location B<id> is only guaranteed to have the size B<id_len>.
|
|
Packit |
c4476c |
The callback is only allowed to generate a shorter id and reduce B<id_len>;
|
|
Packit |
c4476c |
the callback B<must never> increase B<id_len> or write to the location
|
|
Packit |
c4476c |
B<id> exceeding the given limit.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The location B<id> is filled with 0x00 before the callback is called, so the
|
|
Packit |
c4476c |
callback may only fill part of the possible length and leave B<id_len>
|
|
Packit |
c4476c |
untouched while maintaining reproducibility.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Since the sessions must be distinguished, session ids must be unique.
|
|
Packit |
c4476c |
Without the callback a random number is used, so that the probability
|
|
Packit |
c4476c |
of generating the same session id is extremely small (2^256 for SSLv3/TLSv1).
|
|
Packit |
c4476c |
In order to assure the uniqueness of the generated session id, the callback must call
|
|
Packit |
c4476c |
SSL_has_matching_session_id() and generate another id if a conflict occurs.
|
|
Packit |
c4476c |
If an id conflict is not resolved, the handshake will fail.
|
|
Packit |
c4476c |
If the application codes e.g. a unique host id, a unique process number, and
|
|
Packit |
c4476c |
a unique sequence number into the session id, uniqueness could easily be
|
|
Packit |
c4476c |
achieved without randomness added (it should however be taken care that
|
|
Packit |
c4476c |
no confidential information is leaked this way). If the application can not
|
|
Packit |
c4476c |
guarantee uniqueness, it is recommended to use the maximum B<id_len> and
|
|
Packit |
c4476c |
fill in the bytes not used to code special information with random data
|
|
Packit |
c4476c |
to avoid collisions.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_has_matching_session_id() will only query the internal session cache,
|
|
Packit |
c4476c |
not the external one. Since the session id is generated before the
|
|
Packit |
c4476c |
handshake is completed, it is not immediately added to the cache. If
|
|
Packit |
c4476c |
another thread is using the same internal session cache, a race condition
|
|
Packit |
c4476c |
can occur in that another thread generates the same session id.
|
|
Packit |
c4476c |
Collisions can also occur when using an external session cache, since
|
|
Packit |
c4476c |
the external cache is not tested with SSL_has_matching_session_id()
|
|
Packit |
c4476c |
and the same race condition applies.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The callback must return 0 if it cannot generate a session id for whatever
|
|
Packit |
c4476c |
reason and return 1 on success.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
|
|
Packit |
c4476c |
always return 1.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_has_matching_session_id() returns 1 if another session with the
|
|
Packit |
c4476c |
same id is already in the cache.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 EXAMPLES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The callback function listed will generate a session id with the
|
|
Packit |
c4476c |
server id given, and will fill the rest with pseudo random bytes:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
const char session_id_prefix = "www-18";
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#define MAX_SESSION_ID_ATTEMPTS 10
|
|
Packit |
c4476c |
static int generate_session_id(SSL *ssl, unsigned char *id,
|
|
Packit |
c4476c |
unsigned int *id_len)
|
|
Packit |
c4476c |
{
|
|
Packit |
c4476c |
unsigned int count = 0;
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
do {
|
|
Packit |
c4476c |
RAND_pseudo_bytes(id, *id_len);
|
|
Packit |
c4476c |
/*
|
|
Packit |
c4476c |
* Prefix the session_id with the required prefix. NB: If our
|
|
Packit |
c4476c |
* prefix is too long, clip it - but there will be worse effects
|
|
Packit |
c4476c |
* anyway, eg. the server could only possibly create 1 session
|
|
Packit |
c4476c |
* ID (ie. the prefix!) so all future session negotiations will
|
|
Packit |
c4476c |
* fail due to conflicts.
|
|
Packit |
c4476c |
*/
|
|
Packit |
c4476c |
memcpy(id, session_id_prefix, strlen(session_id_prefix) < *id_len ?
|
|
Packit |
c4476c |
strlen(session_id_prefix) : *id_len);
|
|
Packit |
c4476c |
} while (SSL_has_matching_session_id(ssl, id, *id_len)
|
|
Packit |
c4476c |
&& ++count < MAX_SESSION_ID_ATTEMPTS);
|
|
Packit |
c4476c |
if (count >= MAX_SESSION_ID_ATTEMPTS)
|
|
Packit |
c4476c |
return 0;
|
|
Packit |
c4476c |
return 1;
|
|
Packit |
c4476c |
}
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<ssl(7)>, L<SSL_get_version(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|