]>
Commit | Line | Data |
---|---|---|
3733ce61 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_tlsext_use_srtp, | |
6 | SSL_set_tlsext_use_srtp, | |
7 | SSL_get_srtp_profiles, | |
8 | SSL_get_selected_srtp_profile | |
9 | - Configure and query SRTP support | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/srtp.h> | |
14 | ||
15 | int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles); | |
16 | int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles); | |
17 | ||
18 | STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl); | |
19 | SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s); | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | SRTP is the Secure Real-Time Transport Protocol. OpenSSL implements support for | |
24 | the "use_srtp" DTLS extension defined in RFC5764. This provides a mechanism for | |
25 | establishing SRTP keying material, algorithms and parameters using DTLS. This | |
26 | capability may be used as part of an implementation that conforms to RFC5763. | |
27 | OpenSSL does not implement SRTP itself or RFC5763. Note that OpenSSL does not | |
28 | support the use of SRTP Master Key Identifiers (MKIs). Also note that this | |
29 | extension is only supported in DTLS. Any SRTP configuration will be ignored if a | |
30 | TLS connection is attempted. | |
31 | ||
32 | An OpenSSL client wishing to send the "use_srtp" extension should call | |
33 | SSL_CTX_set_tlsext_use_srtp() to set its use for all SSL objects subsequently | |
34 | created from an SSL_CTX. Alternatively a client may call | |
35 | SSL_set_tlsext_use_srtp() to set its use for an individual SSL object. The | |
36 | B<profiles> parameters should point to a NUL-terminated, colon delimited list of | |
37 | SRTP protection profile names. | |
38 | ||
39 | The currently supported protection profile names are: | |
40 | ||
41 | =over 4 | |
42 | ||
43 | =item SRTP_AES128_CM_SHA1_80 | |
44 | ||
45 | This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC5764. | |
46 | ||
47 | =item SRTP_AES128_CM_SHA1_32 | |
48 | ||
49 | This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC5764. | |
50 | ||
51 | =item SRTP_AEAD_AES_128_GCM | |
52 | ||
53 | This corresponds to the profile of the same name defined in RFC7714. | |
54 | ||
55 | =item SRTP_AEAD_AES_256_GCM | |
56 | ||
57 | This corresponds to the profile of the same name defined in RFC7714. | |
58 | ||
a425c0fe KK |
59 | =item SRTP_DOUBLE_AEAD_AES_128_GCM_AEAD_AES_128_GCM |
60 | ||
61 | This corresponds to the profile of the same name defined in RFC8723. | |
62 | ||
63 | =item SRTP_DOUBLE_AEAD_AES_256_GCM_AEAD_AES_256_GCM | |
64 | ||
65 | This corresponds to the profile of the same name defined in RFC8723. | |
66 | ||
67 | =item SRTP_ARIA_128_CTR_HMAC_SHA1_80 | |
68 | ||
69 | This corresponds to the profile of the same name defined in RFC8269. | |
70 | ||
71 | =item SRTP_ARIA_128_CTR_HMAC_SHA1_32 | |
72 | ||
73 | This corresponds to the profile of the same name defined in RFC8269. | |
74 | ||
75 | =item SRTP_ARIA_256_CTR_HMAC_SHA1_80 | |
76 | ||
77 | This corresponds to the profile of the same name defined in RFC8269. | |
78 | ||
79 | =item SRTP_ARIA_256_CTR_HMAC_SHA1_32 | |
80 | ||
81 | This corresponds to the profile of the same name defined in RFC8269. | |
82 | ||
83 | =item SRTP_AEAD_ARIA_128_GCM | |
84 | ||
85 | This corresponds to the profile of the same name defined in RFC8269. | |
86 | ||
87 | =item SRTP_AEAD_ARIA_256_GCM | |
88 | ||
89 | This corresponds to the profile of the same name defined in RFC8269. | |
90 | ||
3733ce61 MC |
91 | =back |
92 | ||
93 | Supplying an unrecognised protection profile name will result in an error. | |
94 | ||
95 | An OpenSSL server wishing to support the "use_srtp" extension should also call | |
96 | SSL_CTX_set_tlsext_use_srtp() or SSL_set_tlsext_use_srtp() to indicate the | |
97 | protection profiles that it is willing to negotiate. | |
98 | ||
99 | The currently configured list of protection profiles for either a client or a | |
100 | server can be obtained by calling SSL_get_srtp_profiles(). This returns a stack | |
101 | of SRTP_PROTECTION_PROFILE objects. The memory pointed to in the return value of | |
102 | this function should not be freed by the caller. | |
103 | ||
104 | After a handshake has been completed the negotiated SRTP protection profile (if | |
105 | any) can be obtained (on the client or the server) by calling | |
106 | SSL_get_selected_srtp_profile(). This function will return NULL if no SRTP | |
107 | protection profile was negotiated. The memory returned from this function should | |
108 | not be freed by the caller. | |
109 | ||
3266cf58 | 110 | If an SRTP protection profile has been successfully negotiated then the SRTP |
3733ce61 MC |
111 | keying material (on both the client and server) should be obtained via a call to |
112 | L<SSL_export_keying_material(3)>. This call should provide a label value of | |
113 | "EXTRACTOR-dtls_srtp" and a NULL context value (use_context is 0). The total | |
114 | length of keying material obtained should be equal to two times the sum of the | |
115 | master key length and the salt length as defined for the protection profile in | |
116 | use. This provides the client write master key, the server write master key, the | |
117 | client write master salt and the server write master salt in that order. | |
118 | ||
f082205b | 119 | These functions cannot be used with QUIC SSL objects. |
d6e7ebba HL |
120 | SSL_CTX_set_tlsext_use_srtp() fails if called on a QUIC SSL context. |
121 | SSL_set_tlsext_use_srtp() fails if called on a QUIC SSL object. | |
f082205b | 122 | |
3733ce61 MC |
123 | =head1 RETURN VALUES |
124 | ||
125 | SSL_CTX_set_tlsext_use_srtp() and SSL_set_tlsext_use_srtp() return 0 on success | |
126 | or 1 on error. | |
127 | ||
128 | SSL_get_srtp_profiles() returns a stack of SRTP_PROTECTION_PROFILE objects on | |
129 | success or NULL on error or if no protection profiles have been configured. | |
130 | ||
131 | SSL_get_selected_srtp_profile() returns a pointer to an SRTP_PROTECTION_PROFILE | |
132 | object if one has been negotiated or NULL otherwise. | |
133 | ||
134 | =head1 SEE ALSO | |
135 | ||
98ca37e4 | 136 | L<ssl(7)>, |
3733ce61 MC |
137 | L<SSL_export_keying_material(3)> |
138 | ||
139 | =head1 COPYRIGHT | |
140 | ||
da1c088f | 141 | Copyright 2017-2023 The OpenSSL Project Authors. All Rights Reserved. |
3733ce61 | 142 | |
4746f25a | 143 | Licensed under the Apache License 2.0 (the "License"). You may not use |
3733ce61 MC |
144 | this file except in compliance with the License. You can obtain a copy |
145 | in the file LICENSE in the source distribution or at | |
146 | L<https://www.openssl.org/source/license.html>. | |
147 | ||
148 | =cut |