mirror of
https://github.com/openssl/openssl.git
synced 2024-11-21 01:15:20 +08:00
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)
This commit is contained in:
Richard Levitte
parent
c07a34e18b
commit
0941666728
@ -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
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user