doc/man7/EVP_PKEY-DSA.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
   6
   7 =head1 DESCRIPTION
   8
   9 For B<DSA> the FIPS186-4 standard specifies that the values used for FFC
  10 parameter generation are also required for parameter validation.
  11 This means that optional FFC domain parameter values for I<seed>, I<pcounter>
  12 and I<gindex> may need to be stored for validation purposes. For B<DSA> these
  13 fields are not stored in the ASN1 data so they need to be stored externally if
  14 validation is required.
  15
  16 =head2 DSA parameters
  17
  18 The B<DSA> key type supports the FFC parameters (see
  19 L<EVP_PKEY-FFC(7)/FFC parameters>).
  20
  21 =head2 DSA key generation parameters
  22
  23 The B<DSA> key type supports the FFC key generation parameters (see
  24 L<EVP_PKEY-FFC(7)/FFC key generation parameters>
  25
  26 The following restrictions apply to the "pbits" field:
  27
  28 For "fips186_4" this must be either 2048 or 3072.
  29 For "fips186_2" this must be 1024.
  30 For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
  31
  32 =head1 EXAMPLES
  33
  34 An 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
  38 The 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_gen(pctx, &param_key);
  58     EVP_PKEY_CTX_free(pctx);
  59
  60     EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
  61
  62 A 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_gen(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
  76 The 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
  90 L<EVP_PKEY-FFC(7)>,
  91 L<EVP_SIGNATURE-DSA(7)>
  92 L<EVP_PKEY(3)>,
  93 L<provider-keymgmt(7)>,
  94 L<EVP_KEYMGMT(3)>,
  95 L<OSSL_PROVIDER-default(7)>,
  96 L<OSSL_PROVIDER-FIPS(7)>
  97
  98 =head1 COPYRIGHT
  99
 100 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
 101
 102 Licensed under the Apache License 2.0 (the "License").  You may not use
 103 this file except in compliance with the License.  You can obtain a copy
 104 in the file LICENSE in the source distribution or at
 105 L<https://www.openssl.org/source/license.html>.
 106
 107 =cut