From b8086652650c0782bc8d63b620663e04a3c6a3a7 Mon Sep 17 00:00:00 2001 From: Shane Lontis Date: Tue, 26 May 2020 13:53:07 +1000 Subject: Update core_names.h fields and document most fields. 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 (Merged from https://github.com/openssl/openssl/pull/11610) --- crypto/dh/dh_lib.c | 6 +- crypto/ec/ec_backend.c | 15 +- crypto/evp/pmeth_lib.c | 6 +- crypto/ffc/ffc_backend.c | 2 +- crypto/ffc/ffc_params.c | 2 +- crypto/provider_core.c | 16 +- doc/man3/EVP_KDF.pod | 12 +- doc/man3/EVP_MAC.pod | 3 + doc/man3/EVP_PKEY_CTX_ctrl.pod | 58 +----- doc/man3/EVP_PKEY_CTX_set_params.pod | 95 +++++++++ doc/man7/EVP_KEYEXCH-DH.pod | 98 +++++++++ doc/man7/EVP_KEYEXCH-ECDH.pod | 133 ++++++++++++ doc/man7/EVP_KEYEXCH-X25519.pod | 50 +++++ doc/man7/EVP_PKEY-DH.pod | 229 +++++++++++++++++++++ doc/man7/EVP_PKEY-DSA.pod | 259 +++++------------------- doc/man7/EVP_PKEY-EC.pod | 69 ++++++- doc/man7/EVP_PKEY-FFC.pod | 199 ++++++++++++++++++ doc/man7/EVP_PKEY-RSA.pod | 13 +- doc/man7/EVP_PKEY-X25519.pod | 4 + doc/man7/EVP_SIGNATURE-DSA.pod | 58 ++++++ doc/man7/EVP_SIGNATURE-ECDSA.pod | 57 ++++++ doc/man7/EVP_SIGNATURE-ED25519.pod | 89 ++++++++ doc/man7/EVP_SIGNATURE-RSA.pod | 112 ++++++++++ doc/man7/Ed25519.pod | 88 -------- doc/man7/OSSL_PROVIDER-FIPS.pod | 14 +- doc/man7/OSSL_PROVIDER-default.pod | 4 +- doc/man7/OSSL_PROVIDER-legacy.pod | 4 +- doc/man7/provider-base.pod | 46 ++++- doc/man7/provider-keyexch.pod | 64 +----- doc/man7/provider-signature.pod | 15 +- include/crypto/ec.h | 2 +- include/openssl/core_names.h | 41 ++-- providers/fips/fipsprov.c | 5 +- providers/implementations/asymciphers/rsa_enc.c | 11 +- providers/implementations/keymgmt/dh_kmgmt.c | 14 +- providers/implementations/keymgmt/dsa_kmgmt.c | 1 - providers/implementations/keymgmt/ec_kmgmt.c | 21 +- providers/implementations/signature/dsa.c | 1 + providers/implementations/signature/eddsa.c | 2 +- providers/implementations/signature/rsa.c | 45 ++-- test/dsatest.c | 2 +- test/evp_pkey_provided_test.c | 10 +- 42 files changed, 1439 insertions(+), 536 deletions(-) create mode 100644 doc/man3/EVP_PKEY_CTX_set_params.pod create mode 100644 doc/man7/EVP_KEYEXCH-DH.pod create mode 100644 doc/man7/EVP_KEYEXCH-ECDH.pod create mode 100644 doc/man7/EVP_KEYEXCH-X25519.pod create mode 100644 doc/man7/EVP_PKEY-DH.pod create mode 100644 doc/man7/EVP_PKEY-FFC.pod create mode 100644 doc/man7/EVP_SIGNATURE-DSA.pod create mode 100644 doc/man7/EVP_SIGNATURE-ECDSA.pod create mode 100644 doc/man7/EVP_SIGNATURE-ED25519.pod create mode 100644 doc/man7/EVP_SIGNATURE-RSA.pod delete mode 100644 doc/man7/Ed25519.pod diff --git a/crypto/dh/dh_lib.c b/crypto/dh/dh_lib.c index c3585f264f..3a523c3591 100644 --- a/crypto/dh/dh_lib.c +++ b/crypto/dh/dh_lib.c @@ -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); diff --git a/crypto/ec/ec_backend.c b/crypto/ec/ec_backend.c index 98dd0ecf5d..fb6497b084 100644 --- a/crypto/ec/ec_backend.c +++ b/crypto/ec/ec_backend.c @@ -19,15 +19,10 @@ * 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; } diff --git a/crypto/evp/pmeth_lib.c b/crypto/evp/pmeth_lib.c index e4327b3a94..355565de63 100644 --- a/crypto/evp/pmeth_lib.c +++ b/crypto/evp/pmeth_lib.c @@ -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; diff --git a/crypto/ffc/ffc_backend.c b/crypto/ffc/ffc_backend.c index 1cfa427df6..c34e79bf4f 100644 --- a/crypto/ffc/ffc_backend.c +++ b/crypto/ffc/ffc_backend.c @@ -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; diff --git a/crypto/ffc/ffc_params.c b/crypto/ffc/ffc_params.c index efd7dc8920..a95a2fa12b 100644 --- a/crypto/ffc/ffc_params.c +++ b/crypto/ffc/ffc_params.c @@ -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 diff --git a/crypto/provider_core.c b/crypto/provider_core.c index 0c21660080..f8aa5721b4 100644 --- a/crypto/provider_core.c +++ b/crypto/provider_core.c @@ -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 diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod index 2d7fe49c16..bceee3f500 100644 --- a/doc/man3/EVP_KDF.pod +++ b/doc/man3/EVP_KDF.pod @@ -68,6 +68,9 @@ EVP_KDF_fetch() fetches an implementation of a KDF I, given a library context I and a set of I. See L for further information. +See L for the lists of +algorithms supported by the default provider. + The returned value must eventually be freed with L. @@ -248,14 +251,7 @@ supported by the KDF algorithm. =head1 SEE ALSO -L -L -L -L -L -L -L -L +L =head1 HISTORY diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 1b961d4978..c98c8d873a 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -82,6 +82,9 @@ EVP_MAC_fetch() fetches an implementation of a MAC I, given a library context I and a set of I. See L for further information. +See L for the list +of algorithms supported by the default provider. + The returned value must eventually be freed with L. diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod index 039073cacf..db91f01038 100644 --- a/doc/man3/EVP_PKEY_CTX_ctrl.pod +++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod @@ -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 - 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 for more information on providers. -See L 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) - -Sets the DH padding mode. -If B is 1 then the shared secret is padded with zeros -up to the size of the DH prime I

. -If B is zero (the default) then no padding is -performed. - -=item "digest" (B) - -Gets and sets the name of the digest algorithm used for the input to the -signature functions. - -=item "digest-size" (B) - -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. -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 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 for the use of B 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. The key type used must match I if it is not -1. The parameter I is a mask indicating which operations the control can be applied to. @@ -662,17 +610,13 @@ allocate adequate memory space for the I 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, L, L, L, diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod new file mode 100644 index 0000000000..b4959c6f44 --- /dev/null +++ b/doc/man3/EVP_PKEY_CTX_set_params.pod @@ -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 + + 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 for more information on providers. +See L 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 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 for the use of B 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 +L +L + +L +L +L +L +L +L +L +L +L +L + +=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, +L, +L, +L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod new file mode 100644 index 0000000000..9e9cee7dce --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-DH.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-DH +- DH Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B key type. + +=head2 DH key exchange parameters + +=over 4 + +=item "pad" (B) + +See L. + +=back + +=head1 EXAMPLES + +The examples assume a host and peer both generate keys using the same +named group (or domain parameters). See L. +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, +L, +L, +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod new file mode 100644 index 0000000000..1add4b7100 --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-ECDH.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +EVP_KEYEXCH-ECDH - ECDH Key Exchange algorithm support + +=head1 DESCRIPTION + +Key exchange support for the B key type. + +=head2 ECDH Key Exchange parameters + +=over 4 + +=item "ecdh-cofactor-mode" (B) + +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 for the related +B parameter that can be set on a +per-key basis. + +=item "kdf-type" (B) + +Sets or gets the Key Derivation Function type to apply within the associated key +exchange ctx. + +=item "kdf-digest" (B) + +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) + +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) + +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) + +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) + +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) + +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 using the same curve name. + +The code to generate a shared secret for the normal case is identical to +L. + +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 +L, +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_KEYEXCH-X25519.pod b/doc/man7/EVP_KEYEXCH-X25519.pod new file mode 100644 index 0000000000..6140c56196 --- /dev/null +++ b/doc/man7/EVP_KEYEXCH-X25519.pod @@ -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 and B key types. + +=head2 Key exchange parameters + +=over 4 + +=item "pad" (B) + +See L. + +=back + +=head1 EXAMPLES + +Keys for the host and peer can be generated as shown in +L. + +The code to generate a shared secret is identical to +L. + +=head1 SEE ALSO + +L, +L +L, +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod new file mode 100644 index 0000000000..33b19a74f9 --- /dev/null +++ b/doc/man7/EVP_PKEY-DH.pod @@ -0,0 +1,229 @@ +=pod + +=head1 NAME + +EVP_PKEY-DH, EVP_KEYMGMT-DH - EVP_PKEY DH keytype and algorithm support + +=head1 DESCRIPTION + +For B 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 for more information about FFC keys. + +For B 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, I and I may need to be stored for validation purposes. +For B the I and I can be stored in ASN1 data +(but the I is not). + +=head2 DH parameters + +In addition to the common FCC parameters that all FFC keytypes should support +(see L)) the B keytype +implementation supports the following: + +=over 4 + +=item "group" (B) + +Set or gets a string that associates a B named safe prime group with known +values for I

