1.\" $OpenBSD: SSL_export_keying_material.3,v 1.3 2019/06/12 09:36:30 schwarze Exp $ 2.\" OpenSSL a599574b Jun 28 17:18:27 2017 +0100 3.\" OpenSSL 23cec1f4 Jun 21 13:55:02 2017 +0100 4.\" 5.\" This file was written by Matt Caswell <matt@openssl.org>. 6.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 12 2019 $ 53.Dt SSL_EXPORT_KEYING_MATERIAL 3 54.Os 55.Sh NAME 56.Nm SSL_export_keying_material 57.Nd obtain keying material for application use 58.Sh SYNOPSIS 59.In openssl/ssl.h 60.Ft int 61.Fo SSL_export_keying_material 62.Fa "SSL *s" 63.Fa "unsigned char *out" 64.Fa "size_t olen" 65.Fa "const char *label" 66.Fa "size_t llen" 67.Fa "const unsigned char *context" 68.Fa "size_t contextlen" 69.Fa "int use_context" 70.Fc 71.Sh DESCRIPTION 72During the creation of a TLS or DTLS connection, 73shared keying material is established between the two endpoints. 74The function 75.Fn SSL_export_keying_material 76enables an application to use some of this keying material 77for its own purposes in accordance with RFC 5705. 78.Pp 79An application may need to securely establish the context 80within which this keying material will be used. 81For example, this may include identifiers for the application session, 82application algorithms or parameters, or the lifetime of the context. 83The context value is left to the application but must be the same on 84both sides of the communication. 85.Pp 86For a given SSL connection 87.Fa s , 88.Fa olen 89bytes of data will be written to 90.Fa out . 91The application specific context should be supplied 92in the location pointed to by 93.Fa context 94and should be 95.Fa contextlen 96bytes long. 97Provision of a context is optional. 98If the context should be omitted entirely, then 99.Fa use_context 100should be set to 0. 101Otherwise it should be any other value. 102If 103.Fa use_context 104is 0, then the values of 105.Fa context 106and 107.Fa contextlen 108are ignored. 109.Pp 110In TLSv1.2 and below, a zero length context is treated differently 111from no context at all, and will result in different keying material 112being returned. 113.Pp 114An application specific label should be provided in the location pointed 115to by 116.Fa label 117and should be 118.Fa llen 119bytes long. 120Typically this will be a value from the 121.Lk https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels "IANA Exporter Label Registry" . 122.Pp 123Alternatively, labels beginning with "EXPERIMENTAL" are permitted by the 124standard to be used without registration. 125.Sh RETURN VALUES 126.Fn SSL_export_keying_material 127returns 1 on success or 0 or -1 on failure. 128.Sh SEE ALSO 129.Xr ssl 3 130.Sh HISTORY 131.Fn SSL_export_keying_material 132first appeared in OpenSSL 1.0.1 and has been available since 133.Ox 5.3 . 134