EVP_PKEY-FFC.pod 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. =pod
  2. =head1 NAME
  3. EVP_PKEY-FFC - EVP_PKEY DSA and DH/DHX shared FFC parameters.
  4. =head1 DESCRIPTION
  5. Finite field cryptography (FFC) is a method of implementing discrete logarithm
  6. cryptography using finite field mathematics. DSA is an example of FFC and
  7. Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
  8. implemented as FFC.
  9. The B<DSA>, B<DH> and B<DHX> keytypes are implemented in OpenSSL's default and
  10. FIPS providers.
  11. The implementations support the basic DSA, DH and DHX keys, containing the public
  12. and private keys I<pub> and I<priv> as well as the three main domain parameters
  13. I<p>, I<q> and I<g>.
  14. For B<DSA> (and B<DH> that is not a named group) the FIPS186-4 standard
  15. specifies that the values used for FFC parameter generation are also required
  16. for parameter validation.
  17. This means that optional FFC domain parameter values for I<seed>, I<pcounter>
  18. and I<gindex> may need to be stored for validation purposes.
  19. For B<DH> the I<seed> and I<pcounter> can be stored in ASN1 data
  20. (but the I<gindex> is not). For B<DSA> however, these fields are not stored in
  21. the ASN1 data so they need to be stored externally if validation is required.
  22. The B<DH> key type uses PKCS#3 format which saves p and g, but not the 'q' value.
  23. The B<DHX> key type uses X9.42 format which saves the value of 'q' and this
  24. must be used for FIPS186-4.
  25. =head2 FFC parameters
  26. In addition to the common parameters that all keytypes should support (see
  27. L<provider-keymgmt(7)/Common parameters>), the B<DSA>, B<DH> and B<DHX> keytype
  28. implementations support the following.
  29. =over 4
  30. =item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
  31. The public key value.
  32. =item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
  33. The private key value.
  34. =back
  35. =head2 FFC DSA, DH and DHX domain parameters
  36. =over 4
  37. =item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
  38. A DSA or Diffie-Hellman prime "p" value.
  39. =item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
  40. A DSA or Diffie-Hellman generator "g" value.
  41. =back
  42. =head2 FFC DSA and DHX domain parameters
  43. =over 4
  44. =item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
  45. A DSA or Diffie-Hellman prime "q" value.
  46. =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
  47. An optional domain parameter I<seed> value used during generation and validation
  48. of I<p>, I<q> and canonical I<g>.
  49. For validation this needs to set the I<seed> that was produced during generation.
  50. =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
  51. Sets the index to use for canonical generation and verification of the generator
  52. I<g>.
  53. Set this to a positive value from 0..FF to use this mode. This I<gindex> can
  54. then be reused during key validation to verify the value of I<g>. If this value
  55. is not set or is -1 then unverifiable generation of the generator I<g> will be
  56. used.
  57. =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
  58. An optional domain parameter I<counter> value that is output during generation
  59. of I<p>. This value must be saved if domain parameter validation is required.
  60. =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
  61. For unverifiable generation of the generator I<g> this value is output during
  62. generation of I<g>. Its value is the first integer larger than one that
  63. satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
  64. =item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
  65. An optional informational cofactor parameter that should equal to (p - 1) / q.
  66. =item "validate-pq" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_PQ>) <unsigned integer>
  67. =item "validate-g" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_G>) <unsigned integer>
  68. These boolean values are used during FIPS186-4 or FIPS186-2 key validation checks
  69. (See L<EVP_PKEY_param_check(3)>) to select validation options. By default
  70. I<validate-pq> and I<validate-g> are both set to 1 to check that p,q and g are
  71. valid. Either of these may be set to 0 to skip a test, which is mainly useful
  72. for testing purposes.
  73. =item "validate-legacy" (B<OSSL_PKEY_PARAM_FFC_VALIDATE_LEGACY>) <unsigned integer>
  74. This boolean value is used during key validation checks
  75. (See L<EVP_PKEY_param_check(3)>) to select the validation type. The default
  76. value of 0 selects FIPS186-4 validation. Setting this value to 1 selects
  77. FIPS186-2 validation.
  78. =back
  79. =head2 FFC key generation parameters
  80. The following key generation types are available for DSA and DHX algorithms:
  81. =over 4
  82. =item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <UTF8 string>
  83. Sets the type of parameter generation. The shared valid values are:
  84. =over 4
  85. =item "fips186_4"
  86. The current standard.
  87. =item "fips186_2"
  88. The old standard that should only be used for legacy purposes.
  89. =item "default"
  90. This can choose one of "fips186_4" or "fips186_2" depending on other
  91. parameters set for parameter generation.
  92. =back
  93. =item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
  94. Sets the size (in bits) of the prime 'p'.
  95. =item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
  96. Sets the size (in bits) of the prime 'q'.
  97. For "fips186_4" this can be either 224 or 256.
  98. For "fips186_2" this has a size of 160.
  99. =item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>) <UTF8 string>
  100. Sets the Digest algorithm to be used as part of the Key Generation Function
  101. associated with the given Key Generation I<ctx>.
  102. This must also be set for key validation.
  103. =item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <UTF8 string>
  104. Sets properties to be used upon look up of the implementation for the selected
  105. Digest algorithm for the Key Generation Function associated with the given key
  106. generation I<ctx>. This may also be set for key validation.
  107. =item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
  108. For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
  109. instead of generating a random seed internally. This should be used for
  110. testing purposes only. This will either produce fixed values for the generated
  111. parameters OR it will fail if the seed did not generate valid primes.
  112. =item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
  113. =item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
  114. =item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
  115. These types are described above.
  116. =back
  117. =head1 CONFORMING TO
  118. The following sections of SP800-56Ar3:
  119. =over 4
  120. =item 5.5.1.1 FFC Domain Parameter Selection/Generation
  121. =back
  122. The following sections of FIPS 186-4:
  123. =over 4
  124. =item A.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.
  125. =item A.2.3 Generation of canonical generator g.
  126. =item A.2.1 Unverifiable Generation of the Generator g.
  127. =back
  128. =head1 SEE ALSO
  129. L<EVP_PKEY-DSA(7)>,
  130. L<EVP_PKEY-DH(7)>,
  131. L<EVP_SIGNATURE-DSA(7)>,
  132. L<EVP_KEYEXCH-DH(7)>
  133. L<EVP_KEYMGMT(3)>,
  134. L<EVP_PKEY(3)>,
  135. L<provider-keymgmt(7)>,
  136. L<OSSL_PROVIDER-default(7)>,
  137. L<OSSL_PROVIDER-FIPS(7)>,
  138. =head1 COPYRIGHT
  139. Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
  140. Licensed under the Apache License 2.0 (the "License"). You may not use
  141. this file except in compliance with the License. You can obtain a copy
  142. in the file LICENSE in the source distribution or at
  143. L<https://www.openssl.org/source/license.html>.
  144. =cut