Amend the design of AlgorithmIdentifier parameter passing

I realised that any application that passes AlgorithmIdentifier parameters
to and from a provider may also be interested in the full AlgorithmIdentifier
of the implementation invocation.

Likewise, any application that wants to get the full AlgorithmIdentifier
from an implementation invocation may also want to pass AlgorithmIdentifier
parameters to that same implementation invocation.

These amendments should be useful to cover all intended uses of the legacy
ctrls for PKCS7 and CMS:

- EVP_PKEY_CTRL_PKCS7_ENCRYPT
- EVP_PKEY_CTRL_PKCS7_DECRYPT
- EVP_PKEY_CTRL_PKCS7_SIGN
- EVP_PKEY_CTRL_CMS_ENCRYPT
- EVP_PKEY_CTRL_CMS_DECRYPT
- EVP_PKEY_CTRL_CMS_SIGN

It should also cover a number of other cases that were previously implemented
through EVP_PKEY_ASN1_METHOD, as well as all sorts of other cases where the
application has had to assemble a X509_ALGOR on their own.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25000)

diff --git a/doc/designs/passing-algorithmidentifier-parameters.md b/doc/designs/passing-algorithmidentifier-parameters.md
index bb3821e33713b6a301dd288a916d8e8e5377a854..f33862e45e20554a7899d2f7ebb71eb02ddfb070 100644 (file)
--- a/doc/designs/passing-algorithmidentifier-parameters.md
+++ b/doc/designs/passing-algorithmidentifier-parameters.md
@@ -1,11 +1,13 @@
-Passing AlgorithmIdentifier parameters to operations
-====================================================
+Handling AlgorithmIdentifier and its parameters with provider operations
+========================================================================
 
 Quick background
 ----------------
 
 We currently only support passing the AlgorithmIdentifier (`X509_ALGOR`)
-parameter field to symmetric cipher provider implementations.
+parameter field to symmetric cipher provider implementations.  We currently
+only support getting full AlgorithmIdentifier (`X509_ALGOR`) from signature
+provider implementations.
 
 We do support passing them to legacy implementations of other types of
 operation algorithms as well, but it's done in a way that can't be supported