, I and I. + +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

and I the value of I can also be +retrieved. + +=item "safeprime-generator" (B) + +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

. + +=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)) the +B keytype implementation supports the following: + +=over 4 + +=item "type" (B) + +Sets the type of parameter generation. For B valid values are: + +=over 4 + +=item "fips186_4" + +=item "default" + +=item "fips186_2" + +These are described in L + +=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) + +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) + +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)). 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 context can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL); + +An B 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 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, ¶m_key); + + EVP_PKEY_print_params(bio_out, param_key, 0, NULL); + ... + EVP_PKEY_free(param_key); + EVP_PKEY_CTX_free(pctx); + +An B 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, +L +L, +L, +L, +L, +L + +=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. + +=cut diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod index ccb34a9f93..680717b140 100644 --- a/doc/man7/EVP_PKEY-DSA.pod +++ b/doc/man7/EVP_PKEY-DSA.pod @@ -2,240 +2,77 @@ =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 and B 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 and I as well as the three main domain parameters -I

, I and I. - -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 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 (and B 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 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, I -and I may need to be stored for validation purposes. -For B the I and I can be stored in ASN1 data -(but the I is not). For B however, these fields are not stored in -the ASN1 data so they need to be stored externally if validation is required. +and I may need to be stored for validation purposes. For B 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) - -A string that associates a B named safe prime group with known values for -I

