[thirdparty/openssl.git] / doc / man3 / EVP_KEYMGMT.pod

=pod

=head1 NAME

EVP_KEYMGMT,
EVP_KEYMGMT_fetch,
EVP_KEYMGMT_up_ref,
EVP_KEYMGMT_free,
EVP_KEYMGMT_get0_provider,
EVP_KEYMGMT_is_a,
EVP_KEYMGMT_get0_description,
EVP_KEYMGMT_get0_name,
EVP_KEYMGMT_do_all_provided,
EVP_KEYMGMT_names_do_all,
EVP_KEYMGMT_gettable_params,
EVP_KEYMGMT_settable_params,
EVP_KEYMGMT_gen_settable_params
- EVP key management routines

=head1 SYNOPSIS

 #include <openssl/evp.h>

 typedef struct evp_keymgmt_st EVP_KEYMGMT;

 EVP_KEYMGMT *EVP_KEYMGMT_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                                const char *properties);
 int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
 void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
 const OSSL_PROVIDER *EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT *keymgmt);
 int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
 const char *EVP_KEYMGMT_get0_name(const EVP_KEYMGMT *keymgmt);
 const char *EVP_KEYMGMT_get0_description(const EVP_KEYMGMT *keymgmt);

 void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
                                  void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
                                  void *arg);
 int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
                              void (*fn)(const char *name, void *data),
                              void *data);
 const OSSL_PARAM *EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT *keymgmt);
 const OSSL_PARAM *EVP_KEYMGMT_settable_params(const EVP_KEYMGMT *keymgmt);
 const OSSL_PARAM *EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT *keymgmt);

=head1 DESCRIPTION

B<EVP_KEYMGMT> is a method object that represents key management
implementations for different cryptographic algorithms.
This method object provides functionality to have providers import key
material from the outside, as well as export key material to the
outside.
Most of the functionality can only be used internally and has no
public interface, this object is simply passed into other functions
when needed.

EVP_KEYMGMT_fetch() looks for an algorithm within the provider that
has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
name given by I<algorithm> and the properties given by I<properties>.

EVP_KEYMGMT_up_ref() increments the reference count for the given
B<EVP_KEYMGMT> I<keymgmt>.

EVP_KEYMGMT_free() decrements the reference count for the given
B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.

EVP_KEYMGMT_get0_provider() returns the provider that has this particular
implementation.

EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an
algorithm that's identifiable with I<name>.

EVP_KEYMGMT_get0_name() returns the algorithm name from the provided
implementation for the given I<keymgmt>. Note that the I<keymgmt> may have
multiple synonyms associated with it. In this case the first name from the
algorithm definition is returned. Ownership of the returned string is
retained by the I<keymgmt> object and should not be freed by the caller.

EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
calls I<fn> with each name and I<data>.

EVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant
for display and human consumption.  The description is at the discretion
of the I<keymgmt> implementation.

EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
all activated providers in the library context I<libctx>, and for each
of the implementations, calls I<fn> with the implementation method and
I<data> as arguments.

EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a
constant B<OSSL_PARAM> array that describes the names and types of key
parameters that can be retrieved or set.
EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>.
See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.

EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that
describes the names and types of key generation parameters that can be set via
L<EVP_PKEY_CTX_set_params(3)>.

=head1 NOTES

EVP_KEYMGMT_fetch() may be called implicitly by other fetching
functions, using the same library context and properties.
Any other API that uses keys will typically do this.

=head1 RETURN VALUES

EVP_KEYMGMT_fetch() returns a pointer to the key management
implementation represented by an EVP_KEYMGMT object, or NULL on
error.

EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.

EVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all
names. A return value of 0 means that the callback was not called for any names.

EVP_KEYMGMT_free() doesn't return any value.

EVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL
on error.

EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
otherwise 0.

EVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error.

EVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if
there isn't one.

EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
NULL on error.

=head1 SEE ALSO

L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>

=head1 HISTORY

The functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019-2022 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
Commit	Line	Data
a94a3e0d RL	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_KEYMGMT,
	6	EVP_KEYMGMT_fetch,
	7	EVP_KEYMGMT_up_ref,
	8	EVP_KEYMGMT_free,
ed576acd	9	EVP_KEYMGMT_get0_provider,
251e610c	10	EVP_KEYMGMT_is_a,
ed576acd TM	11	EVP_KEYMGMT_get0_description,
ed576acd TM	12	EVP_KEYMGMT_get0_name,
251e610c	13	EVP_KEYMGMT_do_all_provided,
e3efe7a5 SL	14	EVP_KEYMGMT_names_do_all,
	15	EVP_KEYMGMT_gettable_params,
	16	EVP_KEYMGMT_settable_params,
	17	EVP_KEYMGMT_gen_settable_params
a94a3e0d RL	18	- EVP key management routines
	19
	20	=head1 SYNOPSIS
	21
	22	#include <openssl/evp.h>
	23
	24	typedef struct evp_keymgmt_st EVP_KEYMGMT;
	25
b4250010	26	EVP_KEYMGMT EVP_KEYMGMT_fetch(OSSL_LIB_CTX ctx, const char *algorithm,
a94a3e0d RL	27	const char *properties);
	28	int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
	29	void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
