=pod

=head1 NAME

EVP_KDF-SNMPKDF - The SNMPKDF EVP_KDF implementation

=head1 DESCRIPTION

Support for computing the B<SNMPKDF> KDF through the B<EVP_KDF> API.

The EVP_KDF-SNMPKDF algorithm implements the SNMPKDF key derivation function.
It is defined in RFC 3414, appendix A.2.2 and is used by SNMP to derive
encryption keys.
Three inputs are required to perform key derivation: The hashing function
(for example SHA1), the engine ID, and the password

=head2 Identity

"SNMPKDF" 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 "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>

=item "pass" (B<OSSL_KDF_PARAM_PASS>) <octet string>

These parameters works as described in L<EVP_KDF(3)/PARAMETERS>.

=item "eid" (B<OSSL_KDF_PARAM_SNMPKDF_EID>) <octet string>

This parameter sets the snmpEngineID value for the KDF.
If a value is already set, the contents are replaced.

=back

=head1 NOTES

A context for SNMPKDF can be obtained by calling:

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

The expected length of the SNMPKDF derivation output is the size of the I<digest>.
Since the SNMPKDF output length can vary depending on the digest used, the caller should allocate a buffer of the
digest size and pass that buffer in the L<EVP_KDF_derive(3)> function along with the expected length.

=head1 EXAMPLES

This example derives an 8 byte IV using SHA1 with a 1K "key" and appropriate
"xcghash" and "session_id" values:

 EVP_KDF *kdf;
 EVP_KDF_CTX *kctx;
 unsigned char eid[1024] = "01234...";
 unsigned char pass[32] = "012345...";
 unsigned char out[20];
 size_t outlen = sizeof(out);
 OSSL_PARAM params[6], *p = params;

 kdf = EVP_KDF_fetch(NULL, "SNMPKDF", NULL);
 kctx = EVP_KDF_CTX_new(kdf);
 EVP_KDF_free(kdf);

 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                         SN_sha1, strlen(SN_sha1));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASS,
                                          pass, sizeof(pass));
 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SNMPKDF_EID,
                                          eid, sizeof(eid));
 *p = OSSL_PARAM_construct_end();
 if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
     /* Error */


=head1 CONFORMING TO

RFC 3414, RFC 7860, NIST SP800-135

=head1 SEE ALSO

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

=head1 HISTORY

This functionality was added in OpenSSL 4.0.

=head1 COPYRIGHT

Copyright 2025 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
