[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_provider,
EVP_KEYMGMT_is_a,
EVP_KEYMGMT_number,
EVP_KEYMGMT_get0_first_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_provider(const EVP_KEYMGMT *keymgmt);
 int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
 int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
 const char *EVP_KEYMGMT_get0_first_name(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_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_number() returns the internal dynamic number assigned to
the I<keymgmt>.

EVP_KEYMGMT_get0_first_name() returns the first algorithm name that is found for
the given I<keymgmt>. Note that the I<keymgmt> may have multiple synonyms
associated with it. In this case it is undefined which one will be 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_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_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_number() returns an integer.

EVP_KEYMGMT_get0_first_name() returns the name that is found or NULL on error.

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-2021 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,
251e610c RL	9	EVP_KEYMGMT_provider,
251e610c RL	10	EVP_KEYMGMT_is_a,
506cb0f6	11	EVP_KEYMGMT_number,
3f96b687	12	EVP_KEYMGMT_get0_first_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);
	30	const OSSL_PROVIDER EVP_KEYMGMT_provider(const EVP_KEYMGMT keymgmt);
251e610c	31	int EVP_KEYMGMT_is_a(const EVP_KEYMGMT keymgmt, const char name);
506cb0f6	32	int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
3f96b687 MC	33	const char EVP_KEYMGMT_get0_first_name(const EVP_KEYMGMT keymgmt);
3f96b687 MC	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
	66	EVP_KEYMGMT_provider() returns the provider that has this particular
	67	implementation.
	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
506cb0f6 RL	72	EVP_KEYMGMT_number() returns the internal dynamic number assigned to
	73	the I<keymgmt>.
	74
3f96b687 MC	75	EVP_KEYMGMT_get0_first_name() returns the first algorithm name that is found for
	76	the given I<keymgmt>. Note that the I<keymgmt> may have multiple synonyms
	77	associated with it. In this case it is undefined which one will be returned.
	78	Ownership of the returned string is retained by the I<keymgmt> object and should
	79	not be freed by the caller.
	80
f651c727 RL	81	EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
	82	calls I<fn> with each name and I<data>.
	83
251e610c RL	84	EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
	85	all activated providers in the library context I<libctx>, and for each
	86	of the implementations, calls I<fn> with the implementation method and
	87	I<data> as arguments.
	88
e3efe7a5 SL	89	EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a
	90	constant B<OSSL_PARAM> array that describes the names and types of key
	91	parameters that can be retrieved or set.
	92	EVP_KEYMGMT_gettable_params() is used by L<EVP_PKEY_gettable_params(3)>.
	93	See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
	94
	95	EVP_KEYMGMT_gen_settable_params() returns a constant B<OSSL_PARAM> array that
	96	describes the names and types of key generation parameters that can be set via
	97	L<EVP_PKEY_CTX_set_params(3)>.
	98
a94a3e0d RL	99	=head1 NOTES
	100
	101	EVP_KEYMGMT_fetch() may be called implicitly by other fetching
	102	functions, using the same library context and properties.
	103	Any other API that uses keys will typically do this.
	104
	105	=head1 RETURN VALUES
	106
	107	EVP_KEYMGMT_fetch() returns a pointer to the key management
	108	implementation represented by an EVP_KEYMGMT object, or NULL on
	109	error.
	110
	111	EVP_KEYMGMT_up_ref() returns 1 on success, or 0 on error.
	112
d84f5515 MC	113	EVP_KEYMGMT_names_do_all() returns 1 if the callback was called for all
	114	names. A return value of 0 means that the callback was not called for any names.
	115
a94a3e0d RL	116	EVP_KEYMGMT_free() doesn't return any value.
	117
	118	EVP_KEYMGMT_provider() returns a pointer to a provider object, or NULL
	119	on error.
	120
251e610c RL	121	EVP_KEYMGMT_is_a() returns 1 of I<keymgmt> was identifiable,
	122	otherwise 0.
	123
506cb0f6 RL	124	EVP_KEYMGMT_number() returns an integer.
506cb0f6 RL	125
3f96b687 MC	126	EVP_KEYMGMT_get0_first_name() returns the name that is found or NULL on error.
3f96b687 MC	127
e3efe7a5 SL	128	EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
	129	EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
	130	NULL on error.
	131
a94a3e0d RL	132	=head1 SEE ALSO
a94a3e0d RL	133
b4250010	134	L<EVP_MD_fetch(3)>, L<OSSL_LIB_CTX(3)>
a94a3e0d RL	135
	136	=head1 HISTORY
	137
	138	The functions described here were added in OpenSSL 3.0.
	139
	140	=head1 COPYRIGHT
	141
8020d79b	142	Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
a94a3e0d RL	143
	144	Licensed under the Apache License 2.0 (the "License"). You may not use
	145	this file except in compliance with the License. You can obtain a copy
	146	in the file LICENSE in the source distribution or at
	147	L<https://www.openssl.org/source/license.html>.
	148
	149	=cut