Update core_names.h fields and document most fields.
authorShane Lontis <shane.lontis@oracle.com>
Tue, 26 May 2020 03:53:07 +0000 (13:53 +1000)
committerShane Lontis <shane.lontis@oracle.com>
Tue, 26 May 2020 03:53:07 +0000 (13:53 +1000)
Renamed some values in core_names i.e Some DH specific names were changed to use DH instead of FFC.
Added some strings values related to RSA keys.
Moved set_params related docs out of EVP_PKEY_CTX_ctrl.pod into its own file.
Updated Keyexchange and signature code and docs.
Moved some common DSA/DH docs into a shared EVP_PKEY-FFC.pod.
Moved Ed25519.pod into EVP_SIGNATURE-ED25519.pod and reworked it.

Added some usage examples. As a result of the usage examples the following change was also made:
ec allows OSSL_PKEY_PARAM_USE_COFACTOR_ECDH as a settable gen parameter.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11610)

41 files changed:
crypto/dh/dh_lib.c
crypto/ec/ec_backend.c
crypto/evp/pmeth_lib.c
crypto/ffc/ffc_backend.c
crypto/ffc/ffc_params.c
crypto/provider_core.c
doc/man3/EVP_KDF.pod
doc/man3/EVP_MAC.pod
doc/man3/EVP_PKEY_CTX_ctrl.pod
doc/man3/EVP_PKEY_CTX_set_params.pod [new file with mode: 0644]
doc/man7/EVP_KEYEXCH-DH.pod [new file with mode: 0644]
doc/man7/EVP_KEYEXCH-ECDH.pod [new file with mode: 0644]
doc/man7/EVP_KEYEXCH-X25519.pod [new file with mode: 0644]
doc/man7/EVP_PKEY-DH.pod [new file with mode: 0644]
doc/man7/EVP_PKEY-DSA.pod
doc/man7/EVP_PKEY-EC.pod
doc/man7/EVP_PKEY-FFC.pod [new file with mode: 0644]
doc/man7/EVP_PKEY-RSA.pod
doc/man7/EVP_PKEY-X25519.pod
doc/man7/EVP_SIGNATURE-DSA.pod [new file with mode: 0644]
doc/man7/EVP_SIGNATURE-ECDSA.pod [new file with mode: 0644]
doc/man7/EVP_SIGNATURE-ED25519.pod [moved from doc/man7/Ed25519.pod with 68% similarity]
doc/man7/EVP_SIGNATURE-RSA.pod [new file with mode: 0644]
doc/man7/OSSL_PROVIDER-FIPS.pod
doc/man7/OSSL_PROVIDER-default.pod
doc/man7/OSSL_PROVIDER-legacy.pod
doc/man7/provider-base.pod
doc/man7/provider-keyexch.pod
doc/man7/provider-signature.pod
include/crypto/ec.h
include/openssl/core_names.h
providers/fips/fipsprov.c
providers/implementations/asymciphers/rsa_enc.c
providers/implementations/keymgmt/dh_kmgmt.c
providers/implementations/keymgmt/dsa_kmgmt.c
providers/implementations/keymgmt/ec_kmgmt.c
providers/implementations/signature/dsa.c
providers/implementations/signature/eddsa.c
providers/implementations/signature/rsa.c
test/dsatest.c
test/evp_pkey_provided_test.c

index c3585f2..3a523c3 100644 (file)
@@ -475,7 +475,7 @@ int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen)
                                  EVP_PKEY_CTRL_DH_PARAMGEN_GENERATOR, gen, NULL);
 #endif
 
-    *p++ = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_FFC_GENERATOR, &gen);
+    *p++ = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_DH_GENERATOR, &gen);
     *p++ = OSSL_PARAM_construct_end();
 
     return EVP_PKEY_CTX_set_params(ctx, params);
@@ -500,7 +500,7 @@ int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int gen)
     if (name == NULL)
         return 0;
 
-    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP,
+    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_DH_GROUP,
                                             (void *)name, 0);
     *p++ = OSSL_PARAM_construct_end();
     return EVP_PKEY_CTX_set_params(ctx, params);
@@ -531,7 +531,7 @@ int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid)
     if (name == NULL)
         return 0;
 
-    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP,
+    *p++ = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_DH_GROUP,
                                             (void *)name, 0);
     *p++ = OSSL_PARAM_construct_end();
     return EVP_PKEY_CTX_set_params(ctx, params);
index 98dd0ec..fb6497b 100644 (file)
  * implementations alike.
  */
 
-int ec_set_param_ecdh_cofactor_mode(EC_KEY *ec, const OSSL_PARAM *p)
+int ec_set_ecdh_cofactor_mode(EC_KEY *ec, int mode)
 {
     const EC_GROUP *ecg = EC_KEY_get0_group(ec);
     const BIGNUM *cofactor;
-    int mode;
-
-    if (!OSSL_PARAM_get_int(p, &mode))
-        return 0;
-
     /*
      * mode can be only 0 for disable, or 1 for enable here.
      *
@@ -224,8 +219,12 @@ int ec_key_otherparams_fromdata(EC_KEY *ec, const OSSL_PARAM params[])
         return 0;
 
     p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_USE_COFACTOR_ECDH);
-    if (p != NULL && !ec_set_param_ecdh_cofactor_mode(ec, p))
-        return 0;
+    if (p != NULL) {
+        int mode;
 
+        if (!OSSL_PARAM_get_int(p, &mode)
+            || !ec_set_ecdh_cofactor_mode(ec, mode))
+            return 0;
+    }
     return 1;
 }
index e4327b3..355565d 100644 (file)
@@ -1033,7 +1033,7 @@ static int legacy_ctrl_str_to_param(EVP_PKEY_CTX *ctx, const char *name,
 # endif
 # ifndef OPENSSL_NO_DH
     else if (strcmp(name, "dh_paramgen_generator") == 0)
-        name = OSSL_PKEY_PARAM_FFC_GENERATOR;
+        name = OSSL_PKEY_PARAM_DH_GENERATOR;
     else if (strcmp(name, "dh_paramgen_prime_len") == 0)
         name = OSSL_PKEY_PARAM_FFC_PBITS;
     else if (strcmp(name, "dh_paramgen_subprime_len") == 0)
@@ -1042,9 +1042,9 @@ static int legacy_ctrl_str_to_param(EVP_PKEY_CTX *ctx, const char *name,
         name = OSSL_PKEY_PARAM_FFC_TYPE;
         value = dh_gen_type_id2name(atoi(value));
     } else if (strcmp(name, "dh_param") == 0)
-        name = OSSL_PKEY_PARAM_FFC_GROUP;
+        name = OSSL_PKEY_PARAM_DH_GROUP;
     else if (strcmp(name, "dh_rfc5114") == 0) {
-        name = OSSL_PKEY_PARAM_FFC_GROUP;
+        name = OSSL_PKEY_PARAM_DH_GROUP;
         value = ffc_named_group_from_uid(atoi(value));
     } else if (strcmp(name, "dh_pad") == 0)
         name = OSSL_EXCHANGE_PARAM_PAD;
index 1cfa427..c34e79b 100644 (file)
@@ -27,7 +27,7 @@ int ffc_params_fromdata(FFC_PARAMS *ffc, const OSSL_PARAM params[])
     if (ffc == NULL)
         return 0;
 
-    prm  = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_FFC_GROUP);
+    prm  = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_DH_GROUP);
     if (prm != NULL) {
         if (prm->data_type != OSSL_PARAM_UTF8_STRING)
             goto err;
index efd7dc8..a95a2fa 100644 (file)
@@ -220,7 +220,7 @@ int ffc_params_todata(const FFC_PARAMS *ffc, OSSL_PARAM_BLD *bld,
 
         if (name == NULL
             || !ossl_param_build_set_utf8_string(bld, params,
-                                                 OSSL_PKEY_PARAM_FFC_GROUP,
+                                                 OSSL_PKEY_PARAM_DH_GROUP,
                                                  name))
             return 0;
 #else
index 0c21660..f8aa572 100644 (file)
@@ -841,8 +841,13 @@ int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
  * never knows.
  */
 static const OSSL_PARAM param_types[] = {
-    OSSL_PARAM_DEFN("openssl-version", OSSL_PARAM_UTF8_PTR, NULL, 0),
-    OSSL_PARAM_DEFN("provider-name", OSSL_PARAM_UTF8_PTR, NULL, 0),
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_VERSION, OSSL_PARAM_UTF8_PTR, NULL, 0),
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_PROV_NAME, OSSL_PARAM_UTF8_PTR,
+                    NULL, 0),
+#ifndef FIPS_MODULE
+    OSSL_PARAM_DEFN(OSSL_PROV_PARAM_CORE_MODULE_FILENAME, OSSL_PARAM_UTF8_PTR,
+                    NULL, 0),
+#endif
     OSSL_PARAM_END
 };
 
@@ -879,13 +884,14 @@ static int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[])
      */
     OSSL_PROVIDER *prov = (OSSL_PROVIDER *)handle;
 
-    if ((p = OSSL_PARAM_locate(params, "openssl-version")) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_VERSION)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, OPENSSL_VERSION_STR);
-    if ((p = OSSL_PARAM_locate(params, "provider-name")) != NULL)
+    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_CORE_PROV_NAME)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, prov->name);
 
 #ifndef FIPS_MODULE
-    if ((p = OSSL_PARAM_locate(params, OSSL_PROV_PARAM_MODULE_FILENAME)) != NULL)
+    if ((p = OSSL_PARAM_locate(params,
+                               OSSL_PROV_PARAM_CORE_MODULE_FILENAME)) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, ossl_provider_module_path(prov));
 #endif
 
index 2d7fe49..bceee3f 100644 (file)
@@ -68,6 +68,9 @@ EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given
 a library context I<libctx> and a set of I<properties>.
 See L<provider(7)/Fetching algorithms> for further information.
 
+See L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)> for the lists of
+algorithms supported by the default provider.
+
 The returned value must eventually be freed with
 L<EVP_KDF_free(3)>.
 
@@ -248,14 +251,7 @@ supported by the KDF algorithm.
 
 =head1 SEE ALSO
 
-L<EVP_KDF-SCRYPT(7)>
-L<EVP_KDF-TLS1_PRF(7)>
-L<EVP_KDF-PBKDF2(7)>
-L<EVP_KDF-HKDF(7)>
-L<EVP_KDF-SS(7)>
-L<EVP_KDF-SSHKDF(7)>
-L<EVP_KDF-X963(7)>
-L<EVP_KDF-X942(7)>
+L<OSSL_PROVIDER-default(7)/Key Derivation Function (KDF)>
 
 =head1 HISTORY
 