ed576acd	30	const OSSL_PROVIDER EVP_KEYMGMT_get0_provider(const EVP_KEYMGMT keymgmt);
251e610c	31	int EVP_KEYMGMT_is_a(const EVP_KEYMGMT keymgmt, const char name);
ed576acd TM	32	const char EVP_KEYMGMT_get0_name(const EVP_KEYMGMT keymgmt);
ed576acd TM	33	const char EVP_KEYMGMT_get0_description(const EVP_KEYMGMT keymgmt);
3f96b687	34
b4250010	35	void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
251e610c RL	36	void (fn)(EVP_KEYMGMT keymgmt, void *arg),
251e610c RL	37	void *arg);
d84f5515 MC	38	int EVP_KEYMGMT_names_do_all(const EVP_KEYMGMT *keymgmt,
	39	void (fn)(const char name, void *data),
	40	void *data);
e3efe7a5 SL	41	const OSSL_PARAM EVP_KEYMGMT_gettable_params(const EVP_KEYMGMT keymgmt);
	42	const OSSL_PARAM EVP_KEYMGMT_settable_params(const EVP_KEYMGMT keymgmt);
	43	const OSSL_PARAM EVP_KEYMGMT_gen_settable_params(const EVP_KEYMGMT keymgmt);
a94a3e0d RL	44
	45	=head1 DESCRIPTION
	46
	47	B<EVP_KEYMGMT> is a method object that represents key management
	48	implementations for different cryptographic algorithms.
	49	This method object provides functionality to have providers import key
	50	material from the outside, as well as export key material to the
	51	outside.
	52	Most of the functionality can only be used internally and has no
	53	public interface, this object is simply passed into other functions
	54	when needed.
	55
	56	EVP_KEYMGMT_fetch() looks for an algorithm within the provider that
b4250010	57	has been loaded into the B<OSSL_LIB_CTX> given by I<ctx>, having the
a94a3e0d RL	58	name given by I<algorithm> and the properties given by I<properties>.
	59
	60	EVP_KEYMGMT_up_ref() increments the reference count for the given
	61	B<EVP_KEYMGMT> I<keymgmt>.
	62
	63	EVP_KEYMGMT_free() decrements the reference count for the given
	64	B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
	65
ed576acd	66	EVP_KEYMGMT_get0_provider() returns the provider that has this particular
a94a3e0d RL	67	implementation.
a94a3e0d RL	68
251e610c RL	69	EVP_KEYMGMT_is_a() checks if I<keymgmt> is an implementation of an
	70	algorithm that's identifiable with I<name>.
	71
ed576acd TM	72	EVP_KEYMGMT_get0_name() returns the algorithm name from the provided
	73	implementation for the given I<keymgmt>. Note that the I<keymgmt> may have
	74	multiple synonyms associated with it. In this case the first name from the
	75	algorithm definition is returned. Ownership of the returned string is
	76	retained by the I<keymgmt> object and should not be freed by the caller.
3f96b687	77
f651c727 RL	78	EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
	79	calls I<fn> with each name and I<data>.
	80
ed576acd TM	81	EVP_KEYMGMT_get0_description() returns a description of the I<keymgmt>, meant
	82	for display and human consumption. The description is at the discretion
	83	of the I<keymgmt> implementation.
03888233	84
251e610c RL	85	EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
	86	all activated providers in the library context I<libctx>, and for each
	87	of the implementations, calls I<fn> with the implementation method and
	88	I<data> as arguments.
	89
e3efe7a5 SL	90	EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a
	91	constant B<OSSL_PARAM> array that describes the names and types of key
	92	parameters that can be retrieved or set.
	93	EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>.
	94	See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
	95
	96	EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that
	97	describes the names and types of key generation parameters that can be set via
	98	L<EVP_PKEY_CTX_set_params(3)>.
	99
a94a3e0d RL	100	=head1 NOTES
	101
	102	EVP_KEYMGMT_fetch() may be called implicitly by other fetching
	103	functions, using the same library context and properties.
	104	Any other API that uses keys will typically do this.
	105
	106	=head1 RETURN VALUES
	107
	108	EVP_KEYMGMT_fetch() returns a pointer to the key management
	109	implementation represented by an EVP_KEYMGMT object, or NULL on
	110	error.
	111
	112	EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.
	113
d84f5515 MC	114	EVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all
	115	names. A return value of 0 means that the callback was not called for any names.
	116
a94a3e0d RL	117	EVP_KEYMGMT_free() doesn't return any value.
a94a3e0d RL	118
ed576acd	119	EVP_KEYMGMT_get0_provider() returns a pointer to a provider object, or NULL
a94a3e0d RL	120	on error.
a94a3e0d RL	121
251e610c RL	122	EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
	123	otherwise 0.
	124
ed576acd	125	EVP_KEYMGMT_get0_name() returns the algorithm name, or NULL on error.
3f96b687	126
e304aa87	127	EVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if
03888233 RL	128	there isn't one.
03888233 RL	129
e3efe7a5 SL	130	EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
	131	EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
	132	NULL on error.
	133
a94a3e0d RL	134	=head1 SEE ALSO
a94a3e0d RL	135
b4250010	136	L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>
a94a3e0d RL	137
	138	=head1 HISTORY
	139
	140	The functions described here were added in OpenSSL 3.0.
	141
	142	=head1 COPYRIGHT
	143
fecb3aae	144	Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
a94a3e0d RL	145
	146	Licensed under the Apache License 2.0 (the "License"). You may not use
	147	this file except in compliance with the License. You can obtain a copy
	148	in the file LICENSE in the source distribution or at
	149	L<https://www.openssl.org/source/license.html>.
	150
	151	=cut