[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>

 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

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

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