index 1b961d4..c98c8d8 100644 (file)
@@ -82,6 +82,9 @@ EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
 a library context I<libctx> and a set of I<properties>.
 See L<provider(7)/Fetching algorithms> for further information.
 
+See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list
+of algorithms supported by the default provider.
+
 The returned value must eventually be freed with
 L<EVP_MAC_free(3)>.
 
index 039073c..db91f01 100644 (file)
@@ -2,10 +2,6 @@
 
 =head1 NAME
 
-EVP_PKEY_CTX_get_params,
-EVP_PKEY_CTX_gettable_params,
-EVP_PKEY_CTX_set_params,
-EVP_PKEY_CTX_settable_params,
 EVP_PKEY_CTX_ctrl,
 EVP_PKEY_CTX_ctrl_str,
 EVP_PKEY_CTX_ctrl_uint64,
@@ -78,11 +74,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
  #include <openssl/evp.h>
 
- int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
- const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
- const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
-
  int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
                        int cmd, int p1, void *p2);
  int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
@@ -186,49 +177,6 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions get and
-send arbitrary parameters from and to the algorithm implementation respectively.
-Not all parameters may be supported by all providers.
-See L<OSSL_PROVIDER(3)> for more information on providers.
-See L<OSSL_PARAM(3)> for more information on parameters.
-These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation.
-
-The parameters currently supported by the default provider are:
-
-=over 4
-
-=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
-
-Sets the DH padding mode.
-If B<OSSL_EXCHANGE_PARAM_PAD> is 1 then the  shared secret is padded with zeros
-up to the size of the DH prime I<p>.
-If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
-performed.
-
-=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
-
-Gets and sets the name of the digest algorithm used for the input to the
-signature functions.
-
-=item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
-
-Gets and sets the output size of the digest algorithm used for the input to the
-signature functions.
-The length of the "digest-size" parameter should not exceed that of a B<size_t>.
-The internal algorithm that supports this parameter is DSA.
-
-=back
-
-EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() gets a
-constant B<OSSL_PARAM> array that describes the  gettable and
-settable parameters for the current algorithm implementation, i.e. parameters
-that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
-respectively.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
-These functions must only be called after the EVP_PKEY_CTX has been initialised
-for use in an operation.
-
 The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
 I<ctx>. The key type used must match I<keytype> if it is not -1. The parameter
 I<optype> is a mask indicating which operations the control can be applied to.
@@ -662,17 +610,13 @@ allocate adequate memory space for the I<id> before calling EVP_PKEY_CTX_get1_id
 
 =head1 RETURN VALUES
 
-EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
-EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
-error.
-It may also return NULL if there are no settable parameters available.
-
 All other functions and macros described on this page return a positive value
 for success and 0 or a negative value for failure. In particular a return value
 of -2 indicates the operation is not supported by the public key algorithm.
 
 =head1 SEE ALSO
 
+L<EVP_PKEY_CTX_set_params(3)>,
 L<EVP_PKEY_CTX_new(3)>,
 L<EVP_PKEY_encrypt(3)>,
 L<EVP_PKEY_decrypt(3)>,
diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod
new file mode 100644 (file)
index 0000000..b4959c6
--- /dev/null
@@ -0,0 +1,95 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_CTX_set_params,
+EVP_PKEY_CTX_settable_params,
+EVP_PKEY_CTX_get_params,
+EVP_PKEY_CTX_gettable_params
+- provider parameter passing operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_CTX_set_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_settable_params(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_CTX_get_params(EVP_PKEY_CTX *ctx, OSSL_PARAM *params);
+ const OSSL_PARAM *EVP_PKEY_CTX_gettable_params(EVP_PKEY_CTX *ctx);
+
+=head1 DESCRIPTION
+
+The EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() functions allow
+transfer of arbitrary key parameters to and from providers.
+Not all parameters may be supported by all providers.
+See L<OSSL_PROVIDER(3)> for more information on providers.
+See L<OSSL_PARAM(3)> for more information on parameters.
+These functions must only be called after the EVP_PKEY_CTX has been initialised
+for use in an operation.
+These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now
+calls these methods internally to interact with providers).
+
+EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a
+constant B<OSSL_PARAM> array that describes the gettable and
+settable parameters for the current algorithm implementation, i.e. parameters
+that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params()
+respectively.
+See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+These functions must only be called after the EVP_PKEY_CTX has been initialised
+for use in an operation.
+
+=head2 Parameters
+
+Examples of EVP_PKEY parameters include the following:
+
+L<provider-keymgmt(7)/Common parameters>
+L<provider-keyexch(7)/Key Exchange parameters>
+L<provider-signature(7)/Signature parameters>
+
+L<EVP_PKEY-RSA(7)/Common RSA parameters>
+L<EVP_PKEY-RSA(7)/RSA key generation parameters>
+L<EVP_PKEY-FFC(7)/FFC parameters>
+L<EVP_PKEY-FFC(7)/FFC key generation parameters>
+L<EVP_PKEY-DSA(7)/DSA parameters>
+L<EVP_PKEY-DSA(7)/DSA key generation parameters>
+L<EVP_PKEY-DH(7)/DH parameters>
+L<EVP_PKEY-DH(7)/DH key generation parameters>
+L<EVP_PKEY-EC(7)/Common EC parameters>
+L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
+
+=head1 RETURN VALUES
+
+EVP_PKEY_CTX_set_params() returns 1 for success or 0 otherwise.
+EVP_PKEY_CTX_settable_params() returns an OSSL_PARAM array on success or NULL on
+error.
+It may also return NULL if there are no settable parameters available.
+
+All other functions and macros described on this page return a positive value
+for success and 0 or a negative value for failure. In particular a return value
+of -2 indicates the operation is not supported by the public key algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_encrypt(3)>,
+L<EVP_PKEY_decrypt(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<EVP_PKEY_verify_recover(3)>,
+L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY_keygen(3)>
+
+=head1 HISTORY
+
+All functions were added in OpenSSL 3.0.
+
+=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
diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod
new file mode 100644 (file)
index 0000000..9e9cee7
--- /dev/null
@@ -0,0 +1,98 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-DH
+- DH Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<DH> key type.
+
+=head2 DH key exchange parameters
+
+=over 4
+
+=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=back
+
+=head1 EXAMPLES
+
+The examples assume a host and peer both generate keys using the same
+named group (or domain parameters). See L<EVP_PKEY-DH(7)/Examples>.
+Both the host and peer transfer their public key to each other.
+
+To convert the peer's generated key pair to a public key in DER format in order
+to transfer to the host:
+
+    EVP_PKEY *peer_key; /* It is assumed this contains the peers generated key */
+    unsigned char *peer_pub_der = NULL;
+    int peer_pub_der_len;
+
+    peer_pub_der_len = i2d_PUBKEY(peer_key, &peer_pub_der);
+    ...
+    OPENSSL_free(peer_pub_der);
+
+To convert the received peer's public key from DER format on the host:
+
+    const unsigned char *pd = peer_pub_der;
+    EVP_PKEY *peer_pub_key = d2i_PUBKEY(NULL, &pd, peer_pub_der_len);
+    ...
+    EVP_PKEY_free(peer_pub_key);
+
+To derive a shared secret on the host using the host's key and the peer's public
+key:
+    /* It is assumed that the host_key and peer_pub_key are set up */
+    void derive_secret(EVP_KEY *host_key, EVP_PKEY *peer_pub_key)
+    {
+        unsigned int pad = 1;
+        OSSL_PARAM params[2];
+        unsigned char *secret = NULL;
+        size_t secret_len = 0;
+        EVP_PKEY_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
+
+        EVP_PKEY_derive_init(dctx);
+
+        /* Optionally set the padding */
+        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
+        params[1] = OSSL_PARAM_construct_end();
+        EVP_PKEY_CTX_set_params(dctx, params);
+
+        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
+
+        /* Get the size by passing NULL as the buffer */
+        EVP_PKEY_derive(dctx, NULL, &secret_len);
+        secret = OPENSSL_zalloc(secret_len);
+
+        EVP_PKEY_derive(dctx, secret, &secret_len);
+        ...
+        OPENSSL_clear_free(secret, secret_len);
+        EVP_PKEY_CTX_free(dctx);
+    }
+
+Very similar code can be used by the peer to derive the same shared secret
+using the host's public key and the peer's generated key pair.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-DH(7)>,
+L<EVP_PKEY-FFC(7)>,
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+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
diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod
new file mode 100644 (file)
index 0000000..1add4b7
--- /dev/null
@@ -0,0 +1,133 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<ECDH> key type.
+
+=head2 ECDH Key Exchange parameters
+
+=over 4
+
+=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
+
+Sets or gets the ECDH mode of operation for the associated key exchange ctx.
+
+In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
+can be used to select between the plain Diffie-Hellman (DH) or Cofactor
+Diffie-Hellman (CDH) variants of the key exchange algorithm.
+
+When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
+on, off, or resetting it to the default for the private key associated with the
+given key exchange ctx.
+
+When getting, the value should be either 1 or 0, respectively signaling if the
+cofactor mode is on or off.
+
+See also L<provider-keymgmt(7)> for the related
+B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
+per-key basis.
+
+=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
+
+Sets or gets the Key Derivation Function type to apply within the associated key
+exchange ctx.
+
+=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
+
+Sets or gets the Digest algorithm to be used as part of the Key Derivation Function
+associated with the given key exchange ctx.
+
+=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
+
+Sets properties to be used upon look up of the implementation for the selected
+Digest algorithm for the Key Derivation Function associated with the given key
+exchange ctx.
+
+=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
+
+Sets or gets the desired size for the output of the chosen Key Derivation Function
+associated with the given key exchange ctx.
+
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
+
+Sets the User Key Material to be used as part of the selected Key Derivation
+Function associated with the given key exchange ctx.
+
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
+
+Gets a pointer to the User Key Material to be used as part of the selected
+Key Derivation Function associated with the given key exchange ctx.
+
+=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
+
+Gets the size of the User Key Material to be used as part of the selected
+Key Derivation Function associated with the given key exchange ctx.
+
+=back
+
+=head1 EXAMPLES
+
+Keys for the host and peer must be generated as shown in
+L<EVP_PKEY-EC(7)/Examples> using the same curve name.
+
+The code to generate a shared secret for the normal case is identical to
+L<EVP_KEYEXCH-DH(7)/Examples>. 
+
+To derive a shared secret on the host using the host's key and the peer's public
+key but also using X963KDF with a user key material:
+
+    /* It is assumed that the host_key, peer_pub_key and ukm are set up */
+    void derive_secret(EVP_PKEY *host_key, EVP_PKEY *peer_key,
+                       unsigned char *ukm, size_t ukm_len)
+    {
+        unsigned char secret[64];
+        size_t out_len = sizeof(secret);
+        size_t secret_len = out_len;
+        unsigned int pad = 1;
+        OSSL_PARAM params[6];
+        EVP_PKET_CTX *dctx = EVP_PKEY_CTX_new_from_pkey(NULL, host_key, NULL);
+
+        EVP_PKEY_derive_init(dctx);
+
+        params[0] = OSSL_PARAM_construct_uint(OSSL_EXCHANGE_PARAM_PAD, &pad);
+        params[1] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_TYPE,
+                                                     "X963KDF", 0);
+        params[2] = OSSL_PARAM_construct_utf8_string(OSSL_EXCHANGE_PARAM_KDF_DIGEST,
+                                                     "SHA1", 0);
+        params[3] = OSSL_PARAM_construct_size_t(OSSL_EXCHANGE_PARAM_KDF_OUTLEN,
+                                                &out_len);
+        params[4] = OSSL_PARAM_construct_octet_string(OSSL_EXCHANGE_PARAM_KDF_UKM,
+                                                      ukm, ukm_len);
+        params[5] = OSSL_PARAM_construct_end();
+        EVP_PKEY_CTX_set_params(dctx, params);
+
+        EVP_PKEY_derive_set_peer(dctx, peer_pub_key);
+        EVP_PKEY_derive(dctx, secret, &secret_len);
+        ...
+        OPENSSL_clear_free(secret, secret_len);
+        EVP_PKEY_CTX_free(dctx);
+    }
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-EC(7)>
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+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
diff --git a/doc/man7/EVP_KEYEXCH-X25519.pod b/doc/man7/EVP_KEYEXCH-X25519.pod
new file mode 100644 (file)
index 0000000..6140c56
--- /dev/null
@@ -0,0 +1,50 @@
+=pod
+
+=head1 NAME
+
+EVP_KEYEXCH-X25519,
+EVP_KEYEXCH-X448
+- X25519 and X448 Key Exchange algorithm support
+
+=head1 DESCRIPTION
+
+Key exchange support for the B<X25519> and B<X448> key types.
+
+=head2 Key exchange parameters
+
+=over 4
+
+=item "pad" (B<OSSL_EXCHANGE_PARAM_PAD>) <unsigned integer>
+
+See L<provider-keyexch(7)/Common Key Exchange parameters>.
+
+=back
+
+=head1 EXAMPLES
+
+Keys for the host and peer can be generated as shown in
+L<EVP_PKEY-X25519(7)/Examples>.
+
+The code to generate a shared secret is identical to
+L<EVP_KEYEXCH-DH(7)/Examples>.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY-FFC(7)>,
+L<EVP_PKEY-DH(7)>
+L<EVP_PKEY(3)>,
+L<provider-keyexch(7)>,
+L<provider-keymgmt(7)>,
+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
diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod
new file mode 100644 (file)
index 0000000..33b19a7
--- /dev/null
@@ -0,0 +1,229 @@
+=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_DH_GROUP>) <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>.
+
+=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 valure 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, &param_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
index ccb34a9..680717b 100644 (file)
 
 =head1 NAME
 
