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

=pod

=head1 NAME

EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free,
EVP_MD_meth_set_input_blocksize,
EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
EVP_MD_meth_get_ctrl
- Routines to build up legacy EVP_MD methods

=head1 SYNOPSIS

 #include <openssl/evp.h>

Deprecated since OpenSSL 3.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:

 EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);
 void EVP_MD_meth_free(EVP_MD *md);
 EVP_MD *EVP_MD_meth_dup(const EVP_MD *md);

 int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);
 int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);
 int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);
 int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);
 int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx));
 int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx,
                                                      const void *data,
                                                      size_t count));
 int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx,
                                                    unsigned char *md));
 int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to,
                                                  const EVP_MD_CTX *from));
 int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx));
 int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd,
                                                  int p1, void *p2));

 int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
 int EVP_MD_meth_get_result_size(const EVP_MD *md);
 int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
 unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
 int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx);
 int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx,
                                                 const void *data,
                                                 size_t count);
 int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx,
                                                unsigned char *md);
 int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to,
                                               const EVP_MD_CTX *from);
 int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx);
 int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
                                               int p1, void *p2);

=head1 DESCRIPTION

All of the functions described on this page are deprecated.
Applications should instead use the OSSL_PROVIDER APIs.

The B<EVP_MD> type is a structure for digest method implementation.
It can also have associated public/private key signing and verifying
routines.

EVP_MD_meth_new() creates a new B<EVP_MD> structure.
These B<EVP_MD> structures are reference counted.

EVP_MD_meth_dup() creates a copy of B<md>.

EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
If the reference count drops to 0 then the structure is freed.

EVP_MD_meth_set_input_blocksize() sets the internal input block size
for the method B<md> to B<blocksize> bytes.

EVP_MD_meth_set_result_size() sets the size of the result that the
digest method in B<md> is expected to produce to B<resultsize> bytes.

The digest method may have its own private data, which OpenSSL will
allocate for it.  EVP_MD_meth_set_app_datasize() should be used to
set the size for it to B<datasize>.

EVP_MD_meth_set_flags() sets the flags to describe optional
behaviours in the particular B<md>.  Several flags can be or'd
together.  The available flags are:

=over 4

=item EVP_MD_FLAG_ONESHOT

This digest method can only handle one block of input.

=item EVP_MD_FLAG_XOF

This digest method is an extensible-output function (XOF) and supports
the B<EVP_MD_CTRL_XOF_LEN> control.

=item EVP_MD_FLAG_DIGALGID_NULL

When setting up a DigestAlgorithmIdentifier, this flag will have the
parameter set to NULL by default.  Use this for PKCS#1.  I<Note: if
combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>

=item EVP_MD_FLAG_DIGALGID_ABSENT

When setting up a DigestAlgorithmIdentifier, this flag will have the
parameter be left absent by default.  I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>

=item EVP_MD_FLAG_DIGALGID_CUSTOM

Custom DigestAlgorithmIdentifier handling via ctrl, with
B<EVP_MD_FLAG_DIGALGID_ABSENT> as default.  I<Note: if combined with
EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
Currently unused.

=item EVP_MD_FLAG_FIPS

This digest method is suitable for use in FIPS mode.
Currently unused.

=back

EVP_MD_meth_set_init() sets the digest init function for B<md>.
The digest init function is called by EVP_Digest(), EVP_DigestInit(),
EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
and EVP_VerifyInit_ex().

EVP_MD_meth_set_update() sets the digest update function for B<md>.
The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and
EVP_SignUpdate().

EVP_MD_meth_set_final() sets the digest final function for B<md>.
The digest final function is called by EVP_Digest(), EVP_DigestFinal(),
EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().

EVP_MD_meth_set_copy() sets the function for B<md> to do extra
computations after the method's private data structure has been copied
from one B<EVP_MD_CTX> to another.  If all that's needed is to copy
the data, there is no need for this copy function.
Note that the copy function is passed two B<EVP_MD_CTX *>, the private
data structure is then available with EVP_MD_CTX_md_data().
This copy function is called by EVP_MD_CTX_copy() and
EVP_MD_CTX_copy_ex().

EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
cleanup before the method's private data structure is cleaned out and
freed.
Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
private data structure is then available with EVP_MD_CTX_md_data().
This cleanup function is called by EVP_MD_CTX_reset() and
EVP_MD_CTX_free().

EVP_MD_meth_set_ctrl() sets the control function for B<md>.
See L<EVP_MD_CTX_ctrl(3)> for the available controls.

EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
to retrieve the method data given with the EVP_MD_meth_set_*()
functions above.

=head1 RETURN VALUES

EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
created B<EVP_MD>, or NULL on failure.
All EVP_MD_meth_set_*() functions return 1.
EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(),
EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the
indicated sizes or flags.
All other EVP_CIPHER_meth_get_*() functions return pointers to their
respective B<md> function.

=head1 SEE ALSO

L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>

=head1 HISTORY

All of these functions were deprecated in OpenSSL 3.0.

The B<EVP_MD> structure was openly available in OpenSSL before version
1.1.
The functions described here were added in OpenSSL 1.1.
The B<EVP_MD> structure created with these functions became reference
counted in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2015-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
706e2462 RL	1	=pod
	2
	3	=head1 NAME
	4
3fd70262 RL	5	EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free,
3fd70262 RL	6	EVP_MD_meth_set_input_blocksize,
706e2462 RL	7	EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize,
	8	EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update,
	9	EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup,
	10	EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
	11	EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
	12	EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
	13	EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
3fd70262 RL	14	EVP_MD_meth_get_ctrl
3fd70262 RL	15	- Routines to build up legacy EVP_MD methods
706e2462 RL	16
	17	=head1 SYNOPSIS
	18
	19	#include <openssl/evp.h>
	20
41bbba53 P	21	Deprecated since OpenSSL 3.0, can be hidden entirely by defining
	22	B<OPENSSL_API_COMPAT> with a suitable version value, see
	23	L<openssl_user_macros(7)>:
	24
6d6e8070	25	EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type);
6d6e8070	26	void EVP_MD_meth_free(EVP_MD *md);
c952780c	27	EVP_MD EVP_MD_meth_dup(const EVP_MD md);
706e2462 RL	28
	29	int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize);
	30	int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize);
	31	int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize);
	32	int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags);
	33	int EVP_MD_meth_set_init(EVP_MD md, int (init)(EVP_MD_CTX *ctx));
	34	int EVP_MD_meth_set_update(EVP_MD md, int (update)(EVP_MD_CTX *ctx,
	35	const void *data,
	36	size_t count));
	37	int EVP_MD_meth_set_final(EVP_MD md, int (final)(EVP_MD_CTX *ctx,
	38	unsigned char *md));
	39	int EVP_MD_meth_set_copy(EVP_MD md, int (copy)(EVP_MD_CTX *to,
	40	const EVP_MD_CTX *from));
	41	int EVP_MD_meth_set_cleanup(EVP_MD md, int (cleanup)(EVP_MD_CTX *ctx));
	42	int EVP_MD_meth_set_ctrl(EVP_MD md, int (ctrl)(EVP_MD_CTX *ctx, int cmd,
	43	int p1, void *p2));
	44
	45	int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
	46	int EVP_MD_meth_get_result_size(const EVP_MD *md);
	47	int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
	48	unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
	49	int (EVP_MD_meth_get_init(const EVP_MD md))(EVP_MD_CTX *ctx);
	50	int (EVP_MD_meth_get_update(const EVP_MD md))(EVP_MD_CTX *ctx,
	51	const void *data,
	52	size_t count);
	53	int (EVP_MD_meth_get_final(const EVP_MD md))(EVP_MD_CTX *ctx,
	54	unsigned char *md);
	55	int (EVP_MD_meth_get_copy(const EVP_MD md))(EVP_MD_CTX *to,
	56	const EVP_MD_CTX *from);
	57	int (EVP_MD_meth_get_cleanup(const EVP_MD md))(EVP_MD_CTX *ctx);
	58	int (EVP_MD_meth_get_ctrl(const EVP_MD md))(EVP_MD_CTX *ctx, int cmd,
	59	int p1, void *p2);
	60
	61	=head1 DESCRIPTION
	62
41bbba53 P	63	All of the functions described on this page are deprecated.
	64	Applications should instead use the OSSL_PROVIDER APIs.
	65
706e2462 RL	66	The B<EVP_MD> type is a structure for digest method implementation.
	67	It can also have associated public/private key signing and verifying
	68	routines.
	69
3fd70262 RL	70	EVP_MD_meth_new() creates a new B<EVP_MD> structure.
3fd70262 RL	71	These B<EVP_MD> structures are reference counted.
706e2462 RL	72
	73	EVP_MD_meth_dup() creates a copy of B<md>.
	74
fdf6c0b6 MC	75	EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
fdf6c0b6 MC	76	If the reference count drops to 0 then the structure is freed.
706e2462 RL	77
	78	EVP_MD_meth_set_input_blocksize() sets the internal input block size
	79	for the method B<md> to B<blocksize> bytes.
	80
	81	EVP_MD_meth_set_result_size() sets the size of the result that the
	82	digest method in B<md> is expected to produce to B<resultsize> bytes.
	83
	84	The digest method may have its own private data, which OpenSSL will
	85	allocate for it. EVP_MD_meth_set_app_datasize() should be used to
	86	set the size for it to B<datasize>.
	87
	88	EVP_MD_meth_set_flags() sets the flags to describe optional
	89	behaviours in the particular B<md>. Several flags can be or'd
	90	together. The available flags are:
	91
	92	=over 4
	93
	94	=item EVP_MD_FLAG_ONESHOT
	95
