secure/lib/libcrypto/man/SSL_CTX_set_tlsext_use_srtp.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_SET_TLSEXT_USE_SRTP 3"
 132 .TH SSL_CTX_SET_TLSEXT_USE_SRTP 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/srtp.h>
 143 \&
 144 \& int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles);
 145 \& int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles);
 146 \&
 147 \& STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl);
 148 \& SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\s-1SRTP\s0 is the Secure Real-Time Transport Protocol. OpenSSL implements support for
 153 the \*(L"use_srtp\*(R" \s-1DTLS\s0 extension defined in \s-1RFC5764.\s0 This provides a mechanism for
 154 establishing \s-1SRTP\s0 keying material, algorithms and parameters using \s-1DTLS.\s0 This
 155 capability may be used as part of an implementation that conforms to \s-1RFC5763.\s0
 156 OpenSSL does not implement \s-1SRTP\s0 itself or \s-1RFC5763.\s0 Note that OpenSSL does not
 157 support the use of \s-1SRTP\s0 Master Key Identifiers (MKIs). Also note that this
 158 extension is only supported in \s-1DTLS.\s0 Any \s-1SRTP\s0 configuration will be ignored if a
 159 \&\s-1TLS\s0 connection is attempted.
 160 .PP
 161 An OpenSSL client wishing to send the \*(L"use_srtp\*(R" extension should call
 162 \&\fISSL_CTX_set_tlsext_use_srtp()\fR to set its use for all \s-1SSL\s0 objects subsequently
 163 created from an \s-1SSL_CTX.\s0 Alternatively a client may call
 164 \&\fISSL_set_tlsext_use_srtp()\fR to set its use for an individual \s-1SSL\s0 object. The
 165 \&\fBprofiles\fR parameters should point to a NUL-terminated, colon delimited list of
 166 \&\s-1SRTP\s0 protection profile names.
 167 .PP
 168 The currently supported protection profile names are:
 169 .IP "\s-1SRTP_AES128_CM_SHA1_80\s0" 4
 170 .IX Item "SRTP_AES128_CM_SHA1_80"
 171 This corresponds to \s-1SRTP_AES128_CM_HMAC_SHA1_80\s0 defined in \s-1RFC5764.\s0
 172 .IP "\s-1SRTP_AES128_CM_SHA1_32\s0" 4
 173 .IX Item "SRTP_AES128_CM_SHA1_32"
 174 This corresponds to \s-1SRTP_AES128_CM_HMAC_SHA1_32\s0 defined in \s-1RFC5764.\s0
 175 .IP "\s-1SRTP_AEAD_AES_128_GCM\s0" 4
 176 .IX Item "SRTP_AEAD_AES_128_GCM"
 177 This corresponds to the profile of the same name defined in \s-1RFC7714.\s0
 178 .IP "\s-1SRTP_AEAD_AES_256_GCM\s0" 4
 179 .IX Item "SRTP_AEAD_AES_256_GCM"
 180 This corresponds to the profile of the same name defined in \s-1RFC7714.\s0
 181 .PP
 182 Supplying an unrecognised protection profile name will result in an error.
 183 .PP
 184 An OpenSSL server wishing to support the \*(L"use_srtp\*(R" extension should also call
 185 \&\fISSL_CTX_set_tlsext_use_srtp()\fR or \fISSL_set_tlsext_use_srtp()\fR to indicate the
 186 protection profiles that it is willing to negotiate.
 187 .PP
 188 The currently configured list of protection profiles for either a client or a
 189 server can be obtained by calling \fISSL_get_srtp_profiles()\fR. This returns a stack
 190 of \s-1SRTP_PROTECTION_PROFILE\s0 objects. The memory pointed to in the return value of
 191 this function should not be freed by the caller.
 192 .PP
 193 After a handshake has been completed the negotiated \s-1SRTP\s0 protection profile (if
 194 any) can be obtained (on the client or the server) by calling
 195 \&\fISSL_get_selected_srtp_profile()\fR. This function will return \s-1NULL\s0 if no \s-1SRTP\s0
 196 protection profile was negotiated. The memory returned from this function should
 197 not be freed by the caller.
 198 .PP
 199 If an \s-1SRTP\s0 protection profile has been successfully negotiated then the \s-1SRTP\s0
 200 keying material (on both the client and server) should be obtained via a call to
 201 \&\fISSL_export_keying_material\fR\|(3). This call should provide a label value of
 202 \&\*(L"EXTRACTOR\-dtls_srtp\*(R" and a \s-1NULL\s0 context value (use_context is 0). The total
 203 length of keying material obtained should be equal to two times the sum of the
 204 master key length and the salt length as defined for the protection profile in
 205 use. This provides the client write master key, the server write master key, the
 206 client write master salt and the server write master salt in that order.
 207 .SH "RETURN VALUES"
 208 .IX Header "RETURN VALUES"
 209 \&\fISSL_CTX_set_tlsext_use_srtp()\fR and \fISSL_set_tlsext_use_srtp()\fR return 0 on success
 210 or 1 on error.
 211 .PP
 212 \&\fISSL_get_srtp_profiles()\fR returns a stack of \s-1SRTP_PROTECTION_PROFILE\s0 objects on
 213 success or \s-1NULL\s0 on error or if no protection profiles have been configured.
 214 .PP
 215 \&\fISSL_get_selected_srtp_profile()\fR returns a pointer to an \s-1SRTP_PROTECTION_PROFILE\s0
 216 object if one has been negotiated or \s-1NULL\s0 otherwise.
 217 .SH "SEE ALSO"
 218 .IX Header "SEE ALSO"
 219 \&\fISSL_export_keying_material\fR\|(3)
 220 .SH "COPYRIGHT"
 221 .IX Header "COPYRIGHT"
 222 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
 223 .PP
 224 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 225 this file except in compliance with the License.  You can obtain a copy
 226 in the file \s-1LICENSE\s0 in the source distribution or at
 227 <https://www.openssl.org/source/license.html>.