EVP_KDF-SRTPKDF¶

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. Typically "AES-128-CTR" or "AES-256-CTR" is used.
"key" (OSSL_KDF_PARAM_KEY) <octet string>
This parameter sets the master key value. This is typically 16 bytes for AES-128 or 32 bytes for AES-256.
"salt" (OSSL_KDF_PARAM_SALT) <octet string>
This parameter sets the master salt value. This is typically 14 bytes as specified in RFC 3711.
"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 (range 2^0 to 2^24).
"index" (OSSL_KDF_PARAM_SRTPKDF_INDEX) <octet string>
This parameter sets the index value used in key derivation. For RTP packets, this is typically a 48-bit (6 byte) value. For RTCP packets, this is typically a 32-bit (4 byte) value. If not set, defaults to zero.
"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 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.