openssl/doc/man7/EVP_KDF-SRTPKDF.pod

=pod

=head1 NAME

EVP_KDF-SRTPKDF - The SRTP EVP_KDF implementation

=head1 DESCRIPTION

Support for computing the B<SRTP> KDF through the B<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.

=head2 Identity

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

=head2 Supported parameters

The supported parameters are:

=over 4

=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>

=item "cipher" (B<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.

=item "key" (B<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.

=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>

This parameter sets the master salt value. This is typically 14 bytes
as specified in RFC 3711.

=item "kdr" (B<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).

=item "index" (B<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.

=item "label" (B<OSSL_KDF_PARAM_SRTPKDF_LABEL>) <unsigned integer>

This parameter sets the label that identifies the type of key to derive.
Valid values are:

=over 4

=item 0 - SRTP encryption key

=item 1 - SRTP authentication key

=item 2 - SRTP salt key

=item 3 - SRTCP encryption key

=item 4 - SRTCP authentication key

=item 5 - SRTCP salt key

=item 6 - SRTP encryption key (alternative)

=item 7 - SRTP salt key (alternative)

=back

=back

=head1 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:

=over 4

=item Labels 0, 3, 6: Output length equals the cipher key length

=item Labels 1, 4: Output length is 20 bytes (160 bits)

=item Labels 2, 5, 7: Output length is 14 bytes (112 bits)

=back

=head1 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);

=head1 CONFORMING TO

RFC 3711 Section 4.3.3 (SRTP Key Derivation)

=head1 SEE ALSO

L<EVP_KDF(3)>,
L<EVP_KDF_CTX_new(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_CTX_set_params(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>

=head1 HISTORY

The SRTPKDF was added in OpenSSL 4.0.0.

=head1 COPYRIGHT

Copyright 2026 The OpenSSL Project Authors. All Rights Reserved.

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
L<https://www.openssl.org/source/license.html>.

=cut