105901b04Schristos=pod 205901b04Schristos 305901b04Schristos=head1 NAME 405901b04Schristos 505901b04SchristosSSL_export_keying_material, 605901b04SchristosSSL_export_keying_material_early 705901b04Schristos- obtain keying material for application use 805901b04Schristos 905901b04Schristos=head1 SYNOPSIS 1005901b04Schristos 1105901b04Schristos #include <openssl/ssl.h> 1205901b04Schristos 1305901b04Schristos int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen, 1405901b04Schristos const char *label, size_t llen, 1505901b04Schristos const unsigned char *context, 1605901b04Schristos size_t contextlen, int use_context); 1705901b04Schristos 1805901b04Schristos int SSL_export_keying_material_early(SSL *s, unsigned char *out, size_t olen, 1905901b04Schristos const char *label, size_t llen, 2005901b04Schristos const unsigned char *context, 2105901b04Schristos size_t contextlen); 2205901b04Schristos 2305901b04Schristos=head1 DESCRIPTION 2405901b04Schristos 2505901b04SchristosDuring the creation of a TLS or DTLS connection shared keying material is 2605901b04Schristosestablished between the two endpoints. The functions 2705901b04SchristosSSL_export_keying_material() and SSL_export_keying_material_early() enable an 2805901b04Schristosapplication to use some of this keying material for its own purposes in 2905901b04Schristosaccordance with RFC5705 (for TLSv1.2 and below) or RFC8446 (for TLSv1.3). 3005901b04Schristos 3105901b04SchristosSSL_export_keying_material() derives keying material using 3205901b04Schristosthe F<exporter_master_secret> established in the handshake. 3305901b04Schristos 3405901b04SchristosSSL_export_keying_material_early() is only usable with TLSv1.3, and derives 3505901b04Schristoskeying material using the F<early_exporter_master_secret> (as defined in the 3605901b04SchristosTLS 1.3 RFC). For the client, the F<early_exporter_master_secret> is only 3705901b04Schristosavailable when the client attempts to send 0-RTT data. For the server, it is 3805901b04Schristosonly available when the server accepts 0-RTT data. 3905901b04Schristos 4005901b04SchristosAn application may need to securely establish the context within which this 4105901b04Schristoskeying material will be used. For example this may include identifiers for the 4205901b04Schristosapplication session, application algorithms or parameters, or the lifetime of 4305901b04Schristosthe context. The context value is left to the application but must be the same 4405901b04Schristoson both sides of the communication. 4505901b04Schristos 4605901b04SchristosFor a given SSL connection B<s>, B<olen> bytes of data will be written to 4705901b04SchristosB<out>. The application specific context should be supplied in the location 4805901b04Schristospointed to by B<context> and should be B<contextlen> bytes long. Provision of 4905901b04Schristosa context is optional. If the context should be omitted entirely then 5005901b04SchristosB<use_context> should be set to 0. Otherwise it should be any other value. If 5105901b04SchristosB<use_context> is 0 then the values of B<context> and B<contextlen> are ignored. 5205901b04SchristosNote that in TLSv1.2 and below a zero length context is treated differently from 5305901b04Schristosno context at all, and will result in different keying material being returned. 5405901b04SchristosIn TLSv1.3 a zero length context is that same as no context at all and will 5505901b04Schristosresult in the same keying material being returned. 5605901b04Schristos 5705901b04SchristosAn application specific label should be provided in the location pointed to by 5805901b04SchristosB<label> and should be B<llen> bytes long. Typically this will be a value from 5905901b04Schristosthe IANA Exporter Label Registry 6005901b04Schristos(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>). 6105901b04SchristosAlternatively labels beginning with "EXPERIMENTAL" are permitted by the standard 62fa9f2818Schristosto be used without registration. TLSv1.3 imposes a maximum label length of 63fa9f2818Schristos249 bytes. 6405901b04Schristos 6505901b04SchristosNote that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and 6605901b04Schristosabove. Attempting to use it in SSLv3 will result in an error. 6705901b04Schristos 6805901b04Schristos=head1 RETURN VALUES 6905901b04Schristos 7005901b04SchristosSSL_export_keying_material() returns 0 or -1 on failure or 1 on success. 7105901b04Schristos 7205901b04SchristosSSL_export_keying_material_early() returns 0 on failure or 1 on success. 7305901b04Schristos 74*66bae5e7Schristos=head1 SEE ALSO 75*66bae5e7Schristos 76*66bae5e7SchristosL<ssl(7)> 77*66bae5e7Schristos 7805901b04Schristos=head1 HISTORY 7905901b04Schristos 80fa9f2818SchristosThe SSL_export_keying_material_early() function was added in OpenSSL 1.1.1. 8105901b04Schristos 8205901b04Schristos=head1 COPYRIGHT 8305901b04Schristos 8405901b04SchristosCopyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. 8505901b04Schristos 86*66bae5e7SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 8705901b04Schristosthis file except in compliance with the License. You can obtain a copy 8805901b04Schristosin the file LICENSE in the source distribution or at 8905901b04SchristosL<https://www.openssl.org/source/license.html>. 9005901b04Schristos 9105901b04Schristos=cut 92