=pod =head1 NAME EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation =head1 DESCRIPTION The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). SSKDF derives a key using input such as a shared secret key (that was generated during the execution of a key establishment scheme) and fixedinfo. SSKDF is also informally referred to as 'Concat KDF'. =head2 Auxiliary function The implementation uses a selectable auxiliary function H, which can be one of: =over 4 =item B =item B =item B =back Both the HMAC and KMAC implementations set the key using the 'salt' value. The hash and HMAC also require the digest to be set. =head2 Identity "SSKDF" 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) =item "digest" (B) =item "mac" (B) =item "maclen" (B) =item "salt" (B) These parameters work as described in L. =item "key" (B) This parameter set the shared secret that is used for key derivation. =item "info" (B) This parameter sets an optional value for fixedinfo, also known as otherinfo. =back =head1 NOTES A context for SSKDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_new_ctx(kdf); The output length of an SSKDF is specified via the I parameter to the L function. =head1 EXAMPLES This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" and fixedinfo value "label": EVP_KDF *kdf; EVP_KDF_CTX *kctx; unsigned char out[10]; OSSL_PARAM params[4], *p = params; kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); kctx = EVP_KDF_new_ctx(kdf); EVP_KDF_free(kdf); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, SN_sha256, strlen(SN_sha256)); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, "secret", (size_t)6); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, "label", (size_t)5); *p = OSSL_PARAM_construct_end(); if (EVP_KDF_set_ctx_params(kctx, params) <= 0) { error("EVP_KDF_set_ctx_params"); } if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { error("EVP_KDF_derive"); } EVP_KDF_free_ctx(kctx); This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", fixedinfo value "label" and salt "salt": EVP_KDF *kdf; EVP_KDF_CTX *kctx; unsigned char out[10]; OSSL_PARAM params[6], *p = params; kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); kctx = EVP_KDF_new_ctx(kdf); EVP_KDF_free(kdf); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, SN_hmac, strlen(SN_hmac)); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, SN_sha256, strlen(SN_sha256)); *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, "label", (size_t)5); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, "salt", (size_t)4); *p = OSSL_PARAM_construct_end(); if (EVP_KDF_set_ctx_params(kctx, params) <= 0) { error("EVP_KDF_set_ctx_params"); } if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { error("EVP_KDF_derive"); } EVP_KDF_free_ctx(kctx); This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" fixedinfo value "label", salt of "salt" and KMAC outlen of 20: EVP_KDF *kdf; EVP_KDF_CTX *kctx; unsigned char out[10]; OSSL_PARAM params[7], *p = params; kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); kctx = EVP_KDF_new_ctx(kdf); EVP_KDF_free(kdf); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, SN_kmac128, strlen(SN_kmac128)); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, SN_sha256, strlen(SN_sha256)); *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, "label", (size_t)5); *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, "salt", (size_t)4); *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); *p = OSSL_PARAM_construct_end(); if (EVP_KDF_set_ctx_params(kctx, params) <= 0) { error("EVP_KDF_set_ctx_params"); } if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { error("EVP_KDF_derive"); } EVP_KDF_free_ctx(kctx); =head1 CONFORMING TO NIST SP800-56Cr1. =head1 SEE ALSO L, L, L, L, L, L, L =head1 HISTORY This functionality was added to OpenSSL 3.0. =head1 COPYRIGHT Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright (c) 2019, Oracle and/or its affiliates. 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. =cut