From: schwarze Date: Sun, 18 Feb 2018 23:34:01 +0000 (+0000) Subject: In ssl.h rev. 1.139 2018/02/17 15:19:43 and rev. 1.140 2018/02/17 15:32:20, X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=795d247b743539e7e61a7f6a1c1c83f9a2148f25;p=openbsd In ssl.h rev. 1.139 2018/02/17 15:19:43 and rev. 1.140 2018/02/17 15:32:20, jsing@ provided SSL_get_client_random(3), SSL_get_server_random(3), and SSL_SESSION_get_master_key(3). Import the documentation from OpenSSL, with some tweaks. --- diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile index 963e1037e9d..413d77c0a77 100644 --- a/lib/libssl/man/Makefile +++ b/lib/libssl/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.60 2018/02/18 22:18:59 schwarze Exp $ +# $OpenBSD: Makefile,v 1.61 2018/02/18 23:34:01 schwarze Exp $ .include @@ -72,6 +72,7 @@ MAN = BIO_f_ssl.3 \ SSL_get_certificate.3 \ SSL_get_ciphers.3 \ SSL_get_client_CA_list.3 \ + SSL_get_client_random.3 \ SSL_get_current_cipher.3 \ SSL_get_default_timeout.3 \ SSL_get_error.3 \ diff --git a/lib/libssl/man/SSL_get_client_random.3 b/lib/libssl/man/SSL_get_client_random.3 new file mode 100644 index 00000000000..8ab663846a6 --- /dev/null +++ b/lib/libssl/man/SSL_get_client_random.3 @@ -0,0 +1,146 @@ +.\" $OpenBSD: SSL_get_client_random.3,v 1.1 2018/02/18 23:34:01 schwarze Exp $ +.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 +.\" +.\" This file was written by Nick Mathewson +.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: February 18 2018 $ +.Dt SSL_GET_CLIENT_RANDOM 3 +.Os +.Sh NAME +.Nm SSL_get_client_random , +.Nm SSL_get_server_random , +.Nm SSL_SESSION_get_master_key +.Nd get internal TLS handshake random values and master key +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft size_t +.Fo SSL_get_client_random +.Fa "const SSL *ssl" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Ft size_t +.Fo SSL_get_server_random +.Fa "const SSL *ssl" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Ft size_t +.Fo SSL_SESSION_get_master_key +.Fa "const SSL_SESSION *session" +.Fa "unsigned char *out" +.Fa "size_t outlen" +.Fc +.Sh DESCRIPTION +.Fn SSL_get_client_random +extracts the random value that was sent from the client to the server +during the initial TLS handshake. +It copies at most +.Fa outlen +bytes of this value into the buffer +.Fa out . +If +.Fa outlen +is zero, nothing is copied. +.Pp +.Fn SSL_get_server_random +behaves the same, but extracts the random value that was sent +from the server to the client during the initial TLS handshake. +.Pp +.Fn SSL_SESSION_get_master_key +behaves the same, but extracts the master secret used to guarantee the +security of the TLS session. +The security of the TLS session depends on keeping the master key +secret: do not expose it, or any information about it, to anybody. +To calculate another secret value that depends on the master secret, +use +.Xr SSL_export_keying_material 3 +instead. +.Pp +All these functions expose internal values from the TLS handshake, +for use in low-level protocols. +Avoid using them unless implementing a feature +that requires access to the internal protocol details. +.Pp +Despite the names of +.Fn SSL_get_client_random +and +.Fn 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 protocol. +.Pp +In current versions of the TLS protocols, +the length of client_random and server_random is always +.Dv SSL3_RANDOM_SIZE +bytes. +Support for other +.Fa outlen +arguments is provided for the unlikely event that a future +version or variant of TLS uses some other length. +.Pp +Finally, though the client_random and server_random values are called +.Dq random , +many TLS implementations generate four bytes of those values +based on their view of the current time. +.Sh RETURN VALUES +If +.Fa outlen +is greater than 0, these functions return the number of bytes +actually copied, which is less than or equal to +.Fa outlen . +If +.Fa outlen +is 0, these functions return the maximum number of bytes they would +copy \(em that is, the length of the underlying field. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_export_keying_material 3 , +.Xr SSL_SESSION_get_id 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_SESSION_new 3