Commit 858618e7 authored by Nick Mathewson's avatar Nick Mathewson Committed by Matt Caswell
Browse files

Add new functions to extract {client,server}_random, master_key 



Tor uses these values to implement a low-rent clone of RFC 5705 (which,
in our defense, we came up with before RFC 5705 existed).  But now that
ssl_st is opaque, we need another way to get at them.

Includes documentation, with suitable warnings about not actually
using these functions.

Signed-off-by: default avatarNick Mathewson <nickm@torproject.org>
Signed-off-by: default avatarMatt Caswell <matt@openssl.org>
Reviewed-by: default avatarTim Hudson <tjh@openssl.org>
parent 9ef17514

doc/ssl/SSL_get_client_random.pod

0 → 100644
+73 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key



=head1 SYNOPSIS



 #include <openssl/ssl.h>



 int SSL_get_client_random(const SSL *ssl, unsigned char *out, int outlen);

 int SSL_get_server_random(const SSL *ssl, unsigned char *out, int outlen);

 int SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, int outlen);



=head1 DESCRIPTION



SSL_get_client_random() extracts the random value sent from the client

to the server during the initial SSL/TLS handshake.  It copies this

value into the buffer provided in B<out>, which must have at least

B<outlen> bytes available. It returns the total number of bytes that were

actually copied.

If B<outlen> is less than zero, SSL_get_client_random() copies nothing, and

returns the total size of the client_random value.



SSL_get_server_random() behaves the same, but extracts the random value

sent from the server to the client during the initial SSL/TLS handshake.



SSL_SESSION_get_master_key() behaves the same, but extracts the master

secret used to guarantee the security of the SSL/TLS session.  This one

can be dangerous if misused; see NOTES below.





=head1 NOTES



You probably shouldn't use these functions.



These functions expose internal values from the TLS handshake, for

use in low-level protocols.  You probably should not use them, unless

you are implementing something that needs access to the internal protocol

details.



Despite the names of SSL_get_client_random() and SSL_get_server_random(), they

ARE NOT random number generators.  Instead, they return the mostly-random values that

were already generated and used in the TLS protoccol.  Using them

in place of RAND_bytes() would be grossly foolish.



The security of your TLS session depends on keeping the master key secret:

do not expose it, or any information about it, to anybody.

If you need to calculate another secret value that depends on the master

secret, you should probably use SSL_export_keying_material() instead, and

forget that you ever saw these functions.



Finally, though the "client_random" and "server_random" values are called

"random", many TLS implementations will generate four bytes of those

values based on their view of the current time.





=head1 RETURN VALUES



If B<outlen> is at least 0, these functions return the number of bytes

actually copied, which will be less than or equal to B<outlen>.



If B<outlen> is less than 0, these functions return the maximum number

of bytes they would copy--that is, the length of the underlying field.



=head1 SEE ALSO



L<ssl(3)|ssl(3)>,

L<RAND_bytes(3)|RAND_bytes(3)>,

L<SSL_export_keying_material(3)|SSL_export_keying_material(3)>





=cut

include/openssl/ssl.h

+4 −0
Original line number Diff line number Diff line
@@ -1652,6 +1652,10 @@ void SSL_set_state(SSL *ssl, int state); 
void SSL_set_verify_result(SSL *ssl, long v);

__owur long SSL_get_verify_result(const SSL *ssl);



__owur int SSL_get_client_random(const SSL *ssl, unsigned char *out, int outlen);

__owur int SSL_get_server_random(const SSL *ssl, unsigned char *out, int outlen);

__owur int SSL_SESSION_get_master_key(const SSL_SESSION *ssl, unsigned char *out, int outlen);



__owur int SSL_set_ex_data(SSL *ssl, int idx, void *data);

void *SSL_get_ex_data(const SSL *ssl, int idx);

__owur int SSL_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,

ssl/ssl_lib.c

+31 −0
Original line number Diff line number Diff line
@@ -2897,6 +2897,37 @@ long SSL_get_verify_result(const SSL *ssl) 
    return (ssl->verify_result);

}



int SSL_get_client_random(const SSL *ssl, unsigned char *out, int outlen)

{

    if (outlen < 0)

        return sizeof(ssl->s3->client_random);

    if (outlen > sizeof(ssl->s3->client_random))

        outlen = sizeof(ssl->s3->client_random);

    memcpy(out, ssl->s3->client_random, outlen);

    return (outlen);

}



int SSL_get_server_random(const SSL *ssl, unsigned char *out, int outlen)

{

    if (outlen < 0)

        return sizeof(ssl->s3->server_random);

    if (outlen > sizeof(ssl->s3->server_random))

        outlen = sizeof(ssl->s3->server_random);

    memcpy(out, ssl->s3->server_random, outlen);

    return (outlen);

}



int SSL_SESSION_get_master_key(const SSL_SESSION *session,

                               unsigned char *out, int outlen)

{

    if (outlen < 0)

        return session->master_key_length;

    if (outlen > session->master_key_length)

        outlen = session->master_key_length;

    memcpy(out, session->master_key, outlen);

    return (outlen);

}



int SSL_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,

                         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func)

{