secure/lib/libcrypto/man/SSL_CTX_set_tlsext_use_srtp.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SET_TLSEXT_USE_SRTP 3"
 136 .TH SSL_CTX_SET_TLSEXT_USE_SRTP 3 "2019-09-10" "1.1.1d" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set_tlsext_use_srtp, SSL_set_tlsext_use_srtp, SSL_get_srtp_profiles, SSL_get_selected_srtp_profile \&\- Configure and query SRTP support
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/srtp.h>
 147 \&
 148 \& int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles);
 149 \& int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles);
 150 \&
 151 \& STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl);
 152 \& SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\s-1SRTP\s0 is the Secure Real-Time Transport Protocol. OpenSSL implements support for
 157 the \*(L"use_srtp\*(R" \s-1DTLS\s0 extension defined in \s-1RFC5764.\s0 This provides a mechanism for
 158 establishing \s-1SRTP\s0 keying material, algorithms and parameters using \s-1DTLS.\s0 This
 159 capability may be used as part of an implementation that conforms to \s-1RFC5763.\s0
 160 OpenSSL does not implement \s-1SRTP\s0 itself or \s-1RFC5763.\s0 Note that OpenSSL does not
 161 support the use of \s-1SRTP\s0 Master Key Identifiers (MKIs). Also note that this
 162 extension is only supported in \s-1DTLS.\s0 Any \s-1SRTP\s0 configuration will be ignored if a
 163 \&\s-1TLS\s0 connection is attempted.
 164 .PP
 165 An OpenSSL client wishing to send the \*(L"use_srtp\*(R" extension should call
 166 \&\fBSSL_CTX_set_tlsext_use_srtp()\fR to set its use for all \s-1SSL\s0 objects subsequently
 167 created from an \s-1SSL_CTX.\s0 Alternatively a client may call
 168 \&\fBSSL_set_tlsext_use_srtp()\fR to set its use for an individual \s-1SSL\s0 object. The
 169 \&\fBprofiles\fR parameters should point to a NUL-terminated, colon delimited list of
 170 \&\s-1SRTP\s0 protection profile names.
 171 .PP
 172 The currently supported protection profile names are:
 173 .IP "\s-1SRTP_AES128_CM_SHA1_80\s0" 4
 174 .IX Item "SRTP_AES128_CM_SHA1_80"
 175 This corresponds to \s-1SRTP_AES128_CM_HMAC_SHA1_80\s0 defined in \s-1RFC5764.\s0
 176 .IP "\s-1SRTP_AES128_CM_SHA1_32\s0" 4
 177 .IX Item "SRTP_AES128_CM_SHA1_32"
 178 This corresponds to \s-1SRTP_AES128_CM_HMAC_SHA1_32\s0 defined in \s-1RFC5764.\s0
 179 .IP "\s-1SRTP_AEAD_AES_128_GCM\s0" 4
 180 .IX Item "SRTP_AEAD_AES_128_GCM"
 181 This corresponds to the profile of the same name defined in \s-1RFC7714.\s0
 182 .IP "\s-1SRTP_AEAD_AES_256_GCM\s0" 4
 183 .IX Item "SRTP_AEAD_AES_256_GCM"
 184 This corresponds to the profile of the same name defined in \s-1RFC7714.\s0
 185 .PP
 186 Supplying an unrecognised protection profile name will result in an error.
 187 .PP
 188 An OpenSSL server wishing to support the \*(L"use_srtp\*(R" extension should also call
 189 \&\fBSSL_CTX_set_tlsext_use_srtp()\fR or \fBSSL_set_tlsext_use_srtp()\fR to indicate the
 190 protection profiles that it is willing to negotiate.
 191 .PP
 192 The currently configured list of protection profiles for either a client or a
 193 server can be obtained by calling \fBSSL_get_srtp_profiles()\fR. This returns a stack
 194 of \s-1SRTP_PROTECTION_PROFILE\s0 objects. The memory pointed to in the return value of
 195 this function should not be freed by the caller.
 196 .PP
 197 After a handshake has been completed the negotiated \s-1SRTP\s0 protection profile (if
 198 any) can be obtained (on the client or the server) by calling
 199 \&\fBSSL_get_selected_srtp_profile()\fR. This function will return \s-1NULL\s0 if no \s-1SRTP\s0
 200 protection profile was negotiated. The memory returned from this function should
 201 not be freed by the caller.
 202 .PP
 203 If an \s-1SRTP\s0 protection profile has been successfully negotiated then the \s-1SRTP\s0
 204 keying material (on both the client and server) should be obtained via a call to
 205 \&\fBSSL_export_keying_material\fR\|(3). This call should provide a label value of
 206 \&\*(L"EXTRACTOR\-dtls_srtp\*(R" and a \s-1NULL\s0 context value (use_context is 0). The total
 207 length of keying material obtained should be equal to two times the sum of the
 208 master key length and the salt length as defined for the protection profile in
 209 use. This provides the client write master key, the server write master key, the
 210 client write master salt and the server write master salt in that order.
 211 .SH "RETURN VALUES"
 212 .IX Header "RETURN VALUES"
 213 \&\fBSSL_CTX_set_tlsext_use_srtp()\fR and \fBSSL_set_tlsext_use_srtp()\fR return 0 on success
 214 or 1 on error.
 215 .PP
 216 \&\fBSSL_get_srtp_profiles()\fR returns a stack of \s-1SRTP_PROTECTION_PROFILE\s0 objects on
 217 success or \s-1NULL\s0 on error or if no protection profiles have been configured.
 218 .PP
 219 \&\fBSSL_get_selected_srtp_profile()\fR returns a pointer to an \s-1SRTP_PROTECTION_PROFILE\s0
 220 object if one has been negotiated or \s-1NULL\s0 otherwise.
 221 .SH "SEE ALSO"
 222 .IX Header "SEE ALSO"
 223 \&\fBSSL_export_keying_material\fR\|(3)
 224 .SH "COPYRIGHT"
 225 .IX Header "COPYRIGHT"
 226 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
 227 .PP
 228 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 229 this file except in compliance with the License.  You can obtain a copy
 230 in the file \s-1LICENSE\s0 in the source distribution or at
 231 <https://www.openssl.org/source/license.html>.