diff options
author | Richard Levitte <levitte@openssl.org> | 2020-01-08 03:44:28 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-01-17 09:04:04 +0100 |
commit | 6508e858836020622efff5dd4be3fa4530d1584b (patch) | |
tree | ec7f0d78108dadd5762d07cc373f67af5a931464 /doc | |
parent | e4a1d0230016d090ba78bc7092384315f85b0e72 (diff) |
EVP: make EVP_PKEY_{bits,security_bits,size} work with provider only keys
These functions relied entirely on the presence of 'pkey->pmeth',
which is NULL on provider only keys. This adds an interface to get
domparam and key data from a provider, given corresponding provider
data (the actual domparam or key).
The retrieved data is cached in the EVP_PKEY structure (lending the
idea from provided EVP_CIPHER).
Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/10778)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man7/provider-keymgmt.pod | 72 |
1 files changed, 66 insertions, 6 deletions
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 1c868c5630..adc1978a36 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -26,6 +26,10 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions const OSSL_PARAM *OP_keymgmt_importdomparam_types(void); const OSSL_PARAM *OP_keymgmt_exportdomparam_types(void); + /* Key domain parameter information */ + int OP_keymgmt_get_domparam_params(void *domparams, OSSL_PARAM params[]); + const OSSL_PARAM *OP_keymgmt_gettable_domparam_params(void); + /* Key creation and destruction */ void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]); void *OP_keymgmt_genkey(void *provctx, @@ -40,6 +44,10 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions const OSSL_PARAM *OP_keymgmt_importkey_types(void); const OSSL_PARAM *OP_keymgmt_exportkey_types(void); + /* Key information */ + int OP_keymgmt_get_key_params(void *key, OSSL_PARAM params[]); + const OSSL_PARAM *OP_keymgmt_gettable_key_params(void); + /* Discovery of supported operations */ const char *OP_keymgmt_query_operation_name(int operation_id); @@ -84,6 +92,9 @@ macros in L<openssl-core_numbers.h(7)>, as follows: OP_keymgmt_exportdomparams OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES + OP_keymgmt_get_domparam_params OSSL_FUNC_KEYMGMT_GET_DOMPARAM_PARAMS + OP_keymgmt_gettable_domparam_params + OSSL_FUNC_KEYMGMT_GETTABLE_DOMPARAM_PARAMS OP_keymgmt_importkey OSSL_FUNC_KEYMGMT_IMPORTKEY OP_keymgmt_genkey OSSL_FUNC_KEYMGMT_GENKEY @@ -92,6 +103,10 @@ macros in L<openssl-core_numbers.h(7)>, as follows: OP_keymgmt_exportkey OSSL_FUNC_KEYMGMT_EXPORTKEY OP_keymgmt_importkey_types OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES OP_keymgmt_exportkey_types OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES + OP_keymgmt_get_key_params OSSL_FUNC_KEYMGMT_GET_KEY_PARAMS + OP_keymgmt_gettable_key_params OSSL_FUNC_KEYMGMT_GETTABLE_KEY_PARAMS + + OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME =head2 Domain Parameter Functions @@ -116,13 +131,18 @@ OP_keymgmt_importdomparam_types() should return a constant array of descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams() can handle. -=for comment There should be one corresponding to OP_keymgmt_gendomparams() -as well... - OP_keymgmt_exportdomparam_types() should return a constant array of descriptor B<OSSL_PARAM>, for parameters that can be exported with OP_keymgmt_exportdomparams(). +OP_keymgmt_get_domparam_params() should extract information data +associated with the given I<domparams>, +see L</Information Parameters>. + +OP_keymgmt_gettable_domparam_params() should return a constant array +of descriptor B<OSSL_PARAM>, for parameters that +OP_keymgmt_get_domparam_params() can handle. + =head2 Key functions OP_keymgmt_importkey() should create a provider side structure @@ -154,13 +174,17 @@ OP_keymgmt_importkey_types() should return a constant array of descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey() can handle. -=for comment There should be one corresponding to OP_keymgmt_genkey() -as well... - OP_keymgmt_exportkey_types() should return a constant array of descriptor B<OSSL_PARAM>, for parameters that can be exported with OP_keymgmt_exportkeys(). +OP_keymgmt_get_key_params() should extract information data associated +with the given I<key>, see L</Information Parameters>. + +OP_keymgmt_gettable_key_params() should return a constant array of +descriptor B<OSSL_PARAM>, for parameters that +OP_keymgmt_get_key_params() can handle. + =head2 Supported operations OP_keymgmt_query_operation_name() should return the name of the @@ -171,6 +195,42 @@ returns NULL, the caller is free to assume that there's an algorithm from the same provider, of the same name as the one used to fetch the keymgmt and try to use that. +=head2 Information Parameters + +See L<OSSL_PARAM(3)> for further details on the parameters structure. + +Parameters currently recognised by built-in keymgmt algorithms' +OP_keymgmt_get_domparams_params() and OP_keymgmt_get_key_params() +are: + +=over 4 + +=item "bits" (B<OSSL_PKEY_PARAM_BITS>) <integer> + +The value should be the cryptographic length of the cryptosystem to +which the key belongs, in bits. The definition of cryptographic +length is specific to the key cryptosystem. + +=item "max-size" (B<OSSL_PKEY_PARAM_MAX_SIZE>) <integer> + +The value should be the maximum size that a caller should allocate to +safely store a signature (called I<sig> in L<provider-signature(7)>), +the result of asymmmetric encryption / decryption (I<out> in +L<provider-asym_cipher(7)>, a derived secret (I<secret> in +L<provider-keyexch(7)>, and similar data). + +Because an EVP_KEYMGMT method is always tightly bound to another method +(signature, asymmetric cipher, key exchange, ...) and must be of the +same provider, this number only needs to be synchronised with the +dimensions handled in the rest of the same provider. + +=item "security-bits" (B<OSSL_PKEY_PARAM_SECURITY_BITS>) <integer> + +The value should be the number of security bits of the given key. +Bits of security is defined in SP800-57. + +=back + =head1 SEE ALSO L<provider(7)> |