=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.
It must be set to one of "AES-128-CTR", "AES-192-CTR" or "AES-256-CTR".

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

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

=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 in the 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. 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.

=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 derive 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
