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

=pod

=head1 NAME

EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
EVP_SIGNATURE_number, EVP_SIGNATURE_is_a, EVP_SIGNATURE_provider,
EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all,
EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params
- Functions to manage EVP_SIGNATURE algorithm objects

=head1 SYNOPSIS

 #include <openssl/evp.h>

 EVP_SIGNATURE *EVP_SIGNATURE_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                                    const char *properties);
 void EVP_SIGNATURE_free(EVP_SIGNATURE *signature);
 int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);
 int EVP_SIGNATURE_number(const EVP_SIGNATURE *signature);
 int EVP_SIGNATURE_is_a(const EVP_SIGNATURE *signature, const char *name);
 OSSL_PROVIDER *EVP_SIGNATURE_provider(const EVP_SIGNATURE *signature);
 void EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx,
                                    void (*fn)(EVP_SIGNATURE *signature,
                                               void *arg),
                                    void *arg);
 int EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature,
                                void (*fn)(const char *name, void *data),
                                void *data);
 const OSSL_PARAM *EVP_SIGNATURE_gettable_ctx_params(const EVP_SIGNATURE *sig);
 const OSSL_PARAM *EVP_SIGNATURE_settable_ctx_params(const EVP_SIGNATURE *sig);

=head1 DESCRIPTION

EVP_SIGNATURE_fetch() fetches the implementation for the given
B<algorithm> from any provider offering it, within the criteria given
by the B<properties>.
The algorithm will be one offering functions for performing signature related
tasks such as signing and verifying.
See L<provider(7)/Fetching algorithms> for further information.

The returned value must eventually be freed with EVP_SIGNATURE_free().

EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE>
structure. Typically this structure will have been obtained from an earlier call
to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the
structure is freed.

EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
structure.

EVP_SIGNATURE_is_a() returns 1 if I<signature> is an implementation of an
algorithm that's identifiable with I<name>, otherwise 0.

EVP_SIGNATURE_provider() returns the provider that I<signature> was fetched from.

EVP_SIGNATURE_do_all_provided() traverses all SIGNATURE implemented by all
activated roviders in the given library context I<libctx>, and for each of the
implementations, calls the given function I<fn> with the implementation method
and the given I<arg> as argument.

EVP_SIGNATURE_number() returns the internal dynamic number assigned to
I<signature>.

EVP_SIGNATURE_names_do_all() traverses all names for I<signature>, and calls
I<fn> with each name and I<data>.

EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params()
return a constant B<OSSL_PARAM> array that describes the names and types of key
parameters that can be retrieved or set by a signature algorithm using
L<EVP_PKEY_CTX_get_params(3)> and L<EVP_PKEY_CTX_set_params(3)>.

=head1 RETURN VALUES

EVP_SIGNATURE_fetch() returns a pointer to an B<EVP_SIGNATURE> for success
or B<NULL> for failure.

EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise.

EVP_SIGNATURE_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_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params()
return a constant B<OSSL_PARAM> array or NULL on error.

=head1 SEE ALSO

L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>

=head1 HISTORY

The functions described here were added 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
Commit	Line	Data
11031468 MC	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
506cb0f6	6	EVP_SIGNATURE_number, EVP_SIGNATURE_is_a, EVP_SIGNATURE_provider,
e3efe7a5 SL	7	EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all,
e3efe7a5 SL	8	EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params
11031468 MC	9	- Functions to manage EVP_SIGNATURE algorithm objects
	10
	11	=head1 SYNOPSIS
	12
	13	#include <openssl/evp.h>
	14
b4250010	15	EVP_SIGNATURE EVP_SIGNATURE_fetch(OSSL_LIB_CTX ctx, const char *algorithm,
11031468 MC	16	const char *properties);
	17	void EVP_SIGNATURE_free(EVP_SIGNATURE *signature);
	18	int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);
506cb0f6	19	int EVP_SIGNATURE_number(const EVP_SIGNATURE *signature);
251e610c	20	int EVP_SIGNATURE_is_a(const EVP_SIGNATURE signature, const char name);
11031468	21	OSSL_PROVIDER EVP_SIGNATURE_provider(const EVP_SIGNATURE signature);
b4250010	22	void EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx,
251e610c RL	23	void (fn)(EVP_SIGNATURE signature,
	24	void *arg),
	25	void *arg);
d84f5515 MC	26	int EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature,
	27	void (fn)(const char name, void *data),
	28	void *data);
e3efe7a5 SL	29	const OSSL_PARAM EVP_SIGNATURE_gettable_ctx_params(const EVP_SIGNATURE sig);
e3efe7a5 SL	30	const OSSL_PARAM EVP_SIGNATURE_settable_ctx_params(const EVP_SIGNATURE sig);
11031468 MC	31
	32	=head1 DESCRIPTION
	33
	34	EVP_SIGNATURE_fetch() fetches the implementation for the given
	35	B<algorithm> from any provider offering it, within the criteria given
	36	by the B<properties>.
	37	The algorithm will be one offering functions for performing signature related
	38	tasks such as signing and verifying.
	39	See L<provider(7)/Fetching algorithms> for further information.
	40
	41	The returned value must eventually be freed with EVP_SIGNATURE_free().
	42
	43	EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE>
	44	structure. Typically this structure will have been obtained from an earlier call
	45	to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the
	46	structure is freed.
	47
	48	EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
	49	structure.
	50
251e610c RL	51	EVP_SIGNATURE_is_a() returns 1 if I<signature> is an implementation of an
	52	algorithm that's identifiable with I<name>, otherwise 0.
	53
11031468 MC	54	EVP_SIGNATURE_provider() returns the provider that I<signature> was fetched from.
11031468 MC	55
251e610c RL	56	EVP_SIGNATURE_do_all_provided() traverses all SIGNATURE implemented by all
	57	activated roviders in the given library context I<libctx>, and for each of the
	58	implementations, calls the given function I<fn> with the implementation method
	59	and the given I<arg> as argument.
	60
506cb0f6 RL	61	EVP_SIGNATURE_number() returns the internal dynamic number assigned to
	62	I<signature>.
	63
f651c727 RL	64	EVP_SIGNATURE_names_do_all() traverses all names for I<signature>, and calls
	65	I<fn> with each name and I<data>.
	66
e3efe7a5 SL	67	EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params()
	68	return a constant B<OSSL_PARAM> array that describes the names and types of key
	69	parameters that can be retrieved or set by a signature algorithm using
	70	L<EVP_PKEY_CTX_get_params(3)> and L<EVP_PKEY_CTX_set_params(3)>.
	71
11031468 MC	72	=head1 RETURN VALUES
	73
	74	EVP_SIGNATURE_fetch() returns a pointer to an B<EVP_SIGNATURE> for success
	75	or B<NULL> for failure.
	76
	77	EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise.
	78
d84f5515 MC	79	EVP_SIGNATURE_names_do_all() returns 1 if the callback was called for all names.
	80	A return value of 0 means that the callback was not called for any names.
	81
e3efe7a5 SL	82	EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params()
	83	return a constant B<OSSL_PARAM> array or NULL on error.
	84
11031468 MC	85	=head1 SEE ALSO
	86
	87	L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(3)>
	88
	89	=head1 HISTORY
	90
	91	The functions described here were added in OpenSSL 3.0.
	92
	93	=head1 COPYRIGHT
	94
e3efe7a5	95	Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
11031468 MC	96
	97	Licensed under the Apache License 2.0 (the "License"). You may not use
	98	this file except in compliance with the License. You can obtain a copy
	99	in the file LICENSE in the source distribution or at
	100	L<https://www.openssl.org/source/license.html>.
	101
	102	=cut