[thirdparty/openssl.git] / doc / man7 / EVP_KDF_X942.pod

=pod

=head1 NAME

EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation

=head1 DESCRIPTION

The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
derive a key using input such as a shared secret key and other info. The other
info is DER encoded data that contains a 32 bit counter.

=head2 Numeric identity

B<EVP_KDF_X942> is the numeric identity for this implementation; it
can be used with the EVP_KDF_CTX_new_id() function.

=head2 Supported controls

The supported controls are:

=over 4

=item B<EVP_KDF_CTRL_SET_MD>

This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.

=item B<EVP_KDF_CTRL_SET_KEY>

This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>

The shared secret used for key derivation.  This control sets the secret.

EVP_KDF_ctrl_str() takes two type strings for this control:

=over 4

=item "secret"

The value string is used as is.

=item "hexsecret"

The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.

=back

=item B<EVP_KDF_CTRL_SET_UKM>

This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>

An optional random string that is provided by the sender called "partyAInfo".
In CMS this is the user keying material.

EVP_KDF_ctrl_str() takes two type strings for this control:

=over 4

=item "ukm"

The value string is used as is.

=item "hexukm"

The value string is expected to be a hexadecimal number, which will be
decoded before being passed on as the control value.

=back

=item B<EVP_KDF_CTRL_SET_CEK_ALG>

This control expects one argument: C<char *alg>

The CEK wrapping algorithm name. 

EVP_KDF_ctrl_str() type string: "cekalg"

The value string is used as is.

=back

=head1 NOTES

A context for X942KDF can be obtained by calling:

EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);

The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.

=head1 EXAMPLES

This example derives 24 bytes, with the secret key "secret" and a random user
keying material:

  EVP_KDF_CTX *kctx;
  unsigned char out[192/8];
  unsignred char ukm[64];

  if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
      error("RAND_bytes");

  kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
  if (kctx == NULL)
      error("EVP_KDF_CTX_new_id");

  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0)
      error("EVP_KDF_CTRL_SET_MD");
  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0)
      error("EVP_KDF_CTRL_SET_KEY");
  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
      error("EVP_KDF_CTRL_SET_UKM");
  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
                   SN_id_smime_alg_CMS3DESwrap) <= 0)
      error("EVP_KDF_CTRL_SET_CEK_ALG");
  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
      error("EVP_KDF_derive");

  EVP_KDF_CTX_free(kctx);

=head1 CONFORMING TO

RFC 2631

=head1 SEE ALSO

L<EVP_KDF_CTX>,
L<EVP_KDF_CTX_new_id(3)>,
L<EVP_KDF_CTX_free(3)>,
L<EVP_KDF_ctrl(3)>,
L<EVP_KDF_size(3)>,
L<EVP_KDF_derive(3)>,
L<EVP_KDF_CTX(3)/CONTROLS>

=head1 HISTORY

This functionality was added to OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019 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
Commit	Line	Data
1aec7716 SL	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation
	6
	7	=head1 DESCRIPTION
	8
	9	The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
	10	X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
	11	derive a key using input such as a shared secret key and other info. The other
	12	info is DER encoded data that contains a 32 bit counter.
	13
	14	=head2 Numeric identity
	15
	16	B<EVP_KDF_X942> is the numeric identity for this implementation; it
	17	can be used with the EVP_KDF_CTX_new_id() function.
	18
	19	=head2 Supported controls
	20
	21	The supported controls are:
	22
	23	=over 4
	24
	25	=item B<EVP_KDF_CTRL_SET_MD>
	26
	27	This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
	28
	29	=item B<EVP_KDF_CTRL_SET_KEY>
	30
	31	This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
	32
	33	The shared secret used for key derivation. This control sets the secret.
	34
	35	EVP_KDF_ctrl_str() takes two type strings for this control:
	36
	37	=over 4
	38
	39	=item "secret"
	40
	41	The value string is used as is.
	42
	43	=item "hexsecret"
	44
	45	The value string is expected to be a hexadecimal number, which will be
	46	decoded before being passed on as the control value.
	47
	48	=back
	49
	50	=item B<EVP_KDF_CTRL_SET_UKM>
	51
	52	This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>
	53
	54	An optional random string that is provided by the sender called "partyAInfo".
	55	In CMS this is the user keying material.
	56
	57	EVP_KDF_ctrl_str() takes two type strings for this control:
	58
	59	=over 4
	60
	61	=item "ukm"
	62
	63	The value string is used as is.
	64
65	=item "hexukm"
66
67	The value string is expected to be a hexadecimal number, which will be
68	decoded before being passed on as the control value.
69
70	=back
71
72	=item B<EVP_KDF_CTRL_SET_CEK_ALG>
73
74	This control expects one argument: C<char *alg>
75
76	The CEK wrapping algorithm name.
77
78	EVP_KDF_ctrl_str() type string: "cekalg"
79
80	The value string is used as is.
81
82	=back
83
84	=head1 NOTES
85
86	A context for X942KDF can be obtained by calling:
87
88	EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
89
90	The output length of an X942KDF is specified via the C<keylen>
91	parameter to the L<EVP_KDF_derive(3)> function.
92
cda77422	93	=head1 EXAMPLES
1aec7716 SL	94
	95	This example derives 24 bytes, with the secret key "secret" and a random user
	96	keying material:
	97
	98	EVP_KDF_CTX *kctx;
	99	unsigned char out[192/8];
	100	unsignred char ukm[64];
	101
	102	if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
	103	error("RAND_bytes");
	104
	105	kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
	106	if (kctx == NULL)
	107	error("EVP_KDF_CTX_new_id");
	108
	109	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0)
	110	error("EVP_KDF_CTRL_SET_MD");
	111	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0)
	112	error("EVP_KDF_CTRL_SET_KEY");
	113	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
	114	error("EVP_KDF_CTRL_SET_UKM");
	115	if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
	116	SN_id_smime_alg_CMS3DESwrap) <= 0)
	117	error("EVP_KDF_CTRL_SET_CEK_ALG");
	118	if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
	119	error("EVP_KDF_derive");
	120
	121	EVP_KDF_CTX_free(kctx);
	122
	123	=head1 CONFORMING TO
	124
	125	RFC 2631
	126
	127	=head1 SEE ALSO
	128
	129	L<EVP_KDF_CTX>,
	130	L<EVP_KDF_CTX_new_id(3)>,
	131	L<EVP_KDF_CTX_free(3)>,
	132	L<EVP_KDF_ctrl(3)>,
	133	L<EVP_KDF_size(3)>,
	134	L<EVP_KDF_derive(3)>,
	135	L<EVP_KDF_CTX(3)/CONTROLS>
	136
	137	=head1 HISTORY
	138
4674aaf4	139	This functionality was added to OpenSSL 3.0.
1aec7716 SL	140
	141	=head1 COPYRIGHT
	142
	143	Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
	144
	145	Licensed under the Apache License 2.0 (the "License"). You may not use
	146	this file except in compliance with the License. You can obtain a copy
	147	in the file LICENSE in the source distribution or at
	148	L<https://www.openssl.org/source/license.html>.
	149
	150	=cut