projects / thirdparty / openssl.git / blame
| 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 | ||
| 59 | =back | |
| 60 | ||
| 61 | Supplying an unrecognised protection profile name will result in an error. | |
| 62 | ||
| 63 | An OpenSSL server wishing to support the "use_srtp" extension should also call | |
| 64 | SSL_CTX_set_tlsext_use_srtp() or SSL_set_tlsext_use_srtp() to indicate the | |
| 65 | protection profiles that it is willing to negotiate. | |
| 66 | ||
| 67 | The currently configured list of protection profiles for either a client or a | |
| 68 | server can be obtained by calling SSL_get_srtp_profiles(). This returns a stack | |
| 69 | of SRTP_PROTECTION_PROFILE objects. The memory pointed to in the return value of | |
| 70 | this function should not be freed by the caller. | |
| 71 | ||
| 72 | After a handshake has been completed the negotiated SRTP protection profile (if | |
| 73 | any) can be obtained (on the client or the server) by calling | |
| 74 | SSL_get_selected_srtp_profile(). This function will return NULL if no SRTP | |
| 75 | protection profile was negotiated. The memory returned from this function should | |
| 76 | not be freed by the caller. | |
| 77 | ||
| 3266cf58 | 78 | If an SRTP protection profile has been successfully negotiated then the SRTP |
| 3733ce61 MC |
79 | keying material (on both the client and server) should be obtained via a call to |
| 80 | L<SSL_export_keying_material(3)>. This call should provide a label value of | |
| 81 | "EXTRACTOR-dtls_srtp" and a NULL context value (use_context is 0). The total | |
| 82 | length of keying material obtained should be equal to two times the sum of the | |
| 83 | master key length and the salt length as defined for the protection profile in | |
| 84 | use. This provides the client write master key, the server write master key, the | |
| 85 | client write master salt and the server write master salt in that order. | |
| 86 | ||
| 87 | =head1 RETURN VALUES | |
| 88 | ||
| 89 | SSL_CTX_set_tlsext_use_srtp() and SSL_set_tlsext_use_srtp() return 0 on success | |
| 90 | or 1 on error. | |
| 91 | ||
| 92 | SSL_get_srtp_profiles() returns a stack of SRTP_PROTECTION_PROFILE objects on | |
| 93 | success or NULL on error or if no protection profiles have been configured. | |
| 94 | ||
| 95 | SSL_get_selected_srtp_profile() returns a pointer to an SRTP_PROTECTION_PROFILE | |
| 96 | object if one has been negotiated or NULL otherwise. | |
| 97 | ||
| 98 | =head1 SEE ALSO | |
| 99 | ||
| 98ca37e4 | 100 | L<ssl(7)>, |
| 3733ce61 MC |
101 | L<SSL_export_keying_material(3)> |
| 102 | ||
| 103 | =head1 COPYRIGHT | |
| 104 | ||
| b0edda11 | 105 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. |
| 3733ce61 | 106 | |
| 4746f25a | 107 | Licensed under the Apache License 2.0 (the "License"). You may not use |
| 3733ce61 MC |
108 | this file except in compliance with the License. You can obtain a copy |
| 109 | in the file LICENSE in the source distribution or at | |
| 110 | L<https://www.openssl.org/source/license.html>. | |
| 111 | ||
| 112 | =cut |