37842dfa AS	96	This digest method can only handle one block of input.
	97
	98	=item EVP_MD_FLAG_XOF
	99
	100	This digest method is an extensible-output function (XOF) and supports
	101	the B<EVP_MD_CTRL_XOF_LEN> control.
706e2462 RL	102
	103	=item EVP_MD_FLAG_DIGALGID_NULL
	104
	105	When setting up a DigestAlgorithmIdentifier, this flag will have the
	106	parameter set to NULL by default. Use this for PKCS#1. I<Note: if
	107	combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
	108
	109	=item EVP_MD_FLAG_DIGALGID_ABSENT
	110
	111	When setting up a DigestAlgorithmIdentifier, this flag will have the
	112	parameter be left absent by default. I<Note: if combined with
b9b6a7e5	113	EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
706e2462 RL	114
	115	=item EVP_MD_FLAG_DIGALGID_CUSTOM
	116
	117	Custom DigestAlgorithmIdentifier handling via ctrl, with
	118	B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
b9b6a7e5	119	EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
706e2462 RL	120	Currently unused.
706e2462 RL	121
37842dfa AS	122	=item EVP_MD_FLAG_FIPS
	123
	124	This digest method is suitable for use in FIPS mode.
	125	Currently unused.
	126
706e2462 RL	127	=back
	128
	129	EVP_MD_meth_set_init() sets the digest init function for B<md>.
37842dfa	130	The digest init function is called by EVP_Digest(), EVP_DigestInit(),
706e2462 RL	131	EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
	132	and EVP_VerifyInit_ex().
	133
	134	EVP_MD_meth_set_update() sets the digest update function for B<md>.
37842dfa	135	The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and
706e2462 RL	136	EVP_SignUpdate().
	137
	138	EVP_MD_meth_set_final() sets the digest final function for B<md>.
37842dfa	139	The digest final function is called by EVP_Digest(), EVP_DigestFinal(),
706e2462 RL	140	EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
	141
	142	EVP_MD_meth_set_copy() sets the function for B<md> to do extra
	143	computations after the method's private data structure has been copied
	144	from one B<EVP_MD_CTX> to another. If all that's needed is to copy
	145	the data, there is no need for this copy function.
	146	Note that the copy function is passed two B<EVP_MD_CTX *>, the private
	147	data structure is then available with EVP_MD_CTX_md_data().
	148	This copy function is called by EVP_MD_CTX_copy() and
	149	EVP_MD_CTX_copy_ex().
	150
	151	EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
9d22666e	152	cleanup before the method's private data structure is cleaned out and
706e2462 RL	153	freed.
	154	Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
	155	private data structure is then available with EVP_MD_CTX_md_data().
	156	This cleanup function is called by EVP_MD_CTX_reset() and
	157	EVP_MD_CTX_free().
	158
	159	EVP_MD_meth_set_ctrl() sets the control function for B<md>.
37842dfa	160	See L<EVP_MD_CTX_ctrl(3)> for the available controls.
706e2462	161
706e2462 RL	162	EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
	163	EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
	164	EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
	165	EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
	166	EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
	167	to retrieve the method data given with the EVP_MD_meth_set_*()
	168	functions above.
	169
51e47d5f RL	170	=head1 RETURN VALUES
	171
	172	EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
	173	created B<EVP_MD>, or NULL on failure.
	174	All EVP_MD_meth_set_*() functions return 1.
	175	EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(),
	176	EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the
	177	indicated sizes or flags.
	178	All other EVP_CIPHER_meth_get_*() functions return pointers to their
	179	respective B<md> function.
	180
706e2462 RL	181	=head1 SEE ALSO
	182
	183	L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
	184
	185	=head1 HISTORY
	186
41bbba53 P	187	All of these functions were deprecated in OpenSSL 3.0.
41bbba53 P	188
706e2462	189	The B<EVP_MD> structure was openly available in OpenSSL before version
3fd70262 RL	190	1.1.
	191	The functions described here were added in OpenSSL 1.1.
	192	The B<EVP_MD> structure created with these functions became reference
	193	counted in OpenSSL 3.0.
706e2462	194
e2f92610 RS	195	=head1 COPYRIGHT
e2f92610 RS	196
0f84cbc3	197	Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	198
4746f25a	199	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	200	this file except in compliance with the License. You can obtain a copy
	201	in the file LICENSE in the source distribution or at
	202	L<https://www.openssl.org/source/license.html>.
	203
	204	=cut