@@ -15,18 +17,30 @@ libcrypto and the backend implementation.
 For a longer background and explanation, see
 [Background / tl;dr](#background-tldr) at the end of this design.
 
-Establish an OSSL_PARAM key that any algorithms may become aware of
--------------------------------------------------------------------
+Establish OSSL_PARAM keys that any algorithms may become aware of
+-----------------------------------------------------------------
 
-We already have a parameter key, but it's currently only specified for
-`EVP_CIPHER`, in support of `EVP_CIPHER_param_to_asn1()` and
-`EVP_CIPHER_asn1_to_param()`.
+We already have known parameter keys:
 
-"alg_id_param", also known as the macro `OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS`
+- "algor_id_param", also known as the macro `OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS`.
 
-This parameter can be used in the exact same manner with other operations,
-with the value of the AlgorithmIdentifier parameter as an octet string, to
-be interpreted by the implementations in whatever way they see fit.
+  This is currently only specified for `EVP_CIPHER`, in support of
+  `EVP_CIPHER_param_to_asn1()` and `EVP_CIPHER_asn1_to_param()`
+
+- "algorithm-id", also known as the macro `OSSL_SIGNATURE_PARAM_ALGORITHM_ID`.
+
+This design proposes:
+
+1. Adding a parameter key "algorithm-id-params", to replace "algor_id_param",
+   and deprecate the latter.
+2. Making both "algorithm-id" and "algorithm-id-params" generically available,
+   rather than only tied to `EVP_SIGNATURE` ("algorithm-id") or `EVP_CIPHER`
+   ("algor_id_param").
+
+This way, these parameters can be used in the exact same manner with other
+operations, with the value of the AlgorithmIdentifier as well as its
+parameters as octet strings, to be used and interpreted by applications and
+provider implementations alike in whatever way they see fit.
 
 Applications can choose to add these in an `OSSL_PARAM` array, to be passed
 with the multitude of initialization functions that take such an array, or
@@ -34,7 +48,7 @@ using specific operation `OSSL_PARAM` setters and getters (such as
 `EVP_PKEY_CTX_set_params`), or using other available convenience functions
 (see below).
 
-This parameter will have to be documented in the following files:
+These parameter will have to be documented in the following files:
 
 - `doc/man7/provider-asym_cipher.pod`
 - `doc/man7/provider-cipher.pod`
@@ -67,20 +81,25 @@ such parameter data from them.
  * These two would essentially be aliases for EVP_CIPHER_param_to_asn1()
  * and EVP_CIPHER_asn1_to_param().
  */
-EVP_CIPHER_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
-EVP_CIPHER_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_CIPHER_CTX_set_algor_params(EVP_CIPHER_CTX *ctx, const X509_ALGOR *alg);
+EVP_CIPHER_CTX_get_algor_params(EVP_CIPHER_CTX *ctx, X509_ALGOR *alg);
+EVP_CIPHER_CTX_get_algor(EVP_CIPHER_CTX *ctx, X509_ALGOR **alg);
 
-EVP_MD_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
-EVP_MD_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_MD_CTX_set_algor_params(EVP_MD_CTX *ctx, const X509_ALGOR *alg);
+EVP_MD_CTX_get_algor_params(EVP_MD_CTX *ctx, X509_ALGOR *alg);
+EVP_MD_CTX_get_algor(EVP_MD_CTX *ctx, X509_ALGOR **alg);
 
-EVP_MAC_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
-EVP_MAC_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_MAC_CTX_set_algor_params(EVP_MAC_CTX *ctx, const X509_ALGOR *alg);
+EVP_MAC_CTX_get_algor_params(EVP_MAC_CTX *ctx, X509_ALGOR *alg);
+EVP_MAC_CTX_get_algor(EVP_MAC_CTX *ctx, X509_ALGOR **alg);
 
-EVP_KDF_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
-EVP_KDF_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_KDF_CTX_set_algor_params(EVP_KDF_CTX *ctx, const X509_ALGOR *alg);
+EVP_KDF_CTX_get_algor_params(EVP_KDF_CTX *ctx, X509_ALGOR *alg);
+EVP_KDF_CTX_get_algor(EVP_KDF_CTX *ctx, X509_ALGOR **alg);
 
-EVP_PKEY_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
-EVP_PKEY_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_PKEY_CTX_set_algor_params(EVP_PKEY_CTX *ctx, const X509_ALGOR *alg);
+EVP_PKEY_CTX_get_algor_params(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
+EVP_PKEY_CTX_get_algor(EVP_PKEY_CTX *ctx, X509_ALGOR **alg);
 ```
 
 Note that all might not need to be added immediately, depending on if they

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 3a09ab443484d34af65d9a3fcb773184d4eff522..b38e82059893afb1cdd213625b95825d2fbcdf86 100644 (file)
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -782,12 +782,23 @@ The length of the "keybits" parameter should not exceed that of a B<size_t>.
 Gets or sets the number of rounds to be used for a cipher.
 This is used by the RC5 cipher.
 
-=item "alg_id_param" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string>
+=item "algorithm-id" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID>) <octet string>
+
+Used to get the DER encoded AlgorithmIdentifier from the cipher
+implementation.  Functions like L<EVP_PKEY_CTX_get_algor(3)> use this
+parameter.
+
+=item "algorithm-id-params" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string>
 
 Used to pass the DER encoded AlgorithmIdentifier parameter to or from
-the cipher implementation.  Functions like L<EVP_CIPHER_param_to_asn1(3)>
-and L<EVP_CIPHER_asn1_to_param(3)> use this parameter for any implementation
-that has the flag B<EVP_CIPH_FLAG_CUSTOM_ASN1> set.
+the cipher implementation.
+Functions like L<EVP_CIPHER_CTX_set_algor_params(3)> and
+L<EVP_CIPHER_CTX_get_algor_params(3)> use this parameter.
+
+=item "alg_id_params" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD>) <octet string>
+
+An deprecated alias for "algorithm-id-params", only used by
+L<EVP_CIPHER_param_to_asn1(3)> and L<EVP_CIPHER_asn1_to_param(3)>.
 
 =item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string>
 

diff --git a/util/perl/OpenSSL/paramnames.pm b/util/perl/OpenSSL/paramnames.pm
index 0a6ca49aedec4dce3788c9cc187fad8d99d61748..c5d26ab743fdcbf9ea256ec462a7ed0fbcea46a7 100644 (file)
--- a/util/perl/OpenSSL/paramnames.pm
+++ b/util/perl/OpenSSL/paramnames.pm
@@ -91,6 +91,16 @@ my %params = (
     'ALG_PARAM_PROPERTIES' =>   "properties",   # utf8_string
     'ALG_PARAM_FIPS_APPROVED_INDICATOR' => 'fips-indicator',   # int, -1, 0 or 1
 
+    # For any operation that deals with AlgorithmIdentifier, they should
+    # implement both of these.
+    # ALG_PARAM_ALGORITHM_ID is intended to be gettable, and is the
+    # implementation's idea of what its full AlgID should look like.
+    # ALG_PARAM_ALGORITHM_ID_PARAMS is intended to be both settable
+    # and gettable, to allow the calling application to pass or get
+    # AlgID parameters to and from the provided implementation.
+    'ALG_PARAM_ALGORITHM_ID' => "algorithm-id", # octet_string (DER)
+    'ALG_PARAM_ALGORITHM_ID_PARAMS' =>  "algorithm-id-params", # octet_string
+
 # cipher parameters
     'CIPHER_PARAM_PADDING' =>              "padding",     # uint
     'CIPHER_PARAM_USE_BITS' =>             "use-bits",    # uint
@@ -127,8 +137,13 @@ my %params = (
     'CIPHER_PARAM_DECRYPT_ONLY' =>         "decrypt-only",  # int, 0 or 1
     'CIPHER_PARAM_FIPS_ENCRYPT_CHECK' =>   "encrypt-check", # int
     'CIPHER_PARAM_FIPS_APPROVED_INDICATOR' => '*ALG_PARAM_FIPS_APPROVED_INDICATOR',
-# For passing the AlgorithmIdentifier parameter in DER form
-    'CIPHER_PARAM_ALGORITHM_ID_PARAMS' =>  "alg_id_param",# octet_string
+    'CIPHER_PARAM_ALGORITHM_ID' =>         '*ALG_PARAM_ALGORITHM_ID',
+    # Historically, CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD was used.  For the
+    # time being, the old libcrypto functions will use both, so old providers
+    # continue to work.
+    # New providers are encouraged to use CIPHER_PARAM_ALGORITHM_ID_PARAMS.
+    'CIPHER_PARAM_ALGORITHM_ID_PARAMS' =>  '*ALG_PARAM_ALGORITHM_ID_PARAMS',
+    'CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD' => "alg_id_param", # octet_string
     'CIPHER_PARAM_XTS_STANDARD' =>         "xts_standard",# utf8_string
 
     'CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT' =>  "tls1multi_maxsndfrag",# uint
@@ -286,6 +301,8 @@ my %params = (
     'PKEY_PARAM_IMPLICIT_REJECTION' =>  "implicit-rejection",
     'PKEY_PARAM_FIPS_DIGEST_CHECK' =>   "digest-check",
     'PKEY_PARAM_FIPS_KEY_CHECK' =>      "key-check",
+    'PKEY_PARAM_ALGORITHM_ID' =>        '*ALG_PARAM_ALGORITHM_ID',
+    'PKEY_PARAM_ALGORITHM_ID_PARAMS' => '*ALG_PARAM_ALGORITHM_ID_PARAMS',
 
 # Diffie-Hellman/DSA Parameters
     'PKEY_PARAM_FFC_P' =>               "p",
@@ -421,21 +438,22 @@ my %params = (
     'EXCHANGE_PARAM_FIPS_APPROVED_INDICATOR' => '*ALG_PARAM_FIPS_APPROVED_INDICATOR',
 
 # Signature parameters
-    'SIGNATURE_PARAM_ALGORITHM_ID' =>       "algorithm-id",
-    'SIGNATURE_PARAM_PAD_MODE' =>           '*PKEY_PARAM_PAD_MODE',
-    'SIGNATURE_PARAM_DIGEST' =>             '*PKEY_PARAM_DIGEST',
-    'SIGNATURE_PARAM_PROPERTIES' =>         '*PKEY_PARAM_PROPERTIES',
-    'SIGNATURE_PARAM_PSS_SALTLEN' =>        "saltlen",
-    'SIGNATURE_PARAM_MGF1_DIGEST' =>        '*PKEY_PARAM_MGF1_DIGEST',
-    'SIGNATURE_PARAM_MGF1_PROPERTIES' =>    '*PKEY_PARAM_MGF1_PROPERTIES',
-    'SIGNATURE_PARAM_DIGEST_SIZE' =>        '*PKEY_PARAM_DIGEST_SIZE',
-    'SIGNATURE_PARAM_NONCE_TYPE' =>         "nonce-type",
-    'SIGNATURE_PARAM_INSTANCE' =>           "instance",
-    'SIGNATURE_PARAM_CONTEXT_STRING' =>     "context-string",
-    'SIGNATURE_PARAM_FIPS_DIGEST_CHECK' =>  '*PKEY_PARAM_FIPS_DIGEST_CHECK',
-    'SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE' => 'verify-message',
-    'SIGNATURE_PARAM_FIPS_KEY_CHECK' =>     '*PKEY_PARAM_FIPS_KEY_CHECK',
-    'SIGNATURE_PARAM_FIPS_SIGN_CHECK' =>    '*PKEY_PARAM_FIPS_SIGN_CHECK',
+    'SIGNATURE_PARAM_ALGORITHM_ID' =>         '*PKEY_PARAM_ALGORITHM_ID',
+    'SIGNATURE_PARAM_ALGORITHM_ID_PARAMS' =>  '*PKEY_PARAM_ALGORITHM_ID_PARAMS',
+    'SIGNATURE_PARAM_PAD_MODE' =>             '*PKEY_PARAM_PAD_MODE',
+    'SIGNATURE_PARAM_DIGEST' =>               '*PKEY_PARAM_DIGEST',
+    'SIGNATURE_PARAM_PROPERTIES' =>           '*PKEY_PARAM_PROPERTIES',
+    'SIGNATURE_PARAM_PSS_SALTLEN' =>          "saltlen",
+    'SIGNATURE_PARAM_MGF1_DIGEST' =>          '*PKEY_PARAM_MGF1_DIGEST',
+    'SIGNATURE_PARAM_MGF1_PROPERTIES' =>      '*PKEY_PARAM_MGF1_PROPERTIES',
+    'SIGNATURE_PARAM_DIGEST_SIZE' =>          '*PKEY_PARAM_DIGEST_SIZE',
+    'SIGNATURE_PARAM_NONCE_TYPE' =>           "nonce-type",
+    'SIGNATURE_PARAM_INSTANCE' =>             "instance",
+    'SIGNATURE_PARAM_CONTEXT_STRING' =>       "context-string",
+    'SIGNATURE_PARAM_FIPS_DIGEST_CHECK' =>    '*PKEY_PARAM_FIPS_DIGEST_CHECK',
+    'SIGNATURE_PARAM_FIPS_VERIFY_MESSAGE' =>  'verify-message',
+    'SIGNATURE_PARAM_FIPS_KEY_CHECK' =>       '*PKEY_PARAM_FIPS_KEY_CHECK',
+    'SIGNATURE_PARAM_FIPS_SIGN_CHECK' =>      '*PKEY_PARAM_FIPS_SIGN_CHECK',
     'SIGNATURE_PARAM_FIPS_RSA_PSS_SALTLEN_CHECK' => "rsa-pss-saltlen-check",
     'SIGNATURE_PARAM_FIPS_SIGN_X931_PAD_CHECK' => "sign-x931-pad-check",
     'SIGNATURE_PARAM_FIPS_APPROVED_INDICATOR' => '*ALG_PARAM_FIPS_APPROVED_INDICATOR',