124 lines
5.6 KiB
HTML
124 lines
5.6 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>SSL_export_keying_material</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>SSL_export_keying_material,
|
||
|
SSL_export_keying_material_early
|
||
|
- obtain keying material for application use</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/ssl.h></pre>
|
||
|
<pre>
|
||
|
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);</pre>
|
||
|
<pre>
|
||
|
int SSL_export_keying_material_early(SSL *s, unsigned char *out, size_t olen,
|
||
|
const char *label, size_t llen,
|
||
|
const unsigned char *context,
|
||
|
size_t contextlen);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>During the creation of a TLS or DTLS connection shared keying material is
|
||
|
established between the two endpoints. The functions
|
||
|
<code>SSL_export_keying_material()</code> and <code>SSL_export_keying_material_early()</code> enable an
|
||
|
application to use some of this keying material for its own purposes in
|
||
|
accordance with <a href="http://www.ietf.org/rfc/rfc5705.txt" class="rfc">RFC5705</a> (for TLSv1.2 and below) or <a href="http://www.ietf.org/rfc/rfc8446.txt" class="rfc">RFC8446</a> (for TLSv1.3).</p>
|
||
|
<p><code>SSL_export_keying_material()</code> derives keying material using
|
||
|
the <em class="file">exporter_master_secret</em> established in the handshake.</p>
|
||
|
<p><code>SSL_export_keying_material_early()</code> is only usable with TLSv1.3, and derives
|
||
|
keying material using the <em class="file">early_exporter_master_secret</em> (as defined in the
|
||
|
TLS 1.3 RFC). For the client, the <em class="file">early_exporter_master_secret</em> is only
|
||
|
available when the client attempts to send 0-RTT data. For the server, it is
|
||
|
only available when the server accepts 0-RTT data.</p>
|
||
|
<p>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.</p>
|
||
|
<p>For a given SSL connection <strong>s</strong>, <strong>olen</strong> bytes of data will be written to
|
||
|
<strong>out</strong>. The application specific context should be supplied in the location
|
||
|
pointed to by <strong>context</strong> and should be <strong>contextlen</strong> bytes long. Provision of
|
||
|
a context is optional. If the context should be omitted entirely then
|
||
|
<strong>use_context</strong> should be set to 0. Otherwise it should be any other value. If
|
||
|
<strong>use_context</strong> is 0 then the values of <strong>context</strong> and <strong>contextlen</strong> are ignored.
|
||
|
Note that in TLSv1.2 and below a zero length context is treated differently from
|
||
|
no context at all, and will result in different keying material being returned.
|
||
|
In TLSv1.3 a zero length context is that same as no context at all and will
|
||
|
result in the same keying material being returned.</p>
|
||
|
<p>An application specific label should be provided in the location pointed to by
|
||
|
<strong>label</strong> and should be <strong>llen</strong> bytes long. Typically this will be a value from
|
||
|
the IANA Exporter Label Registry
|
||
|
(<a href="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels">https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels</a>).
|
||
|
Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
|
||
|
to be used without registration. TLSv1.3 imposes a maximum label length of
|
||
|
249 bytes.</p>
|
||
|
<p>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.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>SSL_export_keying_material()</code> returns 0 or -1 on failure or 1 on success.</p>
|
||
|
<p><code>SSL_export_keying_material_early()</code> returns 0 on failure or 1 on success.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>ssl(7)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>The <code>SSL_export_keying_material_early()</code> function was added in OpenSSL 1.1.1.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>Licensed under the Apache License 2.0 (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
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|