Digi
/
meta-digi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
meta-digi/meta-digi-dey/recipes-connectivity/openssl/openssl/0004-Amend-the-design-of-Al...

268 lines
14 KiB
Diff
Raw Blame History

From 284653acb6df4d68e276d4515a45ccd50ff54eab Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Thu, 25 Jul 2024 11:56:13 +0200
Subject: [PATCH] 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.
Upstream-Status: Backport [https://github.com/openssl/openssl/commit/0941666728c44d701496004ebd5bf96ac7b715fb]
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25000)
---
.../passing-algorithmidentifier-parameters.md | 65 ++++++++++++-------
doc/man3/EVP_EncryptInit.pod | 19 ++++--
util/perl/OpenSSL/paramnames.pm | 57 ++++++++++++----
3 files changed, 101 insertions(+), 40 deletions(-)
diff --git a/doc/designs/passing-algorithmidentifier-parameters.md b/doc/designs/passing-algorithmidentifier-parameters.md
index bb3821e337..f33862e45e 100644
--- 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 45c3cb062c..648dc60853 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -770,12 +770,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 bfa75f760c..8c70a594b9 100644
--- a/util/perl/OpenSSL/paramnames.pm
+++ b/util/perl/OpenSSL/paramnames.pm
@@ -68,6 +68,16 @@ my %params = (
'ALG_PARAM_MAC' => "mac", # utf8_string
'ALG_PARAM_PROPERTIES' => "properties", # utf8_string
+ # 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
@@ -100,8 +110,16 @@ my %params = (
'CIPHER_PARAM_RC2_KEYBITS' => "keybits", # size_t
'CIPHER_PARAM_SPEED' => "speed", # uint
'CIPHER_PARAM_CTS_MODE' => "cts_mode", # utf8_string
-# For passing the AlgorithmIdentifier parameter in DER form
- 'CIPHER_PARAM_ALGORITHM_ID_PARAMS' => "alg_id_param",# octet_string
+ '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',
+ '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
@@ -250,6 +268,10 @@ my %params = (
# it for API stability, but please use ASYM_CIPHER_PARAM_IMPLICIT_REJECTION
# instead.
'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",
@@ -378,17 +400,26 @@ my %params = (
'EXCHANGE_PARAM_KDF_UKM' => "kdf-ukm",
# 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_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',
+ 'SIGNATURE_PARAM_SIGNATURE' => "signature",
# Asym cipher parameters
'ASYM_CIPHER_PARAM_DIGEST' => '*PKEY_PARAM_DIGEST',
--
2.43.0
Reference in New Issue View Git Blame Copy Permalink