NAME

EVP_KDF-SRTPKDF - The SRTP EVP_KDF implementation

DESCRIPTION

Support for computing the SRTP KDF through the EVP_KDF API.

The EVP_KDF-SRTP algorithm implements the SRTP key derivation function. SRTP follows the specification in RFC 3711 Section 4.3.3, where various cryptographic keys (encryption, authentication, and salt keys) are derived from a master key and master salt using AES encryption with specific labels.

The output keys are used for SRTP and SRTCP packet protection.

Identity

"SRTP" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

Supported parameters

The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>: This parameter sets the cipher to be used for the key derivation. It must be set to one of "AES-128-CTR", "AES-192-CTR" or "AES-256-CTR".
"key" (OSSL_KDF_PARAM_KEY) <octet string>: This parameter sets the master key value. This must be 16 bytes for AES-128, 24 bytes for AES-192 or 32 bytes for AES-256.
"salt" (OSSL_KDF_PARAM_SALT) <octet string>: This parameter sets the master salt value. The must be at least 14 bytes. Note that larger salts are truncated.
"kdr" (OSSL_KDF_PARAM_SRTPKDF_KDR) <unsigned integer>: This parameter sets the key derivation rate (KDR). The KDR controls how often keys are rederived. If not set or set to zero, no key rederivation is performed. The KDR value is power of 2 in the range 2^0 to 2^24.
"index" (OSSL_KDF_PARAM_SRTPKDF_INDEX) <octet string>: This parameter sets the index value used in key derivation. The length must be at least 6 bytes for RTP packets, or at least 4 bytes for RTCP packets. Note that larger index values are truncated. If it is not set, or it has zero length, no key rederivation is performed.
"label" (OSSL_KDF_PARAM_SRTPKDF_LABEL) <unsigned integer>: This parameter sets the label that identifies the type of key to derive. Valid values are:

0 - SRTP encryption key
1 - SRTP authentication key
2 - SRTP salt key
3 - SRTCP encryption key
4 - SRTCP authentication key
5 - SRTCP salt key
6 - SRTP encryption key (alternative)
7 - SRTP salt key (alternative)

NOTES

A context for SRTP can be obtained by calling:

 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SRTP", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

The output length of the SRTP KDF derive operation is determined by the label:

Labels 0, 3, 6: Output length equals the cipher key length
Labels 1, 4: Output length is 20 bytes (160 bits)
Labels 2, 5, 7: Output length is 14 bytes (112 bits)

EXAMPLES

This example derives an SRTP encryption key (label 0) using AES-128-CTR with a 16-byte master key and 14-byte master salt:

 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[16];
 unsigned char master_key[16] = { /* master key bytes */ };
 unsigned char master_salt[14] = { /* master salt bytes */ };
 uint32_t label = 0;
 OSSL_PARAM params[5], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SRTP", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER,
                                         "AES-128-CTR", 0);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          master_key, sizeof(master_key));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          master_salt, sizeof(master_salt));
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SRTPKDF_LABEL, &label);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);

This example derives an SRTP authentication key (label 1) with key derivation rate and index:

 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char out[20];
 unsigned char master_key[16] = { /* master key bytes */ };
 unsigned char master_salt[14] = { /* master salt bytes */ };
 uint32_t kdr = 0x1000; /* KDR */
 unsigned char index[6] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x01 }; /* index */
 uint32_t label = 1;
 OSSL_PARAM params[7], *p = params;
 kdf = EVP_KDF_fetch(NULL, "SRTP", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);
 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER,
                                         "AES-128-CTR", 0);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                          master_key, sizeof(master_key));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                          master_salt, sizeof(master_salt));
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SRTPKDF_KDR, &kdr);
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SRTPKDF_INDEX,
                                          index, sizeof(index));
 *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SRTPKDF_LABEL, &label);
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }
 EVP_KDF_CTX_free(kctx);

CONFORMING TO

RFC 3711 Section 4.3.3 (SRTP Key Derivation)

HISTORY

The SRTPKDF was added in OpenSSL 4.0.0.

COPYRIGHT

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.