Reorganize the internal evp_keymgmt functions

[thirdparty/openssl.git] / doc / man7 / provider-keymgmt.pod

=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 domain parameter validation */
 int OP_keymgmt_validate_domparams(void *key);

 /* 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);

 /* Key validation */
 int OP_keymgmt_validate_public(void *key);
 int OP_keymgmt_validate_private(void *key);
 int OP_keymgmt_validate_pairwise(void *key);

 /* 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

 OP_keymgmt_validate_domparams   OSSL_FUNC_KEYMGMT_VALIDATE_DOMPARAMS
 OP_keymgmt_validate_public      OSSL_FUNC_KEYMGMT_VALIDATE_PUBLIC
 OP_keymgmt_validate_private     OSSL_FUNC_KEYMGMT_VALIDATE_PRIVATE
 OP_keymgmt_validate_pairwise    OSSL_FUNC_KEYMGMT_VALIDATE_PAIRWISE

=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.

OP_keymgmt_validate_domparams() should return a value of 1 if the
domain parameters are valid, or 0 for invalid.

=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.

OP_keymgmt_validate_public() should return 1 if the public component of the
key is valid, or 0 if invalid.
OP_keymgmt_validate_private() should return 1 if the private component of the
key is valid, or 0 if invalid.
OP_keymgmt_validate_pairwise() should return 1 if the the pairwise consistency
of the key is valid, or 0 if invalid.


=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-2020 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