[thirdparty/openssl.git] / doc / man7 / EVP_KDF-SS.pod

=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<H(x) = hash(x, digest=md)>

=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>

=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>

=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<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>

=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>

This parameter is ignored for KMAC.

=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>

=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>

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

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

=item "key" (B<EVP_KDF_CTRL_SET_KEY>) <octet string>

This parameter set the shared secret that is used for key derivation.

=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string>

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_CTX_new(kdf);

The output length of an SSKDF is specified via the I<keylen>
parameter to the L<EVP_KDF_derive(3)> 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_CTX_new(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_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }

 EVP_KDF_CTX_free(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_CTX_new(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_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }

 EVP_KDF_CTX_free(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[6], *p = params;

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

 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                         SN_kmac128, strlen(SN_kmac128));
 *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_derive(kctx, out, sizeof(out), params) <= 0) {
     error("EVP_KDF_derive");
 }

 EVP_KDF_CTX_free(kctx);

=head1 CONFORMING TO

NIST SP800-56Cr1.

=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_CTX_get_kdf_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF(3)/PARAMETERS>

=head1 HISTORY

This functionality was added in OpenSSL 3.0.

=head1 COPYRIGHT

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

=cut
Commit	Line	Data
ccd7115a P	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation
	6
	7	=head1 DESCRIPTION
	8
	9	The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF).
	10	SSKDF derives a key using input such as a shared secret key (that was generated
	11	during the execution of a key establishment scheme) and fixedinfo.
	12	SSKDF is also informally referred to as 'Concat KDF'.
	13
	14	=head2 Auxiliary function
	15
	16	The implementation uses a selectable auxiliary function H, which can be one of:
	17
	18	=over 4
	19
	20	=item B<H(x) = hash(x, digest=md)>
	21
	22	=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
	23
	24	=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
	25
	26	=back
	27
	28	Both the HMAC and KMAC implementations set the key using the 'salt' value.
	29	The hash and HMAC also require the digest to be set.
	30
	31	=head2 Identity
	32
	33	"SSKDF" is the name for this implementation; it
	34	can be used with the EVP_KDF_fetch() function.
	35
	36	=head2 Supported parameters
	37
	38	The supported parameters are:
	39
	40	=over 4
	41
0c452a51	42	=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
ccd7115a	43
0c452a51	44	=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
ccd7115a	45
e8add4d3	46	This parameter is ignored for KMAC.
e8add4d3	47
0c452a51	48	=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string>
ccd7115a	49
0c452a51	50	=item "maclen" (B<OSSL_KDF_PARAM_MAC_SIZE>) <unsigned integer>
ccd7115a	51
0c452a51	52	=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
ccd7115a P	53
	54	These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
	55
0c452a51	56	=item "key" (B<EVP_KDF_CTRL_SET_KEY>) <octet string>
ccd7115a P	57
	58	This parameter set the shared secret that is used for key derivation.
	59
0c452a51	60	=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string>
ccd7115a P	61
	62	This parameter sets an optional value for fixedinfo, also known as otherinfo.
	63
	64	=back
	65
	66	=head1 NOTES
	67
	68	A context for SSKDF can be obtained by calling:
	69
	70	EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
660c5344	71	EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
ccd7115a	72
dfabee82	73	The output length of an SSKDF is specified via the I<keylen>
86913ef7	74	parameter to the L<EVP_KDF_derive(3)> function.
ccd7115a P	75
	76	=head1 EXAMPLES
	77
	78	This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
	79	and fixedinfo value "label":
	80
	81	EVP_KDF *kdf;
	82	EVP_KDF_CTX *kctx;
	83	unsigned char out[10];
	84	OSSL_PARAM params[4], *p = params;
	85
	86	kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
660c5344	87	kctx = EVP_KDF_CTX_new(kdf);
ccd7115a P	88	EVP_KDF_free(kdf);
	89
	90	*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
	91	SN_sha256, strlen(SN_sha256));
	92	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
	93	"secret", (size_t)6);
	94	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
	95	"label", (size_t)5);
	96	*p = OSSL_PARAM_construct_end();
6980e36a	97	if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
ccd7115a P	98	error("EVP_KDF_derive");
	99	}
	100
660c5344	101	EVP_KDF_CTX_free(kctx);
ccd7115a P	102
	103	This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
	104	fixedinfo value "label" and salt "salt":
	105
	106	EVP_KDF *kdf;
	107	EVP_KDF_CTX *kctx;
	108	unsigned char out[10];
	109	OSSL_PARAM params[6], *p = params;
	110
	111	kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
660c5344	112	kctx = EVP_KDF_CTX_new(kdf);
ccd7115a P	113	EVP_KDF_free(kdf);
	114
	115	*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
	116	SN_hmac, strlen(SN_hmac));
	117	*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
	118	SN_sha256, strlen(SN_sha256));
	119	*p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY,
	120	"secret", (size_t)6);
	121	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
	122	"label", (size_t)5);
	123	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
	124	"salt", (size_t)4);
	125	*p = OSSL_PARAM_construct_end();
6980e36a	126	if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
ccd7115a P	127	error("EVP_KDF_derive");
	128	}
	129
660c5344	130	EVP_KDF_CTX_free(kctx);
ccd7115a P	131
	132	This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
	133	fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
	134
	135	EVP_KDF *kdf;
	136	EVP_KDF_CTX *kctx;
	137	unsigned char out[10];
e8add4d3	138	OSSL_PARAM params[6], *p = params;
ccd7115a P	139
ccd7115a P	140	kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
660c5344	141	kctx = EVP_KDF_CTX_new(kdf);
ccd7115a P	142	EVP_KDF_free(kdf);
	143
	144	*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
	145	SN_kmac128, strlen(SN_kmac128));
ccd7115a P	146	*p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY,
	147	"secret", (size_t)6);
	148	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
	149	"label", (size_t)5);
	150	*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
	151	"salt", (size_t)4);
	152	*p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
	153	*p = OSSL_PARAM_construct_end();
6980e36a	154	if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
ccd7115a P	155	error("EVP_KDF_derive");
	156	}
	157
660c5344	158	EVP_KDF_CTX_free(kctx);
ccd7115a P	159
	160	=head1 CONFORMING TO
	161
	162	NIST SP800-56Cr1.
	163
	164	=head1 SEE ALSO
	165
4c04e7b1	166	L<EVP_KDF(3)>,
660c5344 MC	167	L<EVP_KDF_CTX_new(3)>,
	168	L<EVP_KDF_CTX_free(3)>,
	169	L<EVP_KDF_CTX_set_params(3)>,
1ba21239	170	L<EVP_KDF_CTX_get_kdf_size(3)>,
4c04e7b1	171	L<EVP_KDF_derive(3)>,
ccd7115a P	172	L<EVP_KDF(3)/PARAMETERS>
	173
	174	=head1 HISTORY
	175
4741c80c	176	This functionality was added in OpenSSL 3.0.
ccd7115a P	177
	178	=head1 COPYRIGHT
	179
8020d79b	180	Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. Copyright
ccd7115a P	181	(c) 2019, Oracle and/or its affiliates. All rights reserved.
	182
	183	Licensed under the Apache License 2.0 (the "License"). You may not use
	184	this file except in compliance with the License. You can obtain a copy
	185	in the file LICENSE in the source distribution or at
	186	L<https://www.openssl.org/source/license.html>.
	187
	188	=cut