mirror of
https://github.com/openssl/openssl.git
synced 2024-12-03 05:41:46 +08:00
5ac8fb584a
We do the same thing for the "get1" version. In reality this has broader use than just TLS (it can also be used in CMS), and "encodedpoint" only makes sense when you are talking about EC based algorithms. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/13105)
235 lines
6.9 KiB
Plaintext
235 lines
6.9 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
For B<DH> FFC key agreement, two classes of domain parameters can be used:
|
|
"safe" domain parameters that are associated with approved named safe-prime
|
|
groups, and a class of "FIPS 186-type" domain parameters. FIPS 186-type domain
|
|
parameters should only be used for backward compatibility with existing
|
|
applications that cannot be upgraded to use the approved safe-prime groups.
|
|
|
|
See L<EVP_PKEY-FFC(7)> for more information about FFC keys.
|
|
|
|
For B<DH> that is not a named group) the FIPS186-4 standard specifies that the
|
|
values used for FFC parameter generation are also required for parameter
|
|
validation. This means that optional FFC domain parameter values for
|
|
I<seed>, I<pcounter> and I<gindex> may need to be stored for validation purposes.
|
|
For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
|
|
(but the I<gindex> is not).
|
|
|
|
=head2 DH parameters
|
|
|
|
In addition to the common FCC parameters that all FFC keytypes should support
|
|
(see L<EVP_PKEY-FFC(7)/FFC parameters>)) the B<DH> keytype
|
|
implementation supports the following:
|
|
|
|
=over 4
|
|
|
|
=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
|
|
|
|
Set or gets a string that associates a B<DH> named safe prime group with known
|
|
values for I<p>, I<q> and I<g>.
|
|
|
|
The following values can be used by the OpenSSL's default and FIPS providers:
|
|
"ffdhe2048", "ffdhe3072", "ffdhe4096", "ffdhe6144", "ffdhe8192",
|
|
"modp_2048", "modp_3072", "modp_4096", "modp_6144", "modp_8192".
|
|
|
|
The following additional values can also be used by OpenSSL's default provider:
|
|
"modp_1536", "dh_1024_160", "dh_2048_224", "dh_2048_256".
|
|
|
|
DH named groups can be easily validated since the parameters are well known.
|
|
For protocols that only transfer I<p> and I<g> the value of I<q> can also be
|
|
retrieved.
|
|
|
|
=item "safeprime-generator" (B<OSSL_PKEY_PARAM_DH_GENERATOR>) <integer>
|
|
|
|
Used for DH generation of safe primes using the old generator code.
|
|
It is recommended to use a named safe prime group instead, if domain parameter
|
|
validation is required. The default value is 2.
|
|
|
|
These are not named safe prime groups so setting this value for the OpenSSL FIPS
|
|
provider will instead choose a named safe prime group based on the size of I<p>.
|
|
|
|
=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
|
|
|
|
Used for getting and setting the encoding of the DH public key used in a key
|
|
exchange message for the TLS protocol.
|
|
|
|
=back
|
|
|
|
=head2 DH domain parameter / key generation parameters
|
|
|
|
In addition to the common FCC key generation parameters that all FFC key types
|
|
should support (see L<EVP_PKEY-FFC(7)/FFC key generation parameters>)) the
|
|
B<DH> keytype implementation supports the following:
|
|
|
|
=over 4
|
|
|
|
=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
|
|
|
|
Sets the type of parameter generation. For B<DH> valid values are:
|
|
|
|
=over 4
|
|
|
|
=item "fips186_4"
|
|
|
|
=item "default"
|
|
|
|
=item "fips186_2"
|
|
|
|
These are described in L<EVP_PKEY-FFC(7)/FFC key generation parameters>
|
|
|
|
=item "group"
|
|
|
|
This specifies that a named safe prime name will be chosen using the "pbits"
|
|
type.
|
|
|
|
=item "generator"
|
|
|
|
A safe prime generator. See the "safeprime-generator" type above.
|
|
|
|
=back
|
|
|
|
=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
|
|
|
|
Sets the size (in bits) of the prime 'p'.
|
|
|
|
For "fips186_4" this must be 2048.
|
|
For "fips186_2" this must be 1024.
|
|
For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
|
|
|
|
=item "priv_len" (B<OSSL_PKEY_PARAM_DH_PRIV_LEN>) <integer>
|
|
|
|
An optional value to set the maximum length of the generated private key.
|
|
The default value used if this is not set is the maximum value of
|
|
BN_num_bits(I<q>)). The minimum value that this can be set to is 2 * s.
|
|
Where s is the security strength of the key which has values of
|
|
112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
An B<EVP_PKEY> context can be obtained by calling:
|
|
|
|
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
|
|
|
|
An B<DH> key can be generated with a named safe prime group by calling:
|
|
|
|
int priv_len = 2 * 112;
|
|
OSSL_PARAM params[3];
|
|
EVP_PKEY *pkey = NULL;
|
|
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
|
|
|
|
params[0] = OSSL_PARAM_construct_utf8_string("group", "ffdhe2048", 0);
|
|
/* "priv_len" is optional */
|
|
params[1] = OSSL_PARAM_construct_int("priv_len", &priv_len);
|
|
params[2] = OSSL_PARAM_construct_end();
|
|
|
|
EVP_PKEY_keygen_init(pctx);
|
|
EVP_PKEY_CTX_set_params(pctx, params);
|
|
EVP_PKEY_gen(pctx, &pkey);
|
|
...
|
|
EVP_PKEY_free(key);
|
|
EVP_PKEY_CTX_free(pctx);
|
|
|
|
Legacy B<DH> domain parameters can be generated by calling:
|
|
unsigned int pbits = 2048;
|
|
unsigned int qbits = 256;
|
|
int gindex = 1;
|
|
OSSL_PARAM params[5];
|
|
EVP_PKEY *param_key = NULL;
|
|
EVP_PKEY_CTX *pctx = NULL;
|
|
|
|
pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
|
|
EVP_PKEY_paramgen_init(pctx);
|
|
|
|
params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
|
|
params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
|
|
params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
|
|
params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
|
|
params[4] = OSSL_PARAM_construct_end();
|
|
EVP_PKEY_CTX_set_params(pctx, params);
|
|
|
|
EVP_PKEY_gen(pctx, ¶m_key);
|
|
|
|
EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
|
|
...
|
|
EVP_PKEY_free(param_key);
|
|
EVP_PKEY_CTX_free(pctx);
|
|
|
|
An B<DH> key can be generated using domain parameters by calling:
|
|
|
|
EVP_PKEY *key = NULL;
|
|
EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
|
|
|
|
EVP_PKEY_keygen_init(gctx);
|
|
EVP_PKEY_gen(gctx, &key);
|
|
EVP_PKEY_print_private(bio_out, key, 0, NULL);
|
|
...
|
|
EVP_PKEY_free(key);
|
|
EVP_PKEY_CTX_free(gctx);
|
|
|
|
=for comment TODO(3.0): To validate domain parameters, additional values used
|
|
during generation may be required to be set into the key.
|
|
|
|
=head1 CONFORMING TO
|
|
|
|
=over 4
|
|
|
|
=item RFC 7919 (TLS ffdhe named safe prime groups)
|
|
|
|
=item RFC 3526 (IKE modp named safe prime groups)
|
|
|
|
=item RFC 5114 (Additional DH named groups for dh_1024_160", "dh_2048_224"
|
|
and "dh_2048_256").
|
|
|
|
=back
|
|
|
|
The following sections of SP800-56Ar3:
|
|
|
|
=over 4
|
|
|
|
=item 5.5.1.1 FFC Domain Parameter Selection/Generation
|
|
|
|
=item Appendix D: FFC Safe-prime Groups
|
|
|
|
=back
|
|
|
|
The following sections of FIPS 186-4:
|
|
|
|
=over 4
|
|
|
|
=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
|
|
|
|
=item A.2.3 Generation of canonical generator g.
|
|
|
|
=item A.2.1 Unverifiable Generation of the Generator g.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<EVP_PKEY-FFC(7)>,
|
|
L<EVP_KEYEXCH-DH(7)>
|
|
L<EVP_PKEY(3)>,
|
|
L<provider-keymgmt(7)>,
|
|
L<EVP_KEYMGMT(3)>,
|
|
L<OSSL_PROVIDER-default(7)>,
|
|
L<OSSL_PROVIDER-FIPS(7)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2020 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
|