-EVP_PKEY-DSA, EVP_KEYMGMT-DSA, EVP_PKEY-DH, EVP_KEYMGMT-DH
-- EVP_PKEY DSA and DH keytype and algorithm support
+EVP_PKEY-DSA, EVP_KEYMGMT-DSA - EVP_PKEY DSA keytype and algorithm support
 
 =head1 DESCRIPTION
 
-The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
-providers.
-The implementations support the basic DSA and DH keys, containing the public
-and private keys I<pub> and I<priv> as well as the three main domain parameters
-I<p>, I<q> and I<g>.
-
-Finite field cryptography (FFC) is a method of implementing discrete logarithm
-cryptography using finite field mathematics. DSA is an example of FFC and
-Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
-implemented as FFC.
-
-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.
-
-For B<DSA> (and 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.
+For B<DSA> 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). For B<DSA> however, these fields are not stored in
-the ASN1 data so they need to be stored externally if validation is required.
+and I<gindex> may need to be stored for validation purposes. For B<DSA> these
+fields are not stored in the ASN1 data so they need to be stored externally if
+validation is required.
 
-=head2 Common DH parameters
+=head2 DSA parameters
 
-=over 4
-
-=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
-
-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 default and OpenSSL's 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 the 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_FFC_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>.
-
-=back
-
-=head2 Common DSA & DH parameters
-
-In addition to the common parameters that all keytypes should support (see
-L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
-implementations support the following.
-
-=over 4
-
-=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
-
-The public key value.
-
-=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
-
-The private key value.
-
-=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
+The B<DSA> key type supports the FFC parameters (see
+L<EVP_PKEY-FFC(7)/FFC parameters>).
 
-A DSA or Diffie-Hellman prime "p" value.
+=head2 DSA key generation parameters
 
-=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
+The B<DSA> key type supports the FFC key generation parameters (see
+L<EVP_PKEY-FFC(7)/FFC key generation parameters>
 
-A DSA or Diffie-Hellman prime "q" value.
-
-=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
-
-A DSA or Diffie-Hellman generator "g" value.
-
-=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
-
-An optional domain parameter I<seed> value used during generation and validation
-of I<p>, I<q> and canonical I<g>.
-For validation this needs to set the I<seed> that was produced during generation.
-
-=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
-
-Sets the index to use for canonical generation and verification of the generator
-I<g>.
-Set this to a positive value from 0..FF to use this mode. This I<gindex> can
-then be reused during key validation to verify the value of I<g>. If this value
-is not set or is -1 then unverifiable generation of the generator I<g> will be
-used.
-
-=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
-
-An optional domain parameter I<counter> value that is output during generation
-of I<p>. This value must be saved if domain parameter validation is required.
-
-=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
-
-For unverifiable generation of the generator I<g> this value is output during 
-generation of I<g>. Its value is the first integer larger than one that
-satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
-
-=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
-
-An optional informational cofactor parameter that should equal (p - 1) / q.
-
-=back
-
-
-=head2 DSA / DH key generation (FFC) parameters
-
-The following Key Generation types are available for the built-in FFC algorithms:
-
-=over 4
+The following restrictions apply to the "pbits" field:
 
-=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
-
-Sets the type of parameter generation. For DH Valid values are:
-
-=over 4
-
-=item "fips186_4"
-
-The current standard. This is the default value.
-
-=item "default"
-
-This is an alias to use the latest implemented standard.
-It is currently set to "fips186_4".
-
-=item "group"
-
-This specifies that a named safe prime name will be chosen using the "pbits"
-type.
-
-=item "fips186_2"
-
-The old standard that should only be used for legacy purposes.
-
-=item "generator"
-
-A safe prime generator. See the "safeprime-generator" type.
-
-=back
-
-For DSA valid values are one of "default", "fips186_4" or "fips186_2" as
-described above.
-
-=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 DH, and either of 2048 or 3072 for DSA.
+For "fips186_4" this must be either 2048 or 3072.
 For "fips186_2" this must be 1024.
 For "group" this can be any one of 2048, 3072, 4096, 6144 or 8192.
 
-=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
+=head1 EXAMPLES
 
-Sets the size (in bits) of the prime 'q'.
+An B<EVP_PKEY> context can be obtained by calling:
 
-For "fips186_4" this can be either 224 or 256.
-For "fips186_2" this has a size of 160.
+    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
 
-=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>)  <utf8_string>
+An B<DH> domain parameters key can be generated by calling:
 
-Sets the Digest algorithm to be used as part of the Key Generation Function
-associated with the given Key Generation I<ctx>.
-This must also be set for key validation.
+    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;
 
-=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
+    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
+    EVP_PKEY_paramgen_init(pctx);
 
-Sets properties to be used upon look up of the implementation for the selected
-Digest algorithm for the Key Generation Function associated with the given key
-generation I<ctx>. This may also be set for key validation.
+    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);
 
-=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
+    EVP_PKEY_gen(pctx, &param_key);
+    EVP_PKEY_CTX_free(pctx);
 
-For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
-instead of generating a random seed internally. This should be used for
-testing purposes only. This will either produce fixed values for the generated
-parameters OR it will fail if the seed did not generate valid primes.
+    EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
 
-=item "group" (B<OSSL_PKEY_PARAM_FFC_GROUP>) <UTF8 string>
+An B<DSA> key can be generated using domain parameters by calling:
 
-=item "safeprime-generator" (B<OSSL_PKEY_PARAM_FFC_GENERATOR>) <integer>
+    EVP_PKEY *key = NULL;
+    EVP_PKEY_CTX *gctx = NULL;
 
-=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
-
-=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
-
-=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
-
-These types are described above.
-
-=back
+    gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
+    EVP_PKEY_keygen_init(gctx);
+    EVP_PKEY_gen(gctx, &key);
+    EVP_PKEY_CTX_free(gctx);
+    EVP_PKEY_print_private(bio_out, key, 0, NULL);
 
 
 =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
@@ -250,9 +87,13 @@ The following sections of FIPS 186-4:
 
 =head1 SEE ALSO
 
