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

=pod

=head1 NAME

EVP_MD_meth_dup,
EVP_MD_meth_new, 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, EVP_MD_up_ref
- Routines to build up 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);

 int EVP_MD_up_ref(EVP_MD *md);

=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. Note that 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.

EVP_MD_up_ref() increments the reference count for an EVP_MD structure.

=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.

EVP_MD_up_ref() returns 1 for success or 0 otherwise.

=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.  EVP_MD_up_ref() was added in OpenSSL 3.0. All other functions described
here were added in OpenSSL 1.1.

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