cda774223d
And update find-doc-nits to complain if "=head1 EXAMPLE" is found. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/9602)
146 lines
3.6 KiB
Text
146 lines
3.6 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
|
|
|
|
The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions up to
|
|
and including TLS 1.2.
|
|
|
|
=head2 Numeric identity
|
|
|
|
B<EVP_KDF_TLS1_PRF> 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>.
|
|
|
|
The C<EVP_KDF_CTRL_SET_MD> control is used to set the message digest associated
|
|
with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the
|
|
PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
|
|
|
|
=item B<EVP_KDF_CTRL_SET_TLS_SECRET>
|
|
|
|
This control expects two arguments: C<unsigned char *sec>, C<size_t seclen>
|
|
|
|
Sets the secret value of the TLS PRF to B<seclen> bytes of the buffer B<sec>.
|
|
Any existing secret value is replaced.
|
|
|
|
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_RESET_TLS_SEED>
|
|
|
|
This control does not expect any arguments.
|
|
|
|
Resets the context seed buffer to zero length.
|
|
|
|
=item B<EVP_KDF_CTRL_ADD_TLS_SEED>
|
|
|
|
This control expects two arguments: C<unsigned char *seed>, C<size_t seedlen>
|
|
|
|
Sets the seed to B<seedlen> bytes of B<seed>. If a seed is already set it is
|
|
appended to the existing value.
|
|
|
|
The total length of the context seed buffer cannot exceed 1024 bytes;
|
|
this should be more than enough for any normal use of the TLS PRF.
|
|
|
|
EVP_KDF_ctrl_str() takes two type strings for this control:
|
|
|
|
=over 4
|
|
|
|
=item "seed"
|
|
|
|
The value string is used as is.
|
|
|
|
=item "hexseed"
|
|
|
|
The value string is expected to be a hexadecimal number, which will be
|
|
decoded before being passed on as the control value.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
A context for the TLS PRF can be obtained by calling:
|
|
|
|
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
|
|
|
|
The digest, secret value and seed must be set before a key is derived otherwise
|
|
an error will occur.
|
|
|
|
The output length of the PRF is specified by the C<keylen> parameter to the
|
|
EVP_KDF_derive() function.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
This example derives 10 bytes using SHA-256 with the secret key "secret"
|
|
and seed value "seed":
|
|
|
|
EVP_KDF_CTX *kctx;
|
|
unsigned char out[10];
|
|
|
|
kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
|
|
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_TLS_SECRET,
|
|
"secret", (size_t)6) <= 0) {
|
|
error("EVP_KDF_CTRL_SET_TLS_SECRET");
|
|
}
|
|
if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
|
|
error("EVP_KDF_CTRL_ADD_TLS_SEED");
|
|
}
|
|
if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
|
|
error("EVP_KDF_derive");
|
|
}
|
|
EVP_KDF_CTX_free(kctx);
|
|
|
|
=head1 CONFORMING TO
|
|
|
|
RFC 2246, RFC 5246 and NIST SP 800-135 r1
|
|
|
|
=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_derive(3)>,
|
|
L<EVP_KDF_CTX(3)/CONTROLS>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2018 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
|