EVP_KDF-SNMPKDF¶

NAME¶

EVP_KDF-SNMPKDF - The SNMPKDF EVP_KDF implementation

DESCRIPTION¶

Support for computing the SNMPKDF KDF through the 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

Identity¶

"SNMPKDF" 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>
"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>
"pass" (OSSL_KDF_PARAM_PASS) <octet string>
These parameters works as described in "PARAMETERS" in EVP_KDF(3).
"eid" (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.

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 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 EVP_KDF_derive(3) function along with the expected length.

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 */

CONFORMING TO¶

RFC 3414, RFC 7860, NIST SP800-135

HISTORY¶

This functionality was added in OpenSSL 4.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.