Add RFC7919 documentation.
authorDr. Stephen Henson <steve@openssl.org>
Sat, 7 Oct 2017 12:42:05 +0000 (13:42 +0100)
committerDr. Stephen Henson <steve@openssl.org>
Thu, 12 Oct 2017 01:40:30 +0000 (02:40 +0100)
Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4485)

doc/man3/DH_new_by_nid.pod [new file with mode: 0644]
doc/man3/EVP_PKEY_CTX_ctrl.pod
util/private.num

diff --git a/doc/man3/DH_new_by_nid.pod b/doc/man3/DH_new_by_nid.pod
new file mode 100644 (file)
index 0000000..73636c5
--- /dev/null
@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+DH_new_by_nid, DH_get_nid - get or find DH named parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+ DH *DH_new_by_nid(int nid);
+ int *DH_get_nid(const DH *dh);
+
+=head1 DESCRIPTION
+
+DH_new_by_nid() creates and returns a DH structure containing named parameters
+B<nid>. Currently B<nid> must be B<NID_ffdhe2048>, B<NID_ffdhe3072>,
+B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>.
+
+DH_get_nid() determines if the parameters contained in B<dh> match
+any named set. It returns the NID corresponding to the matching parameters or
+B<NID_undef> if there is no match.
+
+=head1 RETURN VALUES
+
+DH_new_by_nid() returns a set of DH parameters or B<NULL> if an error occurred.
+
+DH_get_nid() returns the NID of the matching set of parameters or
+B<NID_undef> if there is no match.
+
+=head1 COPYRIGHT
+
+Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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
index 4670aa1..2ad470b 100644 (file)
@@ -8,6 +8,7 @@ EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_keygen_bits,
 EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
 EVP_PKEY_CTX_set_dh_paramgen_prime_len,
 EVP_PKEY_CTX_set_dh_paramgen_generator,
+EVP_PKEY_CTX_set_dh_pad, EVP_PKEY_CTX_set_dh_nid,
 EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
 EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations
 
@@ -35,6 +36,8 @@ EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations
  #include <openssl/dh.h>
  int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
  int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
+ int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);
+ int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);
 
  #include <openssl/ec.h>
  int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
@@ -111,6 +114,15 @@ then 1024 is used.
 The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
 for DH parameter generation. If not specified 2 is used.
 
+The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
+1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
+If B<pad> is zero (the default) then no padding is performed.
+
+EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
+B<nid>. The B<nid> parameter must be B<NID_ffdhe2048>, B<NID_ffdhe3072>,
+B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>.  This macro can be
+called during parameter or key generation.
+
 The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
 generation to B<nid>. For EC parameter generation this macro must be called
 or an error occurs because there is no default curve.
index 8c2fa39..205efe3 100644 (file)
@@ -169,6 +169,8 @@ EVP_PKEY_CTX_set1_hkdf_salt             define
 EVP_PKEY_CTX_set1_tls1_prf_secret       define
 EVP_PKEY_CTX_set_dh_paramgen_generator  define
 EVP_PKEY_CTX_set_dh_paramgen_prime_len  define
+EVP_PKEY_CTX_set_dh_pad                 define
+EVP_PKEY_CTX_set_dh_nid                 define
 EVP_PKEY_CTX_set_dsa_paramgen_bits      define
 EVP_PKEY_CTX_set_ec_param_enc           define
 EVP_PKEY_CTX_set_ec_paramgen_curve_nid  define