1.\" $OpenBSD: SSL_CTX_set_tlsext_use_srtp.3,v 1.6 2021/06/11 19:41:39 jmc Exp $ 2.\" full merge up to: OpenSSL b0edda11 Mar 20 13:00:17 2018 +0000 3.\" 4.\" This file was written by Matt Caswell <matt@openssl.org>. 5.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: June 11 2021 $ 52.Dt SSL_CTX_SET_TLSEXT_USE_SRTP 3 53.Os 54.Sh NAME 55.Nm SSL_CTX_set_tlsext_use_srtp , 56.Nm SSL_set_tlsext_use_srtp , 57.Nm SSL_get_srtp_profiles , 58.Nm SSL_get_selected_srtp_profile 59.Nd Configure and query SRTP support 60.Sh SYNOPSIS 61.In openssl/srtp.h 62.Ft int 63.Fo SSL_CTX_set_tlsext_use_srtp 64.Fa "SSL_CTX *ctx" 65.Fa "const char *profiles" 66.Fc 67.Ft int 68.Fo SSL_set_tlsext_use_srtp 69.Fa "SSL *ssl" 70.Fa "const char *profiles" 71.Fc 72.Ft STACK_OF(SRTP_PROTECTION_PROFILE) * 73.Fo SSL_get_srtp_profiles 74.Fa "SSL *ssl" 75.Fc 76.Ft SRTP_PROTECTION_PROFILE * 77.Fo SSL_get_selected_srtp_profile 78.Fa "SSL *ssl" 79.Fc 80.Sh DESCRIPTION 81SRTP is the Secure Real-Time Transport Protocol. 82OpenSSL implements support for the "use_srtp" DTLS extension 83defined in RFC 5764. 84This provides a mechanism for establishing SRTP keying material, 85algorithms and parameters using DTLS. 86This capability may be used as part of an implementation that 87conforms to RFC 5763. 88OpenSSL does not implement SRTP itself or RFC 5763. 89Note that OpenSSL does not support the use of SRTP Master Key 90Identifiers (MKIs). 91Also note that this extension is only supported in DTLS. 92Any SRTP configuration is ignored if a TLS connection is attempted. 93.Pp 94An OpenSSL client wishing to send the "use_srtp" extension should call 95.Fn SSL_CTX_set_tlsext_use_srtp 96to set its use for all 97.Vt SSL 98objects subsequently created from 99.Fa ctx . 100Alternatively a client may call 101.Fn SSL_set_tlsext_use_srtp 102to set its use for an individual 103.Vt SSL 104object. 105The 106.Fa profiles 107parameter should point to a NUL-terminated, colon delimited list of 108SRTP protection profile names. 109.Pp 110The currently supported protection profile names are: 111.Bl -tag -width Ds 112.It Dv SRTP_AES128_CM_SHA1_80 113This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC 5764. 114.It Dv SRTP_AES128_CM_SHA1_32 115This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC 5764. 116.It Dv SRTP_AEAD_AES_128_GCM 117This corresponds to SRTP_AEAD_AES_128_GCM defined in RFC 7714. 118.It Dv SRTP_AEAD_AES_256_GCM 119This corresponds to SRTP_AEAD_AES_256_GCM defined in RFC 7714. 120.El 121.Pp 122Supplying an unrecognised protection profile name results in an error. 123.Pp 124An OpenSSL server wishing to support the "use_srtp" extension should 125also call 126.Fn SSL_CTX_set_tlsext_use_srtp 127or 128.Fn SSL_set_tlsext_use_srtp 129to indicate the protection profiles that it is willing to negotiate. 130.Pp 131The currently configured list of protection profiles for either a client 132or a server can be obtained by calling 133.Fn SSL_get_srtp_profiles . 134This returns a stack of 135.Vt SRTP_PROTECTION_PROFILE 136objects. 137The memory pointed to in the return value of this function should not be 138freed by the caller. 139.Pp 140After a handshake has been completed, the negotiated SRTP protection 141profile (if any) can be obtained (on the client or the server) by 142calling 143.Fn SSL_get_selected_srtp_profile . 144This function returns 145.Dv NULL 146if no SRTP protection profile was negotiated. 147The memory returned from this function should not be freed by the 148caller. 149.Pp 150If an SRTP protection profile has been successfully negotiated, 151then the SRTP keying material (on both the client and server) 152should be obtained by calling 153.Xr SSL_export_keying_material 3 154with a 155.Fa label 156of 157.Qq EXTRACTOR-dtls_srtp , 158a 159.Fa context 160of 161.Dv NULL , 162and a 163.Fa use_context 164argument of 0. 165The total length of keying material obtained should be equal to two 166times the sum of the master key length and the salt length as defined 167for the protection profile in use. 168This provides the client write master key, the server write master key, 169the client write master salt and the server write master salt in that 170order. 171.Sh RETURN VALUES 172Contrary to OpenSSL conventions, 173.Fn SSL_CTX_set_tlsext_use_srtp 174and 175.Fn SSL_set_tlsext_use_srtp 176return 0 on success or 1 on error. 177.Pp 178.Fn SSL_get_srtp_profiles 179returns a stack of 180.Vt SRTP_PROTECTION_PROFILE 181objects on success or 182.Dv NULL 183on error or if no protection profiles have been configured. 184.Pp 185.Fn SSL_get_selected_srtp_profile 186returns a pointer to an 187.Vt SRTP_PROTECTION_PROFILE 188object if one has been negotiated or 189.Dv NULL 190otherwise. 191.Sh SEE ALSO 192.Xr ssl 3 , 193.Xr SSL_export_keying_material 3 194.Sh HISTORY 195These functions first appeared in OpenSSL 1.0.1 196and have been available since 197.Ox 5.3 . 198