-L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
-L<OSSL_PROVIDER-default(7)>, L<OSSL_PROVIDER-FIPS(7)>,
-L<EVP_SIGNATURE-DSA(7)>, L<EVP_KEYEXCH-DH(7)>
+L<EVP_PKEY-FFC(7)>,
+L<EVP_SIGNATURE-DSA(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
 
index 88d0ebd..1995cf7 100644 (file)
@@ -2,7 +2,9 @@
 
 =head1 NAME
 
-EVP_PKEY-EC - EVP_PKEY EC keytype and algorithm support
+EVP_PKEY-EC,
+EVP_KEYMGMT-EC
+- EVP_PKEY EC keytype and algorithm support
 
 =head1 DESCRIPTION
 
@@ -24,9 +26,8 @@ Enable Cofactor DH (ECC CDH) if this value is 1, otherwise it uses normal EC DH
 if the value is zero. The cofactor variant multiplies the shared secret by the
 EC curve's cofactor (note for some curves the cofactor is 1).
 
-=for comment The following link should become L<EVP_KEYEXCH-ECDH(7)>
 
-See also L<provider-keyexch(7)> for the related
+See also L<EVP_KEYEXCH-ECDH(7)> for the related
 B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
 per-operation basis.
 
@@ -47,10 +48,68 @@ An B<EVP_PKEY> context can be obtained by calling:
     EVP_PKEY_CTX *pctx =
         EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 
+An B<EVP_PKEY> ECDSA or ECDH key can be generated with a "P-256" named group by
+calling:
+
+    EVP_PKEY *key = NULL;
+    OSSL_PARAM params[2];
+    EVP_PKEY_CTX *gctx =
+        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
+
+    EVP_PKEY_keygen_init(gctx);
+
+    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_EC_NAME,
+                                                 "P-256", 0);
+    params[1] = OSSL_PARAM_construct_end();
+    EVP_PKEY_CTX_set_params(gctx, params);
+
+    EVP_PKEY_gen(gctx, &key);
+
+    EVP_PKEY_print_private(bio_out, key, 0, NULL);
+    ...
+    EVP_PKEY_free(key);
+    EVP_PKEY_CTX_free(gctx);
+
+An B<EVP_PKEY> EC CDH (Cofactor Diffie-Hellman) key can be generated with a
+"K-571" named group by calling:
+
+    int use_cdh = 1;
+    EVP_PKEY *key = NULL;
+    OSSL_PARAM params[3];
+    EVP_PKEY_CTX *gctx =
+        EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
+
+    EVP_PKEY *key = NULL;
+    OSSL_PARAM params[3];
+    EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
+
+    EVP_PKEY_keygen_init(gctx);
+
+    params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_EC_NAME,
+                                                 "K-571", 0);
+    /*
+     * This curve has a cofactor that is not 1 - so setting CDH mode changes
+     * the behaviour. For many curves the cofactor is 1 - so setting this has
+     * no effect.
+     */
+    params[1] = OSSL_PARAM_construct_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH,
+                                         &use_cdh);
+    params[2] = OSSL_PARAM_construct_end();
+    EVP_PKEY_CTX_set_params(gctx, params);
+
+    EVP_PKEY_gen(gctx, &key);
+    EVP_PKEY_print_private(bio_out, key, 0, NULL);
+    ...
+    EVP_PKEY_free(key);
+    EVP_PKEY_CTX_free(gctx);
+
 =head1 SEE ALSO
 
-L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
-L<EVP_SIGNATURE-ECDSA(7)>, L<EVP_KEYEXCH-ECDH(7)>
+L<EVP_KEYMGMT(3)>,
+L<EVP_PKEY(3)>,
+L<provider-keymgmt(7)>,
+L<EVP_SIGNATURE-ECDSA(7)>,
+L<EVP_KEYEXCH-ECDH(7)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/EVP_PKEY-FFC.pod b/doc/man7/EVP_PKEY-FFC.pod
new file mode 100644 (file)
index 0000000..e97a1c6
--- /dev/null
@@ -0,0 +1,199 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY-FFC - EVP_PKEY DSA and DH shared FFC parameters.
+
+=head1 DESCRIPTION
+
+Finite field cryptography (FFC) is a method of implementing discrete logarithm
+cryptography using finite field mathematics. DSA is an example of FFC and
+Diffie-Hellman key establishment algorithms specified in SP800-56A can also be
+implemented as FFC.
+
+The B<DSA> and B<DH> keytypes are implemented in OpenSSL's default and FIPS
+providers.
+The implementations support the basic DSA and DH keys, containing the public
+and private keys I<pub> and I<priv> as well as the three main domain parameters
+I<p>, I<q> and I<g>.
+
+For B<DSA> (and 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). For B<DSA> however, these fields are not stored in
+the ASN1 data so they need to be stored externally if validation is required.
+
+=head2 FFC parameters
+
+In addition to the common parameters that all keytypes should support (see
+L<provider-keymgmt(7)/Common parameters>), the B<DSA> and B<DH> keytype
+implementations support the following.
+
+=over 4
+
+=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <unsigned integer>
+
+The public key value.
+
+=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <unsigned integer>
+
+The private key value.
+
+=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <unsigned integer>
+
+A DSA or Diffie-Hellman prime "p" value.
+
+=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <unsigned integer>
+
+A DSA or Diffie-Hellman prime "q" value.
+
+=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <unsigned integer>
+
+A DSA or Diffie-Hellman generator "g" value.
+
+=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
+
+An optional domain parameter I<seed> value used during generation and validation
+of I<p>, I<q> and canonical I<g>.
+For validation this needs to set the I<seed> that was produced during generation.
+
+=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
+
+Sets the index to use for canonical generation and verification of the generator
+I<g>.
+Set this to a positive value from 0..FF to use this mode. This I<gindex> can
+then be reused during key validation to verify the value of I<g>. If this value
+is not set or is -1 then unverifiable generation of the generator I<g> will be
+used.
+
+=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
+
+An optional domain parameter I<counter> value that is output during generation
+of I<p>. This value must be saved if domain parameter validation is required.
+
+=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
+
+For unverifiable generation of the generator I<g> this value is output during 
+generation of I<g>. Its value is the first integer larger than one that
+satisfies g = h^j mod p (where g != 1 and "j" is the cofactor).
+
+=item "j" (B<OSSL_PKEY_PARAM_FFC_COFACTOR>) <unsigned integer>
+
+An optional informational cofactor parameter that should equal to (p - 1) / q.
+
+=back
+
+=head2 FFC key generation parameters
+
+The following key generation types are available for DSA and DH algorithms:
+
+=over 4
+
+=item "type" (B<OSSL_PKEY_PARAM_FFC_TYPE>) <utf8_string>
+
+Sets the type of parameter generation. The shared valid values are:
+
+=over 4
+
+=item "fips186_4"
+
+The current standard. This is the default value.
+
+=item "fips186_2"
+
+The old standard that should only be used for legacy purposes.
+
+=item "default"
+
+This is an alias to use the latest implemented standard.
+It is currently set to "fips186_4".
+
+=back
+
+=item "pbits" (B<OSSL_PKEY_PARAM_FFC_PBITS>) <unsigned integer>
+
+Sets the size (in bits) of the prime 'p'.
+
+=item "qbits" (B<OSSL_PKEY_PARAM_FFC_QBITS>) <unsigned integer>
+
+Sets the size (in bits) of the prime 'q'.
+
+For "fips186_4" this can be either 224 or 256.
+For "fips186_2" this has a size of 160.
+
+=item "digest" (B<OSSL_PKEY_PARAM_FFC_DIGEST>)  <utf8_string>
+
+Sets the Digest algorithm to be used as part of the Key Generation Function
+associated with the given Key Generation I<ctx>.
+This must also be set for key validation.
+
+=item "properties" (B<OSSL_PKEY_PARAM_FFC_DIGEST_PROPS>) <utf8_string>
+
+Sets properties to be used upon look up of the implementation for the selected
+Digest algorithm for the Key Generation Function associated with the given key
+generation I<ctx>. This may also be set for key validation.
+
+=item "seed" (B<OSSL_PKEY_PARAM_FFC_SEED>) <octet string>
+
+For "fips186_4" or "fips186_2" generation this sets the I<seed> data to use
+instead of generating a random seed internally. This should be used for
+testing purposes only. This will either produce fixed values for the generated
+parameters OR it will fail if the seed did not generate valid primes.
+
+=item "gindex" (B<OSSL_PKEY_PARAM_FFC_GINDEX>) <integer>
+
+=item "pcounter" (B<OSSL_PKEY_PARAM_FFC_PCOUNTER>) <integer>
+
+=item "hindex" (B<OSSL_PKEY_PARAM_FFC_H>) <integer>
+
+These types are described above.
+
+=back
+
+=head1 CONFORMING TO
+
+The following sections of SP800-56Ar3:
+
+=over 4
+
+=item 5.5.1.1 FFC Domain Parameter Selection/Generation
+
+=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-DSA(7)>,
+L<EVP_PKEY-DH(7)>,
+L<EVP_SIGNATURE-DSA(7)>,
+L<EVP_KEYEXCH-DH(7)>
+L<EVP_KEYMGMT(3)>,
+L<EVP_PKEY(3)>,
+L<provider-keymgmt(7)>,
+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
index c6533f2..ad49284 100644 (file)
@@ -121,6 +121,7 @@ The value should be the number of primes for the generated B<RSA> key.  The
 default is 2.  It isn't permitted to specify a larger number of primes than
 10.  Additionally, the number of primes is limited by the length of the key
 being generated so the maximum number could be less.
+Some providers may only support a value of 2.
 
 =back
 
@@ -158,15 +159,17 @@ An B<RSA> key can be generated with key generation parameters:
     unsigned int bits = 4096;
     OSSL_PARAM params[3];
     EVP_PKEY *pkey = NULL;
-    EVP_PKEY_CTX *pctx =
-        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
+    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 
-    params[0] = OSSL_PARAM_construct_uint("bits", bits);
-    params[1] = OSSL_PARAM_construct_uint("primes", primes);
-    params[2] = OSSL_PARAM_END;
     EVP_PKEY_keygen_init(pctx);
+
+    params[0] = OSSL_PARAM_construct_uint("bits", &bits);
+    params[1] = OSSL_PARAM_construct_uint("primes", &primes);
+    params[2] = OSSL_PARAM_construct_end();
     EVP_PKEY_CTX_set_params(pctx, params);
+
     EVP_PKEY_gen(pctx, &pkey);
+    EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
     EVP_PKEY_CTX_free(pctx);
 
 =head1 SEE ALSO
index 58f7525..fa8c868 100644 (file)
@@ -15,6 +15,8 @@ private key I<priv>.
 
 In the FIPS provider they are non-approved algorithms and do not have the
 "fips=yes" property set.
+No additional parameters can be set during key generation.
+
 
 =head2 Common X25519, X448, ED25519 and ED448 parameters
 
@@ -50,6 +52,8 @@ The empty string, signifying that no digest may be specified.
 
 =item RFC 8032
 
+=item RFC 8410
+
 =back
 
 =head1 EXAMPLES
