From: Matt Caswell <matt@openssl.org>
Date: Wed, 21 Jun 2017 12:55:02 +0000 (+0100)
Subject: Add documentation for the SSL_export_keying_material() function
X-Git-Tag: OpenSSL_1_1_1-pre1~1225
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=23cec1f4b4801c643853bf2eb07d7eae5f4fe7cb;p=openssl
Add documentation for the SSL_export_keying_material() function
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3735)
---
diff --git a/doc/man3/SSL_export_keying_material.pod b/doc/man3/SSL_export_keying_material.pod
new file mode 100644
index 0000000000..ccb99ec9a8
--- /dev/null
+++ b/doc/man3/SSL_export_keying_material.pod
@@ -0,0 +1,61 @@
+=pod
+
+=head1 NAME
+
+SSL_export_keying_material - obtain keying material for application use
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
+ const char *label, size_t llen,
+ const unsigned char *context,
+ size_t contextlen, int use_context);
+
+=head1 DESCRIPTION
+
+During the creation of a TLS or DTLS connection shared keying material is
+established between the two endpoints. The function SSL_export_keying_material()
+enables an application to use some of this keying material for its own purposes
+in accordance with RFC5705.
+
+An application may need to securely establish the context within which this
+keying material will be used. For example this may include identifiers for the
+application session, application algorithms or parameters, or the lifetime of
+the context. The context value is left to the application but must be the same
+on both sides of the communication.
+
+For a given SSL connection B<s>, B<olen> bytes of data will be written to
+B<out>. The application specific context should be supplied in the location
+pointed to by B<context> and should be B<contextlen> bytes long. Provision of
+a context is optional. If the context should be omitted entirely then
+B<use_context> should be set to 0. Otherwise it should be any other value. If
+B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored.
+Note that a zero length context is treated differently to no context at all, and
+will result in different keying material being returned.
+
+An application specific label should be provided in the location pointed to by
+B<label> and should be B<llen> bytes long. Typically this will be a value from
+the IANA Exporter Label Registry
+(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>).
+Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
+to be used without registration.
+
+Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and
+above. Attempting to use it in SSLv3 will result in an error.
+
+=head1 RETURN VALUES
+
+SSL_export_keying_material() returns 0 or -1 on failure or 1 on success.
+
+=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<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/include/openssl/tls1.h b/include/openssl/tls1.h
index 156d3bf398..0878851569 100644
--- a/include/openssl/tls1.h
+++ b/include/openssl/tls1.h
@@ -212,12 +212,12 @@ __owur int SSL_get_servername_type(const SSL *s);
* as specified in RFC 5705. It writes |olen| bytes to |out| given a label and
* optional context. (Since a zero length context is allowed, the |use_context|
* flag controls whether a context is included.) It returns 1 on success and
- * zero otherwise.
+ * 0 or -1 otherwise.
*/
__owur int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
- const char *label, size_t llen,
- const unsigned char *p, size_t plen,
- int use_context);
+ const char *label, size_t llen,
+ const unsigned char *context,
+ size_t contextlen, int use_context);
int SSL_get_peer_signature_type_nid(const SSL *s, int *pnid);
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index d8dd45eb5b..9add3bea11 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -2556,15 +2556,15 @@ void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
const char *label, size_t llen,
- const unsigned char *p, size_t plen,
+ const unsigned char *context, size_t contextlen,
int use_context)
{
if (s->version < TLS1_VERSION && s->version != DTLS1_BAD_VER)
return -1;
return s->method->ssl3_enc->export_keying_material(s, out, olen, label,
- llen, p, plen,
- use_context);
+ llen, context,
+ contextlen, use_context);
}
static unsigned long ssl_session_hash(const SSL_SESSION *a)