1=pod
2
3=head1 NAME
4
5EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
6
7=head1 DESCRIPTION
8
9For B<DSA> the FIPS186-4 standard specifies that the values used for FFC
10parameter generation are also required for parameter validation.
11This means that optional FFC domain parameter values for I<seed>, I<pcounter>
12and I<gindex> may need to be stored for validation purposes. For B<DSA> these
13fields are not stored in the ASN1 data so they need to be stored externally if
14validation is required.
15
16=head2 DSA parameters
17
18The B<DSA> key type supports the FFC parameters (see
19L<EVP_PKEY-FFC(7)/FFC parameters>).
20
21=head2 DSA key generation parameters
22
23The B<DSA> key type supports the FFC key generation parameters (see
24L<EVP_PKEY-FFC(7)/FFC key generation parameters>
25
26The following restrictions apply to the "pbits" field:
27
28For "fips186_4" this must be either 2048 or 3072.
29For "fips186_2" this must be 1024.
30For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
31
32=head1 EXAMPLES
33
34An B<EVP_PKEY> context can be obtained by calling:
35
36    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
37
38The B<DSA> domain parameters can be generated by calling:
39
40    unsigned int pbits = 2048;
41    unsigned int qbits = 256;
42    int gindex = 1;
43    OSSL_PARAM params[5];
44    EVP_PKEY *param_key = NULL;
45    EVP_PKEY_CTX *pctx = NULL;
46
47    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
48    EVP_PKEY_paramgen_init(pctx);
49
50    params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
51    params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
52    params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
53    params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
54    params[4] = OSSL_PARAM_construct_end();
55    EVP_PKEY_CTX_set_params(pctx, params);
56
57    EVP_PKEY_generate(pctx, &param_key);
58    EVP_PKEY_CTX_free(pctx);
59
60    EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
61
62A B<DSA> key can be generated using domain parameters by calling:
63
64    EVP_PKEY *key = NULL;
65    EVP_PKEY_CTX *gctx = NULL;
66
67    gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
68    EVP_PKEY_keygen_init(gctx);
69    EVP_PKEY_generate(gctx, &key);
70    EVP_PKEY_CTX_free(gctx);
71    EVP_PKEY_print_private(bio_out, key, 0, NULL);
72
73
74=head1 CONFORMING TO
75
76The following sections of FIPS 186-4:
77
78=over 4
79
80=item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
81
82=item A.2.3 Generation of canonical generator g.
83
84=item A.2.1 Unverifiable Generation of the Generator g.
85
86=back
87
88=head1 SEE ALSO
89
90L<EVP_PKEY-FFC(7)>,
91L<EVP_SIGNATURE-DSA(7)>
92L<EVP_PKEY(3)>,
93L<provider-keymgmt(7)>,
94L<EVP_KEYMGMT(3)>,
95L<OSSL_PROVIDER-default(7)>,
96L<OSSL_PROVIDER-FIPS(7)>
97
98=head1 COPYRIGHT
99
100Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
101
102Licensed under the Apache License 2.0 (the "License").  You may not use
103this file except in compliance with the License.  You can obtain a copy
104in the file LICENSE in the source distribution or at
105L<https://www.openssl.org/source/license.html>.
106
107=cut
108