diff --git a/doc/man7/EVP_SIGNATURE-DSA.pod b/doc/man7/EVP_SIGNATURE-DSA.pod
new file mode 100644 (file)
index 0000000..11fe500
--- /dev/null
@@ -0,0 +1,58 @@
+=pod
+
+=head1 NAME
+
+EVP_SIGNATURE-DSA
+- The B<EVP_PKEY> DSA signature implementation
+
+=head1 DESCRIPTION
+
+Support for computing DSA signatures.
+See L<EVP_PKEY-DSA(7)> for information related to DSA keys.
+
+=head2 Signature Parameters
+
+The following signature parameters can be set using EVP_PKEY_CTX_set_params().
+This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
+and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). 
+
+=over 4
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
+
+The settable parameters are described in L<provider-signature(7)>.
+
+=back
+
+The following signature parameters can be retrieved using
+EVP_PKEY_CTX_get_params().
+
+=over 4
+
+=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+The gettable parameters are described in L<provider-signature(7)>.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_set_params(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<provider-signature(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
diff --git a/doc/man7/EVP_SIGNATURE-ECDSA.pod b/doc/man7/EVP_SIGNATURE-ECDSA.pod
new file mode 100644 (file)
index 0000000..04b80a1
--- /dev/null
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+EVP_SIGNATURE-ECDSA - The EVP_PKEY ECDSA signature implementation.
+
+=head1 DESCRIPTION
+
+Support for computing ECDSA signatures.
+See L<EVP_PKEY-EC(7)> for information related to EC keys.
+
+=head2 ECDSA Signature Parameters
+
+The following signature parameters can be set using EVP_PKEY_CTX_set_params().
+This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
+and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). 
+
+=over 4
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
+
+These parameters are described in L<provider-signature(7)>.
+
+=back
+
+The following signature parameters can be retrieved using
+EVP_PKEY_CTX_get_params().
+
+=over 4
+
+=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+The parameters are described in L<provider-signature(7)>.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_set_params(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<provider-signature(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
similarity index 68%
rename from doc/man7/Ed25519.pod
rename to doc/man7/EVP_SIGNATURE-ED25519.pod
index 912b607..e3d9cd4 100644 (file)
@@ -2,6 +2,8 @@
 
 =head1 NAME
 
+EVP_SIGNATURE-ED25519,
+EVP_SIGNATURE-ED448,
 Ed25519,
 Ed448
 - EVP_PKEY Ed25519 and Ed448 support
@@ -13,9 +15,10 @@ one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448
 (see RFC8032). It has associated private and public key formats compatible with
 RFC 8410.
 
-No additional parameters can be set during key generation, one-shot signing or
-verification. In particular, because PureEdDSA is used, a digest must B<NOT> be
-specified when signing or verifying.
+No additional parameters can be set during one-shot signing or verification.
+In particular, because PureEdDSA is used, a digest must B<NOT> be specified when
+signing or verifying.
+See L<EVP_PKEY-X25519(7)> for information related to B<X25519> and B<X448> keys.
 
 =head1 NOTES
 
@@ -31,14 +34,6 @@ Applications wishing to sign certificates (or other structures such as
 CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign()
 or X509_sign_ctx() in the usual way.
 
-A context for the B<Ed25519> algorithm can be obtained by calling:
-
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
-
-For the B<Ed448> algorithm a context can be obtained by calling:
-
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL);
-
 Ed25519 or Ed448 private keys can be set directly using
 L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
 using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
@@ -56,23 +51,29 @@ specified, then both Ed25519 and Ed448 are benchmarked.
 
 =head1 EXAMPLES
 
-This example generates an B<ED25519> private key and writes it to standard
-output in PEM format:
+To sign a message using a ED25519 or ED448 key:
+
+    void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
+    {
+        size_t sig_len;
+        unsigned char *sig = NULL;
+        EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
+
+        EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key);
+        /* Calculate the requires size for the signature by passing a NULL buffer */
+        EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
+        sig = OPENSSL_zalloc(sig_len);
 
- #include <openssl/evp.h>
- #include <openssl/pem.h>
- ...
- EVP_PKEY *pkey = NULL;
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);
- EVP_PKEY_keygen_init(pctx);
- EVP_PKEY_keygen(pctx, &pkey);
- EVP_PKEY_CTX_free(pctx);
- PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
+        EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len);
+        ...
+        OPENSSL_free(sig);
+        EVP_MD_CTX_free(md_ctx);
+    }
 
 =head1 SEE ALSO
 
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_keygen(3)>,
+L<EVP_PKEY-X25519(7)>
+L<provider-signature(7)>,
 L<EVP_DigestSignInit(3)>,
 L<EVP_DigestVerifyInit(3)>,
 
diff --git a/doc/man7/EVP_SIGNATURE-RSA.pod b/doc/man7/EVP_SIGNATURE-RSA.pod
new file mode 100644 (file)
index 0000000..0cc3336
--- /dev/null
@@ -0,0 +1,112 @@
+=pod
+
+=head1 NAME
+
+EVP_SIGNATURE-RSA
+- The EVP_PKEY RSA signature implementation
+
+=head1 DESCRIPTION
+
+Support for computing RSA signatures.
+See L<EVP_PKEY-RSA(7)> for information related to RSA keys.
+
+=head2 Signature Parameters
+
+The following signature parameters can be set using EVP_PKEY_CTX_set_params().
+This may be called after EVP_PKEY_sign_init() or EVP_PKEY_verify_init(),
+and before calling EVP_PKEY_sign() or EVP_PKEY_verify(). 
+
+=over 4
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+=item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
+
+These common parameters are described in L<provider-signature(7)>.
+
+=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
+
+The type of padding to be used. Its value can be one of the following:
+
+=over 4
+
+=item "none" (B<OSSL_PKEY_RSA_PAD_MODE_NONE>)
+
+=item "pkcs1" (B<OSSL_PKEY_RSA_PAD_MODE_PKCSV15>) 
+
+=item "sslv23" (B<OSSL_PKEY_RSA_PAD_MODE_SSLV23>)
+
+=item "x931" (B<OSSL_PKEY_RSA_PAD_MODE_X931>)
+
+=item "pss" (B<OSSL_PKEY_RSA_PAD_MODE_PSS>) 
+
+=back
+
+=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
+
+The digest algorithm name to use for the maskGenAlgorithm used by "pss" mode.
+
+=item "mgf1-properties" (B<OSSL_SIGNATURE_PARAM_MGF1_PROPERTIES>) <UTF8 string>
+
+Sets the name of the property query associated with the "mgf1-digest" algorithm.
+NULL is used if this optional value is not set.
+
+=item "pss-saltlen" (B<OSSL_SIGNATURE_PARAM_PSS_SALTLEN>) <UTF8 string>
+
+Set or get the "pss" mode minimum salt length. The value can either be a string
+value representing a number or one of the following:
+
+=over 4
+
+=item "digest" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST>)
+
+Use the same length as the digest size.
+
+=item "max" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_MAX>)
+
+Use the maximum salt length.
+
+=item "auto" (B<OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO>)
+
+Auto detect the salt length.
+
+=back
+
+=back
+
+The following signature parameters can be retrieved using
+EVP_PKEY_CTX_get_params().
+
+=over 4
+
+=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
+
+This common parameter is described in L<provider-signature(7)>.
+
+=item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
+
+=item "pad-mode" (B<OSSL_SIGNATURE_PARAM_PAD_MODE>) <UTF8 string>
+
+=item "mgf1-digest" (B<OSSL_SIGNATURE_PARAM_MGF1_DIGEST>) <UTF8 string>
+
+These parameters are as described above.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_CTX_set_params(3)>,
+L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify(3)>,
+L<provider-signature(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
index 92dab0e..1da465f 100644 (file)
@@ -18,9 +18,9 @@ defined:
 
 =over 4
 
-"provider=default"
+=item "provider=default"
 
-"fips=yes"
+=item "fips=yes"
 
 =back
 
@@ -102,6 +102,16 @@ The OpenSSL FIPS provider supports these operations and algorithms:
 
 =item DH, see L<EVP_KEYEXCH-DH(7)>
 
+=item ECDH, see L<EVP_KEYEXCH-ECDH(7)>
+
+=item X25519, see L<EVP_KEYEXCH-X25519(7)>
+
+This has the property "provider=fips,fips=no"
+
+=item X448, see L<EVP_KEYEXCH-X448(7)>
+
+This has the property "provider=fips,fips=no"
+
 =back
 
 =head2 Asymmetric Signature
index acfd4d0..91b02c5 100644 (file)
@@ -17,7 +17,7 @@ defined:
 
 =over 4
 
-"provider=default"
+=item "provider=default"
 
 =back
 
@@ -136,6 +136,8 @@ The OpenSSL default provider supports these operations and algorithms:
 
 =item KRB5KDF, see L<EVP_KDF-KRB5KDF(7)>
 
+=item X963KDF, see L<EVP_KDF-X963(7)>
+
 =back
 
 =head2 Key Exchange
index 27ed308..db2d57e 100644 (file)
@@ -15,12 +15,12 @@ We can consider this the retirement home of cryptographic algorithms.
 
 =head2 Properties
 
-The implementations in this provider specifically have these property
+The implementations in this provider specifically has this property
 defined:
 
 =over 4
 
-"provider=legacy"
+=item "provider=legacy"
 
 =back
 
index aefaa40..081be53 100644 (file)
@@ -234,22 +234,52 @@ useless without at least provider_query_operation(), and
 provider_gettable_params() is fairly useless if not accompanied by
 provider_get_params().
 
+=head2 Provider parameters
+
+provider_get_params() can return the following provider parameters to the core:
+
+=over 4
+
+=item "name" (B<OSSL_PROV_PARAM_NAME>) <UTF8_ptr>
+
+This points to a string that should give a unique name for the provider.
+
+=item "version" (B<OSSL_PROV_PARAM_VERSION>) <UTF8_ptr>
+
+This points to a string that is a version number associated with this provider.
+OpenSSL in-built providers use OPENSSL_VERSION_STR, but this may be different
+for any third party provider. This string is for informational purposes only.
+
+=item "buildinfo" (B<OSSL_PROV_PARAM_BUILDINFO>) <UTF8_ptr>
+
+This points to a string that is a build information associated with this provider.
+OpenSSL in-built providers use OPENSSL_FULL_VERSION_STR, but this may be
+different for any third party provider.
+
+=back 
+
+provider_gettable_params() should return the above parameters.
+
+
 =head2 Core parameters
 
-core_get_params() understands the following known parameters:
+core_get_params() can retrieve the following core parameters for each provider:
 
 =over 4
 
-=item "openssl-version"
+=item "openssl-version" (B<OSSL_PROV_PARAM_CORE_VERSION>) <UTF8_ptr>
+
+This points to the OpenSSL libraries' full version string, i.e. the string
+expanded from the macro B<OPENSSL_VERSION_STR>.
+
+=item "provider-name" (B<OSSL_PROV_PARAM_CORE_PROV_NAME>) <UTF8_ptr>
 
-This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
-OpenSSL libraries' full version string, i.e. the string expanded from
-the macro B<OPENSSL_VERSION_STR>.
+This points to the OpenSSL libraries' idea of what the calling provider is named.
 
-=item "provider-name"
+=item "module-filename" (B<OSSL_PROV_PARAM_CORE_MODULE_FILENAME>) <UTF8_ptr>
 
-This is a B<OSSL_PARAM_UTF8_PTR> type of parameter, pointing at the
-OpenSSL libraries' idea of what the calling provider is called.
+This points to a string containing the full filename of the providers
+module file.
 
 =back
 
index 1d34ded..59cc203 100644 (file)
@@ -131,12 +131,12 @@ written to I<*secretlen>.
 
 OP_keyexch_set_ctx_params() sets key exchange parameters associated with the
 given provider side key exchange context I<ctx> to I<params>,
-see L</Key Exchange Parameters>.
+see L</Common Key Exchange parameters>.
 Any parameter settings are additional to any that were previously set.
 
 OP_keyexch_get_ctx_params() gets key exchange parameters associated with the
 given provider side key exchange context I<ctx> into I<params>,
-see L</Key Exchange Parameters>.
+see L</Common Key Exchange parameters>.
 
 OP_keyexch_settable_ctx_params() yields a constant B<OSSL_PARAM> array that
 describes the settable parameters, i.e. parameters that can be used with
@@ -152,15 +152,13 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 
 Notice that not all settable parameters are also gettable, and vice versa.
 
-=head2 Key Exchange Parameters
+=head2 Common Key Exchange parameters
 
 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 the OP_keyexch_set_ctx_params() and OP_keyexch_get_ctx_params() functions.
 
-Parameters currently recognised by built-in key exchange algorithms are as
-follows.
-Not all parameters are relevant to, or are understood by all key exchange
-algorithms:
+Common parameters currently recognised by built-in key exchange algorithms are
+as follows.
 
 =over 4
 
@@ -168,63 +166,13 @@ algorithms:
 
 Sets the padding mode for the associated key exchange ctx.
 Setting a value of 1 will turn padding on.
-Setting a vlue of 0 will turn padding off.
+Setting a value of 0 will turn padding off.
 If padding is off then the derived shared secret may be smaller than the largest
 possible secret size.
 If padding is on then the derived shared secret will have its first bytes filled
 with 0s where necessary to make the shared secret the same size as the largest
 possible secret size.
 
-=item "ecdh-cofactor-mode" (B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE>) <integer>
-
-Sets/gets the ECDH mode of operation for the associated key exchange ctx.
-
-In the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter
-can be used to select between the plain Diffie-Hellman (DH) or Cofactor
-Diffie-Hellman (CDH) variants of the key exchange algorithm.
-
-When setting, the value should be 1, 0 or -1, respectively forcing cofactor mode
-on, off, or resetting it to the default for the private key associated with the
-given key exchange ctx.
-
-When getting, the value should be either 1 or 0, respectively signaling if the
-cofactor mode is on or off.
-
-See also L<provider-keymgmt(7)> for the related
-B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH> parameter that can be set on a
-per-key basis.
-
-=item "kdf-type" (B<OSSL_EXCHANGE_PARAM_KDF_TYPE>) <utf8_string>
-
-Sets/gets the Key Derivation Function type to apply within the associated key
-exchange ctx.
-
-=item "kdf-digest" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST>) <utf8_string>
-
-Sets/gets the Digest algorithm to be used as part of the Key Derivation Function
-associated with the given key exchange ctx.
-
-=item "kdf-digest-props" (B<OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS>) <utf8_string>
-
-Sets properties to be used upon look up of the implementation for the selected
-Digest algorithm for the Key Derivation Function associated with the given key
-exchange ctx.
-
-=item "kdf-outlen" (B<OSSL_EXCHANGE_PARAM_KDF_OUTLEN>) <size_t>
-
-Sets/gets the desired size for the output of the chosen Key Derivation Function
-associated with the given key exchange ctx.
-
-=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
-
-Sets/gets User Key Material to be used as part of the selected Key Derivation
-Function associated with the given key exchange ctx.
-
-=item "kdf-ukm-len" (B<OSSL_EXCHANGE_PARAM_KDF_UKM_LEN>) <size_t>
-
-Sets/gets the size of the User Key Material to be used as part of the selected
-Key Derivation Function associated with the given key exchange ctx.
-
 =back
 
 =head1 RETURN VALUES