, I and I. - -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

and I the value of I can also be -retrieved. - -=item "safeprime-generator" (B) - -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

. - -=back - -=head2 Common DSA & DH parameters - -In addition to the common parameters that all keytypes should support (see -L), the B and B keytype -implementations support the following. - -=over 4 - -=item "pub" (B) - -The public key value. - -=item "priv" (B) - -The private key value. - -=item "p" (B) +The B key type supports the FFC parameters (see +L). -A DSA or Diffie-Hellman prime "p" value. +=head2 DSA key generation parameters -=item "q" (B) +The B key type supports the FFC key generation parameters (see +L -A DSA or Diffie-Hellman prime "q" value. - -=item "g" (B) - -A DSA or Diffie-Hellman generator "g" value. - -=item "seed" (B) - -An optional domain parameter I value used during generation and validation -of I

, I and canonical I. -For validation this needs to set the I that was produced during generation. - -=item "gindex" (B) - -Sets the index to use for canonical generation and verification of the generator -I. -Set this to a positive value from 0..FF to use this mode. This I can -then be reused during key validation to verify the value of I. If this value -is not set or is -1 then unverifiable generation of the generator I will be -used. - -=item "pcounter" (B) - -An optional domain parameter I value that is output during generation -of I

. This value must be saved if domain parameter validation is required. - -=item "hindex" (B) - -For unverifiable generation of the generator I this value is output during -generation of I. 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) - -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) - -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) - -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) +=head1 EXAMPLES -Sets the size (in bits) of the prime 'q'. +An B 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) +An B 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. -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) + 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. 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) + EVP_PKEY_gen(pctx, ¶m_key); + EVP_PKEY_CTX_free(pctx); -For "fips186_4" or "fips186_2" generation this sets the I 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) +An B key can be generated using domain parameters by calling: -=item "safeprime-generator" (B) + EVP_PKEY *key = NULL; + EVP_PKEY_CTX *gctx = NULL; -=item "gindex" (B) - -=item "pcounter" (B) - -=item "hindex" (B) - -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, L, L, -L, L, -L, L +L, +L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man7/EVP_PKEY-EC.pod b/doc/man7/EVP_PKEY-EC.pod index 88d0ebdd36..1995cf7676 100644 --- a/doc/man7/EVP_PKEY-EC.pod +++ b/doc/man7/EVP_PKEY-EC.pod @@ -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 -See also L for the related +See also L for the related B parameter that can be set on a per-operation basis. @@ -47,10 +48,68 @@ An B context can be obtained by calling: EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL); +An B 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 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, L, L, -L, L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man7/EVP_PKEY-FFC.pod b/doc/man7/EVP_PKEY-FFC.pod new file mode 100644 index 0000000000..e97a1c6bc4 --- /dev/null +++ b/doc/man7/EVP_PKEY-FFC.pod @@ -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 and B 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 and I as well as the three main domain parameters +I

