| =pod |
| |
| =head1 NAME |
| |
| provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions |
| |
| =head1 SYNOPSIS |
| |
| #include <openssl/core_numbers.h> |
| |
| /* |
| * None of these are actual functions, but are displayed like this for |
| * the function signatures for functions that are offered as function |
| * pointers in OSSL_DISPATCH arrays. |
| */ |
| |
| /* Key domain parameter creation and destruction */ |
| void *OP_keymgmt_importdomparams(void *provctx, const OSSL_PARAM params[]); |
| void *OP_keymgmt_gendomparams(void *provctx, const OSSL_PARAM params[]); |
| void OP_keymgmt_freedomparams(void *domparams); |
| |
| /* Key domain parameter export */ |
| int OP_keymgmt_exportdomparams(void *domparams, OSSL_PARAM params[]); |
| |
| /* Key domain parameter discovery */ |
| 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, |
| void *domparams, const OSSL_PARAM genkeyparams[]); |
| void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen); |
| void OP_keymgmt_freekey(void *key); |
| |
| /* Key export */ |
| int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]); |
| |
| /* Key discovery */ |
| 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); |
| |
| =head1 DESCRIPTION |
| |
| The KEYMGMT operation doesn't have much public visibility in OpenSSL |
| libraries, it's rather an internal operation that's designed to work |
| in tandem with operations that use private/public key pairs. |
| |
| Because the KEYMGMT operation shares knowledge with the operations it |
| works with in tandem, they must belong to the same provider. |
| The OpenSSL libraries will ensure that they do. |
| |
| The primary responsibility of the KEYMGMT operation is to hold the |
| provider side domain parameters and keys for the OpenSSL library |
| EVP_PKEY structure. |
| |
| All "functions" mentioned here are passed as function pointers between |
| F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via |
| B<OSSL_ALGORITHM> arrays that are returned by the provider's |
| provider_query_operation() function |
| (see L<provider-base(7)/Provider Functions>). |
| |
| All these "functions" have a corresponding function type definition |
| named B<OSSL_{name}_fn>, and a helper function to retrieve the |
| function pointer from a B<OSSL_DISPATCH> element named |
| B<OSSL_get_{name}>. |
| For example, the "function" OP_keymgmt_importdomparams() has these: |
| |
| typedef void * |
| (OSSL_OP_keymgmt_importdomparams_fn)(void *provctx, |
| const OSSL_PARAM params[]); |
| static ossl_inline OSSL_OP_keymgmt_importdomparams_fn |
| OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf); |
| |
| B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as |
| macros in L<openssl-core_numbers.h(7)>, as follows: |
| |
| OP_keymgmt_importdomparams OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS |
| OP_keymgmt_gendomparams OSSL_FUNC_KEYMGMT_GENDOMPARAMS |
| OP_keymgmt_freedomparams OSSL_FUNC_KEYMGMT_FREEDOMPARAMS |
| 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 |
| OP_keymgmt_loadkey OSSL_FUNC_KEYMGMT_LOADKEY |
| OP_keymgmt_freekey OSSL_FUNC_KEYMGMT_FREEKEY |
| 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 |
| |
| OP_keymgmt_importdomparams() should create a provider side structure |
| for domain parameters, with values taken from the passed B<OSSL_PARAM> |
| array I<params>. |
| |
| OP_keymgmt_gendomparams() should generate domain parameters and create |
| a provider side structure for them. |
| Values of the passed B<OSSL_PARAM> array I<params> should be used as |
| input for parameter generation. |
| |
| OP_keymgmt_freedomparams() should free the passed provider side domain |
| parameter structure I<domparams>. |
| |
| OP_keymgmt_exportdomparams() should extract values from the passed |
| provider side domain parameter structure I<domparams> into the passed |
| B<OSSL_PARAM> I<params>. |
| Only the values specified in I<params> should be extracted. |
| |
| OP_keymgmt_importdomparam_types() should return a constant array of |
| descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams() |
| can handle. |
| |
| 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 |
| for keys, with values taken from the passed B<OSSL_PARAM> array |
| I<params>. |
| |
| OP_keymgmt_genkey() should generate keys and create a provider side |
| structure for them. |
| Values from the passed domain parameters I<domparams> as well as from |
| the passed B<OSSL_PARAM> array I<params> should be used as input for |
| key generation. |
| |
| OP_keymgmt_loadkey() should return a provider side key structure with |
| a key loaded from a location known only to the provider, identitified |
| with the identity I<id> of size I<idlen>. |
| This identity is internal to the provider and is retrieved from the |
| provider through other means. |
| |
| =for comment Right now, OP_keymgmt_loadkey is useless, but will be |
| useful as soon as we have a OSSL_STORE interface |
| |
| OP_keymgmt_freekey() should free the passed I<key>. |
| |
| OP_keymgmt_exportkey() should extract values from the passed |
| provider side key I<key> into the passed B<OSSL_PARAM> I<params>. |
| Only the values specified in I<params> should be extracted. |
| |
| OP_keymgmt_importkey_types() should return a constant array of |
| descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey() |
| can handle. |
| |
| 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 |
| supported algorithm for the operation I<operation_id>. This is |
| similar to provider_query_operation() (see L<provider-base(7)>), |
| but only works as an advisory. If this function is not present, or |
| 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)> |
| |
| =head1 HISTORY |
| |
| The KEYMGMT interface was introduced in OpenSSL 3.0. |
| |
| =head1 COPYRIGHT |
| |
| Copyright 2019 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<https://www.openssl.org/source/license.html>. |
| |
| =cut |