index 45d97e6..538c342 100644 (file)
@@ -303,7 +303,7 @@ initialised verification context is passed in the I<ctx> parameter. The data to
 verified is in I<tbs> which should be I<tbslen> bytes long. The signature to be
 verified is in I<sig> which is I<siglen> bytes long.
 
-=head2 Signature Parameters
+=head2 Signature parameters
 
 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions.
@@ -314,17 +314,20 @@ OP_signature_set_ctx_params() sets the signature parameters associated with the
 given provider side signature context I<ctx> to I<params>.
 Any parameter settings are additional to any that were previously set.
 
-Parameters currently recognised by built-in signature algorithms are as
+Common parameters currently recognised by built-in signature algorithms are as
 follows.
-Not all parameters are relevant to, or are understood by all signature
-algorithms:
 
 =over 4
 
 =item "digest" (B<OSSL_SIGNATURE_PARAM_DIGEST>) <UTF8 string>
 
 Get or sets the name of the digest algorithm used for the input to the signature
-functions.
+functions. It is required in order to calculate the "algorithm-id".
+
+= item "properties" (B<OSSL_SIGNATURE_PARAM_PROPERTIES>) <UTF8 string>
+
+Sets the name of the property query associated with the "digest" algorithm.
+NULL is used if this optional value is not set.
 
 =item "digest-size" (B<OSSL_SIGNATURE_PARAM_DIGEST_SIZE>) <unsigned integer>
 
@@ -358,7 +361,7 @@ i.e. parameters that can be used with OP_signature_get_ctx_params() and
 OP_signature_set_ctx_params() respectively.
 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
 
-=head2 MD Parameters
+=head2 MD parameters
 
 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 the OP_signature_get_md_ctx_params() and OP_signature_set_md_ctx_params()
index b4dd2f1..bccebb0 100644 (file)
@@ -62,7 +62,7 @@ const unsigned char *ecdsa_algorithmidentifier_encoding(int md_nid, size_t *len)
 int ec_key_fromdata(EC_KEY *ecx, const OSSL_PARAM params[], int include_private);
 int ec_key_domparams_fromdata(EC_KEY *ecx, const OSSL_PARAM params[]);
 int ec_key_otherparams_fromdata(EC_KEY *ec, const OSSL_PARAM params[]);
-int ec_set_param_ecdh_cofactor_mode(EC_KEY *ec, const OSSL_PARAM *p);
+int ec_set_ecdh_cofactor_mode(EC_KEY *ec, int mode);
 
 # endif /* OPENSSL_NO_EC */
 #endif
