|
0 |
=pod
|
|
1 |
|
|
2 |
=head1 NAME
|
|
3 |
|
|
4 |
SSL_export_keying_material - obtain keying material for application use
|
|
5 |
|
|
6 |
=head1 SYNOPSIS
|
|
7 |
|
|
8 |
#include <openssl/ssl.h>
|
|
9 |
|
|
10 |
int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
|
|
11 |
const char *label, size_t llen,
|
|
12 |
const unsigned char *context,
|
|
13 |
size_t contextlen, int use_context);
|
|
14 |
|
|
15 |
=head1 DESCRIPTION
|
|
16 |
|
|
17 |
During the creation of a TLS or DTLS connection shared keying material is
|
|
18 |
established between the two endpoints. The function SSL_export_keying_material()
|
|
19 |
enables an application to use some of this keying material for its own purposes
|
|
20 |
in accordance with RFC5705.
|
|
21 |
|
|
22 |
An application may need to securely establish the context within which this
|
|
23 |
keying material will be used. For example this may include identifiers for the
|
|
24 |
application session, application algorithms or parameters, or the lifetime of
|
|
25 |
the context. The context value is left to the application but must be the same
|
|
26 |
on both sides of the communication.
|
|
27 |
|
|
28 |
For a given SSL connection B<s>, B<olen> bytes of data will be written to
|
|
29 |
B<out>. The application specific context should be supplied in the location
|
|
30 |
pointed to by B<context> and should be B<contextlen> bytes long. Provision of
|
|
31 |
a context is optional. If the context should be omitted entirely then
|
|
32 |
B<use_context> should be set to 0. Otherwise it should be any other value. If
|
|
33 |
B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored.
|
|
34 |
Note that a zero length context is treated differently to no context at all, and
|
|
35 |
will result in different keying material being returned.
|
|
36 |
|
|
37 |
An application specific label should be provided in the location pointed to by
|
|
38 |
B<label> and should be B<llen> bytes long. Typically this will be a value from
|
|
39 |
the IANA Exporter Label Registry
|
|
40 |
(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>).
|
|
41 |
Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
|
|
42 |
to be used without registration.
|
|
43 |
|
|
44 |
Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and
|
|
45 |
above. Attempting to use it in SSLv3 will result in an error.
|
|
46 |
|
|
47 |
=head1 RETURN VALUES
|
|
48 |
|
|
49 |
SSL_export_keying_material() returns 0 or -1 on failure or 1 on success.
|
|
50 |
|
|
51 |
=head1 COPYRIGHT
|
|
52 |
|
|
53 |
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
54 |
|
|
55 |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
56 |
this file except in compliance with the License. You can obtain a copy
|
|
57 |
in the file LICENSE in the source distribution or at
|
|
58 |
L<https://www.openssl.org/source/license.html>.
|
|
59 |
|
|
60 |
=cut
|