, I and I. + +For B (and B 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, I +and I may need to be stored for validation purposes. +For B the I and I can be stored in ASN1 data +(but the I is not). For B 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), the B and B keytype +implementations support the following. + +=over 4 + +=item "pub" (B) + +The public key value. + +=item "priv" (B) + +The private key value. + +=item "p" (B) + +A DSA or Diffie-Hellman prime "p" value. + +=item "q" (B) + +A DSA or Diffie-Hellman prime "q" value. + +=item "g" (B) + +A DSA or Diffie-Hellman generator "g" value. + +=item "seed" (B) + +An optional domain parameter I value used during generation and validation +of I

, I and canonical I. +For validation this needs to set the I that was produced during generation. + +=item "gindex" (B) + +Sets the index to use for canonical generation and verification of the generator +I. +Set this to a positive value from 0..FF to use this mode. This I can +then be reused during key validation to verify the value of I. If this value +is not set or is -1 then unverifiable generation of the generator I will be +used. + +=item "pcounter" (B) + +An optional domain parameter I value that is output during generation +of I

. This value must be saved if domain parameter validation is required. + +=item "hindex" (B) + +For unverifiable generation of the generator I this value is output during +generation of I. 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) + +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) + +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) + +Sets the size (in bits) of the prime 'p'. + +=item "qbits" (B) + +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) + +Sets the Digest algorithm to be used as part of the Key Generation Function +associated with the given Key Generation I. +This must also be set for key validation. + +=item "properties" (B) + +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. This may also be set for key validation. + +=item "seed" (B) + +For "fips186_4" or "fips186_2" generation this sets the I 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) + +=item "pcounter" (B) + +=item "hindex" (B) + +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, +L, +L, +L +L, +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_PKEY-RSA.pod b/doc/man7/EVP_PKEY-RSA.pod index c6533f2ffc..ad49284437 100644 --- a/doc/man7/EVP_PKEY-RSA.pod +++ b/doc/man7/EVP_PKEY-RSA.pod @@ -121,6 +121,7 @@ The value should be the number of primes for the generated B 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 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 diff --git a/doc/man7/EVP_PKEY-X25519.pod b/doc/man7/EVP_PKEY-X25519.pod index 58f7525fd9..fa8c86844a 100644 --- a/doc/man7/EVP_PKEY-X25519.pod +++ b/doc/man7/EVP_PKEY-X25519.pod @@ -15,6 +15,8 @@ private key I. 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 index 0000000000..11fe500cb3 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-DSA.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE-DSA +- The B DSA signature implementation + +=head1 DESCRIPTION + +Support for computing DSA signatures. +See L 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) + +=item "properties" (B) + +The settable parameters are described in L. + +=back + +The following signature parameters can be retrieved using +EVP_PKEY_CTX_get_params(). + +=over 4 + +=item "algorithm-id" (B) + +=item "digest" (B) + +The gettable parameters are described in L. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_SIGNATURE-ECDSA.pod b/doc/man7/EVP_SIGNATURE-ECDSA.pod new file mode 100644 index 0000000000..04b80a1118 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-ECDSA.pod @@ -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 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) + +=item "properties" (B) + +These parameters are described in L. + +=back + +The following signature parameters can be retrieved using +EVP_PKEY_CTX_get_params(). + +=over 4 + +=item "algorithm-id" (B) + +=item "digest" (B) + +The parameters are described in L. + +=back + +=head1 SEE ALSO + +L, +L, +L, +L, + +=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. + +=cut diff --git a/doc/man7/EVP_SIGNATURE-ED25519.pod b/doc/man7/EVP_SIGNATURE-ED25519.pod new file mode 100644 index 0000000000..e3d9cd47e2 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-ED25519.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE-ED25519, +EVP_SIGNATURE-ED448, +Ed25519, +Ed448 +- EVP_PKEY Ed25519 and Ed448 support + +=head1 DESCRIPTION + +The B and B EVP_PKEY implementation supports key generation, +one-shot digest sign and digest verify using PureEdDSA and B or B +(see RFC8032). It has associated private and public key formats compatible with +RFC 8410. + +No additional parameters can be set during one-shot signing or verification. +In particular, because PureEdDSA is used, a digest must B be specified when +signing or verifying. +See L for information related to B and B keys. + +=head1 NOTES + +The PureEdDSA algorithm does not support the streaming mechanism +of other signature algorithms using, for example, EVP_DigestUpdate(). +The message to sign or verify must be passed using the one-shot +EVP_DigestSign() and EVP_DigestVerify() functions. + +When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the +digest I parameter B be set to NULL. + +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. + +Ed25519 or Ed448 private keys can be set directly using +L or loaded from a PKCS#8 private key file +using L (or similar function). Completely new keys +can also be generated (see the example below). Setting a private key also sets +the associated public key. + +Ed25519 or Ed448 public keys can be set directly using +L or loaded from a SubjectPublicKeyInfo +structure in a PEM file using L (or similar function). + +Ed25519 and Ed448 can be tested with the L application +since version 1.1.1. +Valid algorithm names are B, B and B. If B is +specified, then both Ed25519 and Ed448 are benchmarked. + +=head1 EXAMPLES + +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); + + EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len); + ... + OPENSSL_free(sig); + EVP_MD_CTX_free(md_ctx); + } + +=head1 SEE ALSO + +L +L, +L, +L, + +=head1 COPYRIGHT + +Copyright 2017-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. + +=cut diff --git a/doc/man7/EVP_SIGNATURE-RSA.pod b/doc/man7/EVP_SIGNATURE-RSA.pod new file mode 100644 index 0000000000..0cc3336bc9 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-RSA.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE-RSA +- The EVP_PKEY RSA signature implementa