index 1bd1224..8bafc1b 100644 (file)
 extern "C" {
 # endif
 
+/* Well known parameter names that core passes to providers */
+#define OSSL_PROV_PARAM_CORE_VERSION         "openssl-version" /* utf8_ptr */
+#define OSSL_PROV_PARAM_CORE_PROV_NAME       "provider-name"   /* utf8_ptr */
+#define OSSL_PROV_PARAM_CORE_MODULE_FILENAME "module-filename" /* utf8_ptr */
+
 /* Well known parameter names that Providers can define */
 #define OSSL_PROV_PARAM_NAME            "name"                /* utf8_string */
 #define OSSL_PROV_PARAM_VERSION         "version"             /* utf8_string */
 #define OSSL_PROV_PARAM_BUILDINFO       "buildinfo"           /* utf8_string */
-#define OSSL_PROV_PARAM_MODULE_FILENAME "module-filename"     /* octet_string */
 
 /* Self test callback parameters */
 #define OSSL_PROV_PARAM_SELF_TEST_PHASE  "st-phase" /* utf8_string */
@@ -29,6 +33,8 @@ extern "C" {
  * Algorithm parameters
  * If "engine" or "properties" are specified, they should always be paired
  * with the algorithm type.
+ * Note these are common names that are shared by many types (such as kdf, mac,
+ * and pkey) e.g: see OSSL_MAC_PARAM_DIGEST below.
  */
 #define OSSL_ALG_PARAM_DIGEST       "digest"    /* utf8_string */
 #define OSSL_ALG_PARAM_CIPHER       "cipher"    /* utf8_string */
@@ -123,11 +129,16 @@ extern "C" {
 #define OSSL_MAC_PARAM_PROPERTIES   OSSL_ALG_PARAM_PROPERTIES /* utf8 string */
 #define OSSL_MAC_PARAM_SIZE         "size"       /* size_t */
 
-/* Known MAC names (not a complete list) */
+/* Known MAC names */
+#define OSSL_MAC_NAME_BLAKE2BMAC    "BLAKE2BMAC"
+#define OSSL_MAC_NAME_BLAKE2SMAC    "BLAKE2SMAC"
 #define OSSL_MAC_NAME_CMAC          "CMAC"
+#define OSSL_MAC_NAME_GMAC          "GMAC"
 #define OSSL_MAC_NAME_HMAC          "HMAC"
 #define OSSL_MAC_NAME_KMAC128       "KMAC128"
 #define OSSL_MAC_NAME_KMAC256       "KMAC256"
+#define OSSL_MAC_NAME_POLY1305      "POLY1305"
+#define OSSL_MAC_NAME_SIPHASH       "SIPHASH"
 
 /* KDF / PRF parameters */
 #define OSSL_KDF_PARAM_SECRET       "secret"    /* octet string */
@@ -179,8 +190,6 @@ extern "C" {
 #define OSSL_PKEY_PARAM_DEFAULT_DIGEST      "default-digest" /* utf8 string */
 #define OSSL_PKEY_PARAM_MANDATORY_DIGEST    "mandatory-digest" /* utf8 string */
 #define OSSL_PKEY_PARAM_PAD_MODE            "pad-mode"
-#define OSSL_PKEY_PARAM_DIGEST              OSSL_ALG_PARAM_DIGEST
-#define OSSL_PKEY_PARAM_PROPERTIES          OSSL_ALG_PARAM_PROPERTIES
 #define OSSL_PKEY_PARAM_DIGEST_SIZE         "digest-size"
 #define OSSL_PKEY_PARAM_MASKGENFUNC         "mgf"
 #define OSSL_PKEY_PARAM_MGF1_DIGEST         "mgf1-digest"
@@ -194,13 +203,6 @@ extern "C" {
 #define OSSL_PKEY_PARAM_FFC_P        "p"
 #define OSSL_PKEY_PARAM_FFC_G        "g"
 #define OSSL_PKEY_PARAM_FFC_Q        "q"
-#define OSSL_PKEY_PARAM_FFC_GINDEX   "gindex"
-#define OSSL_PKEY_PARAM_FFC_PCOUNTER "pcounter"
-#define OSSL_PKEY_PARAM_FFC_SEED     "seed"
-#define OSSL_PKEY_PARAM_FFC_COFACTOR "j"
-#define OSSL_PKEY_PARAM_FFC_H        "hindex"
-#define OSSL_PKEY_PARAM_FFC_GROUP    "group"
-
 #define OSSL_PKEY_PARAM_FFC_GINDEX   "gindex"
 #define OSSL_PKEY_PARAM_FFC_PCOUNTER "pcounter"
 #define OSSL_PKEY_PARAM_FFC_SEED     "seed"
@@ -208,8 +210,8 @@ extern "C" {
 #define OSSL_PKEY_PARAM_FFC_H        "hindex"
 
 /* Diffie-Hellman params */
-#define OSSL_PKEY_PARAM_FFC_GROUP    "group"
-#define OSSL_PKEY_PARAM_FFC_GENERATOR "safeprime-generator"
+#define OSSL_PKEY_PARAM_DH_GROUP     "group"
+#define OSSL_PKEY_PARAM_DH_GENERATOR "safeprime-generator"
 #define OSSL_PKEY_PARAM_DH_PRIV_LEN   "priv_len"
 
 /* Elliptic Curve Domain Parameters */
@@ -270,6 +272,18 @@ extern "C" {
 #define OSSL_PKEY_PARAM_RSA_COEFFICIENT8 OSSL_PKEY_PARAM_RSA_COEFFICIENT"8"
 #define OSSL_PKEY_PARAM_RSA_COEFFICIENT9 OSSL_PKEY_PARAM_RSA_COEFFICIENT"9"
 
+/* RSA padding modes */
+#define OSSL_PKEY_RSA_PAD_MODE_NONE    "none"
+#define OSSL_PKEY_RSA_PAD_MODE_PKCSV15 "pkcs1"
+#define OSSL_PKEY_RSA_PAD_MODE_SSLV23  "sslv23"
+#define OSSL_PKEY_RSA_PAD_MODE_OAEP    "oaep"
+#define OSSL_PKEY_RSA_PAD_MODE_X931    "x931"
+#define OSSL_PKEY_RSA_PAD_MODE_PSS     "pss"
+
+/* RSA pss padding salt length */
+#define OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST "digest"
+#define OSSL_PKEY_RSA_PSS_SALT_LEN_MAX    "max"
+#define OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO   "auto"
 
 /* Key generation parameters */
 #define OSSL_PKEY_PARAM_RSA_BITS            OSSL_PKEY_PARAM_BITS
@@ -287,7 +301,6 @@ extern "C" {
 #define OSSL_PKEY_PARAM_FFC_DIGEST_PROPS OSSL_PKEY_PARAM_PROPERTIES
 
 /* Key Exchange parameters */
-
 #define OSSL_EXCHANGE_PARAM_PAD                   "pad" /* uint */
 #define OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE "ecdh-cofactor-mode" /* int */
 #define OSSL_EXCHANGE_PARAM_KDF_TYPE              "kdf-type" /* utf8_string */
index 1c4f3fd..bbf95b7 100644 (file)
@@ -113,11 +113,12 @@ static const OSSL_PARAM fips_param_types[] = {
 /*
  * Parameters to retrieve from the core provider - required for self testing.
  * NOTE: inside core_get_params() these will be loaded from config items
- * stored inside prov->parameters (except for OSSL_PROV_PARAM_MODULE_FILENAME).
+ * stored inside prov->parameters (except for
+ * OSSL_PROV_PARAM_CORE_MODULE_FILENAME).
  */
 static OSSL_PARAM core_params[] =
 {
-    OSSL_PARAM_utf8_ptr(OSSL_PROV_PARAM_MODULE_FILENAME,
+    OSSL_PARAM_utf8_ptr(OSSL_PROV_PARAM_CORE_MODULE_FILENAME,
                         selftest_params.module_filename,
                         sizeof(selftest_params.module_filename)),
     OSSL_PARAM_utf8_ptr(OSSL_PROV_FIPS_PARAM_MODULE_MAC,
index f7e7b54..405842e 100644 (file)
@@ -44,13 +44,12 @@ static OSSL_OP_asym_cipher_set_ctx_params_fn rsa_set_ctx_params;
 static OSSL_OP_asym_cipher_settable_ctx_params_fn rsa_settable_ctx_params;
 
 static OSSL_ITEM padding_item[] = {
-    { RSA_PKCS1_PADDING,        "pkcs1"  },
-    { RSA_SSLV23_PADDING,       "sslv23" },
-    { RSA_NO_PADDING,           "none"   },
-    { RSA_PKCS1_OAEP_PADDING,   "oaep"   }, /* Correct spelling first */
+    { RSA_PKCS1_PADDING,        OSSL_PKEY_RSA_PAD_MODE_PKCSV15 },
+    { RSA_SSLV23_PADDING,       OSSL_PKEY_RSA_PAD_MODE_SSLV23 },
+    { RSA_NO_PADDING,           OSSL_PKEY_RSA_PAD_MODE_NONE },
+    { RSA_PKCS1_OAEP_PADDING,   OSSL_PKEY_RSA_PAD_MODE_OAEP }, /* Correct spelling first */
     { RSA_PKCS1_OAEP_PADDING,   "oeap"   },
-    { RSA_X931_PADDING,         "x931"   },
-    { RSA_PKCS1_PSS_PADDING,    "pss"    },
+    { RSA_X931_PADDING,         OSSL_PKEY_RSA_PAD_MODE_X931 },
     { 0,                        NULL     }
 };
 
index a551a72..1e344bd 100644 (file)
@@ -235,8 +235,8 @@ err:
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_GINDEX, NULL),                          \
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_PCOUNTER, NULL),                        \
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_H, NULL),                               \
-    OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP, NULL, 0),                \
-    OSSL_PARAM_octet_string(OSSL_PKEY_PARAM_FFC_SEED, NULL, 0)
+    OSSL_PARAM_octet_string(OSSL_PKEY_PARAM_FFC_SEED, NULL, 0),                \
+    OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_DH_GROUP, NULL, 0)
 # define DH_IMEXPORTABLE_PUBLIC_KEY                                            \
     OSSL_PARAM_BN(OSSL_PKEY_PARAM_PUB_KEY, NULL, 0)
 # define DH_IMEXPORTABLE_PRIVATE_KEY                                           \
@@ -427,7 +427,7 @@ static int dh_gen_set_params(void *genctx, const OSSL_PARAM params[])
             return 0;
         }
     }
-    p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_FFC_GROUP);
+    p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_DH_GROUP);
     if (p != NULL) {
         if (p->data_type != OSSL_PARAM_UTF8_STRING
            || ((gctx->group_nid = ffc_named_group_to_uid(p->data)) == NID_undef)) {
@@ -436,7 +436,7 @@ static int dh_gen_set_params(void *genctx, const OSSL_PARAM params[])
         }
         gctx->gen_type = DH_PARAMGEN_TYPE_GROUP;
     }
-    p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_FFC_GENERATOR);
+    p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_DH_GENERATOR);
     if (p != NULL && !OSSL_PARAM_get_int(p, &gctx->generator))
         return 0;
     p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_FFC_GINDEX);
@@ -486,7 +486,9 @@ static int dh_gen_set_params(void *genctx, const OSSL_PARAM params[])
 static const OSSL_PARAM *dh_gen_settable_params(void *provctx)
 {
     static OSSL_PARAM settable[] = {
-        OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP, NULL, 0),
+        OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_DH_GROUP, NULL, 0),
+        OSSL_PARAM_int(OSSL_PKEY_PARAM_DH_PRIV_LEN, NULL),
+        OSSL_PARAM_int(OSSL_PKEY_PARAM_DH_GENERATOR, NULL),
         OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_FFC_TYPE, NULL, 0),
         OSSL_PARAM_size_t(OSSL_PKEY_PARAM_FFC_PBITS, NULL),
         OSSL_PARAM_size_t(OSSL_PKEY_PARAM_FFC_QBITS, NULL),
@@ -494,10 +496,8 @@ static const OSSL_PARAM *dh_gen_settable_params(void *provctx)
         OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_FFC_DIGEST_PROPS, NULL, 0),
         OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_GINDEX, NULL),
         OSSL_PARAM_octet_string(OSSL_PKEY_PARAM_FFC_SEED, NULL, 0),
-        OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_GENERATOR, NULL),
         OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_PCOUNTER, NULL),
         OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_H, NULL),
-        OSSL_PARAM_int(OSSL_PKEY_PARAM_DH_PRIV_LEN, NULL),
         OSSL_PARAM_END
     };
     return settable;
index de54b9a..af8361f 100644 (file)
@@ -213,7 +213,6 @@ err:
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_GINDEX, NULL),                          \
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_PCOUNTER, NULL),                        \
     OSSL_PARAM_int(OSSL_PKEY_PARAM_FFC_H, NULL),                               \
-    OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_FFC_GROUP, NULL, 0),                \
     OSSL_PARAM_octet_string(OSSL_PKEY_PARAM_FFC_SEED, NULL, 0)
 # define DSA_IMEXPORTABLE_PUBLIC_KEY                    \
     OSSL_PARAM_BN(OSSL_PKEY_PARAM_PUB_KEY, NULL, 0)
index a48b279..8e7b9f3 100644 (file)
@@ -543,13 +543,8 @@ static
 int ec_set_params(void *key, const OSSL_PARAM params[])
 {
     EC_KEY *eck = key;
-    const OSSL_PARAM *p;
-
-    p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_USE_COFACTOR_ECDH);
-    if (p != NULL && !ec_set_param_ecdh_cofactor_mode(eck, p))
-        return 0;
 
-    return 1;
+    return ec_key_otherparams_fromdata(eck, params);
 }
 
 static
@@ -583,9 +578,9 @@ int ec_validate(void *keydata, int selection)
 
 struct ec_gen_ctx {
     OPENSSL_CTX *libctx;
-
     EC_GROUP *gen_group;
     int selection;
+    int ecdh_mode;
 };
 
 static void *ec_gen_init(void *provctx, int selection)
@@ -600,6 +595,7 @@ static void *ec_gen_init(void *provctx, int selection)
         gctx->libctx = libctx;
         gctx->gen_group = NULL;
         gctx->selection = selection;
