Latest update.
This commit is contained in:
@@ -21,26 +21,30 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
|
||||
/* Key object information */
|
||||
int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
|
||||
const OSSL_PARAM *OP_keymgmt_gettable_params(void);
|
||||
int OP_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
|
||||
const OSSL_PARAM *OP_keymgmt_settable_params(void);
|
||||
|
||||
/* Key object content checks */
|
||||
int OP_keymgmt_has(void *keydata, int selection);
|
||||
int OP_keymgmt_match(const void *keydata1, const void *keydata2,
|
||||
int selection);
|
||||
|
||||
/* Discovery of supported operations */
|
||||
const char *OP_keymgmt_query_operation_name(int operation_id);
|
||||
|
||||
/* Key object import and export functions */
|
||||
int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
|
||||
const OSSL_PARAM *OP_keymgmt_import_types, (int selection);
|
||||
const OSSL_PARAM *OP_keymgmt_import_types(int selection);
|
||||
int OP_keymgmt_export(int selection, void *keydata,
|
||||
OSSL_CALLBACK *param_cb, void *cbarg);
|
||||
const OSSL_PARAM *OP_keymgmt_export_types(int selection);
|
||||
|
||||
/* Key object copy */
|
||||
int OP_keymgmt_copy(void *keydata_to, const void *keydata_from, int selection);
|
||||
|
||||
/* Key object validation */
|
||||
int OP_keymgmt_validate(void *keydata, int selection);
|
||||
|
||||
/* 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
|
||||
@@ -78,17 +82,21 @@ macros in L<openssl-core_numbers.h(7)>, as follows:
|
||||
|
||||
OP_keymgmt_get_params OSSL_FUNC_KEYMGMT_GET_PARAMS
|
||||
OP_keymgmt_gettable_params OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
|
||||
OP_keymgmt_set_params OSSL_FUNC_KEYMGMT_SET_PARAMS
|
||||
OP_keymgmt_settable_params OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
|
||||
|
||||
OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
|
||||
|
||||
OP_keymgmt_has OSSL_FUNC_KEYMGMT_HAS
|
||||
OP_keymgmt_validate OSSL_FUNC_KEYMGMT_VALIDATE
|
||||
OP_keymgmt_match OSSL_FUNC_KEYMGMT_MATCH
|
||||
|
||||
OP_keymgmt_import OSSL_FUNC_KEYMGMT_IMPORT
|
||||
OP_keymgmt_import_types OSSL_FUNC_KEYMGMT_IMPORT_TYPES
|
||||
OP_keymgmt_export OSSL_FUNC_KEYMGMT_EXPORT
|
||||
OP_keymgmt_export_types OSSL_FUNC_KEYMGMT_EXPORT_TYPES
|
||||
|
||||
OP_keymgmt_copy OSSL_FUNC_KEYMGMT_COPY
|
||||
|
||||
=head2 Key Objects
|
||||
|
||||
@@ -202,7 +210,17 @@ descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
|
||||
can handle.
|
||||
|
||||
If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
|
||||
must also be present.
|
||||
must also be present, and vice versa.
|
||||
|
||||
OP_keymgmt_set_params() should update information data associated
|
||||
with the given I<keydata>, see L</Information Parameters>.
|
||||
|
||||
OP_keymgmt_settable_params() should return a constant array of
|
||||
descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_set_params()
|
||||
can handle.
|
||||
|
||||
If OP_keymgmt_settable_params() is present, OP_keymgmt_set_params()
|
||||
must also be present, and vice versa.
|
||||
|
||||
=head2 Key Object Checking Functions
|
||||
|
||||
@@ -214,7 +232,7 @@ 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.
|
||||
|
||||
OP_keymgmt_has() should check whether the given I<keydata> the subsets
|
||||
OP_keymgmt_has() should check whether the given I<keydata> contains the subsets
|
||||
of data indicated by the I<selector>. A combination of several
|
||||
selector bits must consider all those subsets, not just one. An
|
||||
implementation is, however, free to consider an empty subset of data
|
||||
@@ -228,7 +246,12 @@ B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY> (or B<OSSL_KEYMGMT_SELECT_KEYPAIR>
|
||||
for short) is expected to check that the pairwise consistency of
|
||||
I<keydata> is valid.
|
||||
|
||||
=head2 Key Object Import and Export Functions
|
||||
OP_keymgmt_match() should check if the data subset indicated by
|
||||
I<selection> in I<keydata1> and I<keydata2> match. It is assumed that
|
||||
the caller has ensured that I<keydata1> and I<keydata2> are both owned
|
||||
by the implementation of this function.
|
||||
|
||||
=head2 Key Object Import, Export and Copy Functions
|
||||
|
||||
OP_keymgmt_import() should import data indicated by I<selection> into
|
||||
I<keydata> with values taken from the B<OSSL_PARAM> array I<params>.
|
||||
@@ -245,12 +268,100 @@ OP_keymgmt_export_types() should return a constant array of descriptor
|
||||
B<OSSL_PARAM> for data indicated by I<selection>, that the
|
||||
OP_keymgmt_export() callback can expect to receive.
|
||||
|
||||
OP_keymgmt_copy() should copy data subsets indicated by I<selection>
|
||||
from I<keydata_from> to I<keydata_to>. It is assumed that the caller
|
||||
has ensured that I<keydata_to> and I<keydata_from> are both owned by
|
||||
the implementation of this function.
|
||||
|
||||
=head2 Built-in RSA Import/Export Types
|
||||
|
||||
The following Import/Export types are available for the built-in RSA algorithm:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <integer>
|
||||
|
||||
The RSA "n" value.
|
||||
|
||||
=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <integer>
|
||||
|
||||
The RSA "e" value.
|
||||
|
||||
=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <integer>
|
||||
|
||||
The RSA "d" value.
|
||||
|
||||
=item "rsa-factor" (B<OSSL_PKEY_PARAM_RSA_FACTOR>) <integer>
|
||||
|
||||
An RSA factor. In 2 prime RSA these are often known as "p" or "q". This value
|
||||
may be repeated up to 10 times in a single key.
|
||||
|
||||
=item "rsa-exponent" (B<OSSL_PKEY_PARAM_RSA_EXPONENT>) <integer>
|
||||
|
||||
An RSA CRT (Chinese Remainder Theorem) exponent. This value may be repeated up
|
||||
to 10 times in a single key.
|
||||
|
||||
=item "rsa-coefficient" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT>) <integer>
|
||||
|
||||
An RSA CRT (Chinese Remainder Theorem) coefficient. This value may be repeated
|
||||
up to 9 times in a single key.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Built-in DSA and Diffie-Hellman Import/Export Types
|
||||
|
||||
The following Import/Export types are available for the built-in DSA and
|
||||
Diffie-Hellman algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <integer> or <octet string>
|
||||
|
||||
The public key value.
|
||||
|
||||
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <integer> or <octet string>
|
||||
|
||||
The private key value.
|
||||
|
||||
=item "p" (B<OSSL_PKEY_PARAM_FFC_P>) <integer>
|
||||
|
||||
A DSA or Diffie-Hellman "p" value.
|
||||
|
||||
=item "q" (B<OSSL_PKEY_PARAM_FFC_Q>) <integer>
|
||||
|
||||
A DSA or Diffie-Hellman "q" value.
|
||||
|
||||
=item "g" (B<OSSL_PKEY_PARAM_FFC_G>) <integer>
|
||||
|
||||
A DSA or Diffie-Hellman "g" value.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Built-in X25519, X448, ED25519 and ED448 Import/Export Types
|
||||
|
||||
The following Import/Export types are available for the built-in X25519, X448,
|
||||
ED25519 and X448 algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
|
||||
|
||||
The public key value.
|
||||
|
||||
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
|
||||
|
||||
The private key value.
|
||||
|
||||
=back
|
||||
|
||||
=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_params:
|
||||
Parameters currently recognised by built-in keymgmt algorithms
|
||||
are as follows.
|
||||
Not all parameters are relevant to, or are understood by all keymgmt
|
||||
algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
@@ -278,8 +389,46 @@ dimensions handled in the rest of the same provider.
|
||||
The value should be the number of security bits of the given key.
|
||||
Bits of security is defined in SP800-57.
|
||||
|
||||
=item "use-cofactor-flag" (B<OSSL_PKEY_PARAM_USE_COFACTOR_FLAG>,
|
||||
B<OSSL_PKEY_PARAM_USE_COFACTOR_ECDH>) <integer>
|
||||
|
||||
The value should be either 1 or 0, to respectively enable or disable
|
||||
use of the cofactor in operations using this key.
|
||||
|
||||
In the context of a key that can be used to perform an Elliptic Curve
|
||||
Diffie-Hellman key exchange, this parameter can be used to mark a requirement
|
||||
for using the Cofactor Diffie-Hellman (CDH) variant of the key exchange
|
||||
algorithm.
|
||||
|
||||
See also L<provider-keyexch(7)> for the related
|
||||
B<OSSL_EXCHANGE_PARAM_EC_ECDH_COFACTOR_MODE> parameter that can be set on a
|
||||
per-operation basis.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OP_keymgmt_new() should return a valid reference to the newly created provider
|
||||
side key object, or NULL on failure.
|
||||
|
||||
OP_keymgmt_import(), OP_keymgmt_export(), OP_keymgmt_get_params() and
|
||||
OP_keymgmt_set_params() should return 1 for success or 0 on error.
|
||||
|
||||
OP_keymgmt_validate() should return 1 on successful validation, or 0 on
|
||||
failure.
|
||||
|
||||
OP_keymgmt_has() should return 1 if all the selected data subsets are contained
|
||||
in the given I<keydata> or 0 otherwise.
|
||||
|
||||
OP_keymgmt_query_operation_name() should return a pointer to a string matching
|
||||
the requested operation, or NULL if the same name used to fetch the keymgmt
|
||||
applies.
|
||||
|
||||
OP_keymgmt_gettable_params() and OP_keymgmt_settable_params()
|
||||
OP_keymgmt_import_types(), OP_keymgmt_export_types()
|
||||
should
|
||||
always return a constant B<OSSL_PARAM> array.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<provider(7)>
|
||||
|
||||
Reference in New Issue
Block a user