+        gctx->ecdh_mode = 0;
     }
     return gctx;
 }
@@ -636,6 +632,11 @@ static int ec_gen_set_params(void *genctx, const OSSL_PARAM params[])
     struct ec_gen_ctx *gctx = genctx;
     const OSSL_PARAM *p;
 
+    if ((p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_USE_COFACTOR_ECDH))
+        != NULL) {
+        if (!OSSL_PARAM_get_int(p, &gctx->ecdh_mode))
+            return 0;
+    }
     if ((p = OSSL_PARAM_locate_const(params, OSSL_PKEY_PARAM_EC_NAME))
         != NULL) {
         const char *curve_name = NULL;
@@ -670,7 +671,8 @@ static int ec_gen_set_params(void *genctx, const OSSL_PARAM params[])
 static const OSSL_PARAM *ec_gen_settable_params(void *provctx)
 {
     static OSSL_PARAM settable[] = {
-        { OSSL_PKEY_PARAM_EC_NAME, OSSL_PARAM_UTF8_STRING, NULL, 0, 0 },
+        OSSL_PARAM_utf8_string(OSSL_PKEY_PARAM_EC_NAME, NULL, 0),
+        OSSL_PARAM_int(OSSL_PKEY_PARAM_USE_COFACTOR_ECDH, NULL),
         OSSL_PARAM_END
     };
 
@@ -705,6 +707,9 @@ static void *ec_gen(void *genctx, OSSL_CALLBACK *osslcb, void *cbarg)
     if ((gctx->selection & OSSL_KEYMGMT_SELECT_KEYPAIR) != 0)
         ret = ret && EC_KEY_generate_key(ec);
 
+    if (gctx->ecdh_mode != -1)
+        ret = ret && ec_set_ecdh_cofactor_mode(ec, gctx->ecdh_mode);
+
     if (ret)
         return ec;
 
index 9227cb1..de6aac6 100644 (file)
@@ -446,6 +446,7 @@ static int dsa_set_ctx_params(void *vpdsactx, const OSSL_PARAM params[])
 
 static const OSSL_PARAM known_settable_ctx_params[] = {
     OSSL_PARAM_utf8_string(OSSL_SIGNATURE_PARAM_DIGEST, NULL, 0),
+    OSSL_PARAM_utf8_string(OSSL_SIGNATURE_PARAM_PROPERTIES, NULL, 0),
     OSSL_PARAM_END
 };
 
index 4ecc526..35a6950 100644 (file)
@@ -56,7 +56,7 @@ static int eddsa_digest_signverify_init(void *vpeddsactx, const char *mdname,
     PROV_EDDSA_CTX *peddsactx = (PROV_EDDSA_CTX *)vpeddsactx;
     ECX_KEY *edkey = (ECX_KEY *)vedkey;
 
-    if (mdname != NULL) {
+    if (mdname != NULL && mdname[0] != '\0') {
         PROVerr(0, PROV_R_INVALID_DIGEST);
         return 0;
     }
index 0e3885e..81611bb 100644 (file)
@@ -55,13 +55,11 @@ static OSSL_OP_signature_set_ctx_md_params_fn rsa_set_ctx_md_params;
 static OSSL_OP_signature_settable_ctx_md_params_fn rsa_settable_ctx_md_params;
 
 static OSSL_ITEM padding_item[] = {
-    { RSA_PKCS1_PADDING,        "pkcs1"  },
-    { RSA_SSLV23_PADDING,       "sslv23" },
-    { RSA_NO_PADDING,           "none"   },
-    { RSA_PKCS1_OAEP_PADDING,   "oaep"   }, /* Correct spelling first */
-    { RSA_PKCS1_OAEP_PADDING,   "oeap"   },
-    { RSA_X931_PADDING,         "x931"   },
-    { RSA_PKCS1_PSS_PADDING,    "pss"    },
+    { RSA_PKCS1_PADDING,        OSSL_PKEY_RSA_PAD_MODE_PKCSV15 },
+    { RSA_SSLV23_PADDING,       OSSL_PKEY_RSA_PAD_MODE_SSLV23 },
+    { RSA_NO_PADDING,           OSSL_PKEY_RSA_PAD_MODE_NONE },
+    { RSA_X931_PADDING,         OSSL_PKEY_RSA_PAD_MODE_X931 },
+    { RSA_PKCS1_PSS_PADDING,    OSSL_PKEY_RSA_PAD_MODE_PSS },
     { 0,                        NULL     }
 };
 
@@ -939,25 +937,32 @@ static int rsa_get_ctx_params(void *vprsactx, OSSL_PARAM *params)
             if (!OSSL_PARAM_set_int(p, prsactx->saltlen))
                 return 0;
         } else if (p->data_type == OSSL_PARAM_UTF8_STRING) {
+            const char *value = NULL;
+
             switch (prsactx->saltlen) {
             case RSA_PSS_SALTLEN_DIGEST:
-                if (!OSSL_PARAM_set_utf8_string(p, "digest"))
-                    return 0;
+                value = OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST;
                 break;
             case RSA_PSS_SALTLEN_MAX:
-                if (!OSSL_PARAM_set_utf8_string(p, "max"))
-                    return 0;
+                value = OSSL_PKEY_RSA_PSS_SALT_LEN_MAX;
                 break;
             case RSA_PSS_SALTLEN_AUTO:
-                if (!OSSL_PARAM_set_utf8_string(p, "auto"))
-                    return 0;
+                value = OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO;
                 break;
             default:
-                if (BIO_snprintf(p->data, p->data_size, "%d", prsactx->saltlen)
-                    <= 0)
-                    return 0;
-                break;
+                {
+                    int len = BIO_snprintf(p->data, p->data_size, "%d",
+                                           prsactx->saltlen);
+
+                    if (len <= 0)
+                        return 0;
+                    p->return_size = len;
+                    break;
+                }
             }
+            if (value != NULL
+                && !OSSL_PARAM_set_utf8_string(p, value))
+                return 0;
         }
     }
 
@@ -1117,11 +1122,11 @@ static int rsa_set_ctx_params(void *vprsactx, const OSSL_PARAM params[])
                 return 0;
             break;
         case OSSL_PARAM_UTF8_STRING:
-            if (strcmp(p->data, "digest") == 0)
+            if (strcmp(p->data, OSSL_PKEY_RSA_PSS_SALT_LEN_DIGEST) == 0)
                 saltlen = RSA_PSS_SALTLEN_DIGEST;
-            else if (strcmp(p->data, "max") == 0)
+            else if (strcmp(p->data, OSSL_PKEY_RSA_PSS_SALT_LEN_MAX) == 0)
                 saltlen = RSA_PSS_SALTLEN_MAX;
-            else if (strcmp(p->data, "auto") == 0)
+            else if (strcmp(p->data, OSSL_PKEY_RSA_PSS_SALT_LEN_AUTO) == 0)
                 saltlen = RSA_PSS_SALTLEN_AUTO;
             else
                 saltlen = atoi(p->data);
index c9857d6..8444ea1 100644 (file)
@@ -282,7 +282,7 @@ static int dsa_keygen_test(void)
                                              &pcount_out))
         || !TEST_int_eq(pcount_out, expected_c)
         || !TEST_false(EVP_PKEY_get_utf8_string_param(key,
-                                                      OSSL_PKEY_PARAM_FFC_GROUP,
+                                                      OSSL_PKEY_PARAM_DH_GROUP,
                                                       group_out,
                                                       sizeof(group_out), &len)))
         goto end;
index c5ef724..4c68f6b 100644 (file)
@@ -447,7 +447,7 @@ static int test_fromdata_dh_named_group(void)
         || !TEST_ptr(pub = BN_bin2bn(pub_data, sizeof(pub_data), NULL))
         || !TEST_ptr(priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL))
         || !TEST_true(OSSL_PARAM_BLD_push_utf8_string(bld,
-                                                      OSSL_PKEY_PARAM_FFC_GROUP,
+                                                      OSSL_PKEY_PARAM_DH_GROUP,
                                                       group_name, 0))
         || !TEST_true(OSSL_PARAM_BLD_push_BN(bld, OSSL_PKEY_PARAM_PUB_KEY, pub))
         || !TEST_true(OSSL_PARAM_BLD_push_BN(bld, OSSL_PKEY_PARAM_PRIV_KEY, priv))
@@ -464,7 +464,7 @@ static int test_fromdata_dh_named_group(void)
         || !TEST_int_eq(EVP_PKEY_size(pk), 256))
         goto err;
 
-    if (!TEST_true(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_FFC_GROUP,
+    if (!TEST_true(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_DH_GROUP,
                                                   name_out, sizeof(name_out),
                                                   &len))
         || !TEST_str_eq(name_out, group_name)
@@ -588,7 +588,7 @@ static int test_fromdata_dh_fips186_4(void)
         || !TEST_ptr(pub = BN_bin2bn(pub_data, sizeof(pub_data), NULL))
         || !TEST_ptr(priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL))
         || !TEST_true(OSSL_PARAM_BLD_push_utf8_string(bld,
-                                                      OSSL_PKEY_PARAM_FFC_GROUP,
+                                                      OSSL_PKEY_PARAM_DH_GROUP,
                                                       group_name, 0))
         || !TEST_true(OSSL_PARAM_BLD_push_BN(bld, OSSL_PKEY_PARAM_PUB_KEY, pub))
         || !TEST_true(OSSL_PARAM_BLD_push_BN(bld, OSSL_PKEY_PARAM_PRIV_KEY, priv))
@@ -605,7 +605,7 @@ static int test_fromdata_dh_fips186_4(void)
         || !TEST_int_eq(EVP_PKEY_size(pk), 256))
         goto err;
 
-    if (!TEST_true(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_FFC_GROUP,
+    if (!TEST_true(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_DH_GROUP,
                                                   name_out, sizeof(name_out),
                                                   &len))
         || !TEST_str_eq(name_out, group_name)
@@ -1143,7 +1143,7 @@ static int test_fromdata_dsa_fips186_4(void)
         || !TEST_int_eq(EVP_PKEY_size(pk), 2 + 2 * (3 + sizeof(q_data))))
         goto err;
 
-    if (!TEST_false(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_FFC_GROUP,
+    if (!TEST_false(EVP_PKEY_get_utf8_string_param(pk, OSSL_PKEY_PARAM_DH_GROUP,
                                                    name_out, sizeof(name_out),
                                                    &len))
         || !TEST_true(EVP_PKEY_get_bn_param(pk, OSSL_PKEY_PARAM_PUB_KEY,