[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_CTX_md_data
- 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));
 void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
 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.

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

EVP_MD_meth_free() destroys a B<EVP_MD> structure.

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 handles one block of input.

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

=back

EVP_MD_meth_set_init() sets the digest init function for B<md>.
The digest init function is called by 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_DigestUpdate(),
EVP_SignUpdate().

EVP_MD_meth_set_final() sets the digest final function for B<md>.
The digest final function is called by 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>.


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 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 version 1.1.

=head1 COPYRIGHT

Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (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,
c952780c RS	14	EVP_MD_meth_get_ctrl, EVP_MD_CTX_md_data
c952780c RS	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));
c952780c	37	void EVP_MD_CTX_md_data(const EVP_MD_CTX ctx);
706e2462 RL	38	int EVP_MD_meth_set_cleanup(EVP_MD md, int (cleanup)(EVP_MD_CTX *ctx));
	39	int EVP_MD_meth_set_ctrl(EVP_MD md, int (ctrl)(EVP_MD_CTX *ctx, int cmd,
	40	int p1, void *p2));
	41
	42	int EVP_MD_meth_get_input_blocksize(const EVP_MD *md);
	43	int EVP_MD_meth_get_result_size(const EVP_MD *md);
	44	int EVP_MD_meth_get_app_datasize(const EVP_MD *md);
	45	unsigned long EVP_MD_meth_get_flags(const EVP_MD *md);
	46	int (EVP_MD_meth_get_init(const EVP_MD md))(EVP_MD_CTX *ctx);
	47	int (EVP_MD_meth_get_update(const EVP_MD md))(EVP_MD_CTX *ctx,
	48	const void *data,
	49	size_t count);
	50	int (EVP_MD_meth_get_final(const EVP_MD md))(EVP_MD_CTX *ctx,
	51	unsigned char *md);
	52	int (EVP_MD_meth_get_copy(const EVP_MD md))(EVP_MD_CTX *to,
	53	const EVP_MD_CTX *from);
	54	int (EVP_MD_meth_get_cleanup(const EVP_MD md))(EVP_MD_CTX *ctx);
	55	int (EVP_MD_meth_get_ctrl(const EVP_MD md))(EVP_MD_CTX *ctx, int cmd,
	56	int p1, void *p2);
	57
	58	=head1 DESCRIPTION
	59
	60	The B<EVP_MD> type is a structure for digest method implementation.
	61	It can also have associated public/private key signing and verifying
	62	routines.
	63
	64	EVP_MD_meth_new() creates a new B<EVP_MD> structure.
	65
	66	EVP_MD_meth_dup() creates a copy of B<md>.
	67
	68	EVP_MD_meth_free() destroys a B<EVP_MD> structure.
	69
	70	EVP_MD_meth_set_input_blocksize() sets the internal input block size
	71	for the method B<md> to B<blocksize> bytes.
	72
	73	EVP_MD_meth_set_result_size() sets the size of the result that the
	74	digest method in B<md> is expected to produce to B<resultsize> bytes.
	75
	76	The digest method may have its own private data, which OpenSSL will
	77	allocate for it. EVP_MD_meth_set_app_datasize() should be used to
	78	set the size for it to B<datasize>.
	79
	80	EVP_MD_meth_set_flags() sets the flags to describe optional
	81	behaviours in the particular B<md>. Several flags can be or'd
	82	together. The available flags are:
	83
	84	=over 4
	85
	86	=item EVP_MD_FLAG_ONESHOT
	87
	88	This digest method can only handles one block of input.
	89
	90	=item EVP_MD_FLAG_DIGALGID_NULL
	91
	92	When setting up a DigestAlgorithmIdentifier, this flag will have the
	93	parameter set to NULL by default. Use this for PKCS#1. I<Note: if
	94	combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
	95
	96	=item EVP_MD_FLAG_DIGALGID_ABSENT
	97
	98	When setting up a DigestAlgorithmIdentifier, this flag will have the
	99	parameter be left absent by default. I<Note: if combined with
b9b6a7e5	100	EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
706e2462 RL	101
	102	=item EVP_MD_FLAG_DIGALGID_CUSTOM
	103
	104	Custom DigestAlgorithmIdentifier handling via ctrl, with
	105	B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
b9b6a7e5	106	EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
706e2462 RL	107	Currently unused.
	108
	109	=back
	110
	111	EVP_MD_meth_set_init() sets the digest init function for B<md>.
	112	The digest init function is called by EVP_DigestInit(),
	113	EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit()
	114	and EVP_VerifyInit_ex().
	115
	116	EVP_MD_meth_set_update() sets the digest update function for B<md>.
	117	The digest update function is called by EVP_DigestUpdate(),
	118	EVP_SignUpdate().
	119
	120	EVP_MD_meth_set_final() sets the digest final function for B<md>.
	121	The digest final function is called by EVP_DigestFinal(),
	122	EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal().
	123
	124	EVP_MD_meth_set_copy() sets the function for B<md> to do extra
	125	computations after the method's private data structure has been copied
	126	from one B<EVP_MD_CTX> to another. If all that's needed is to copy
	127	the data, there is no need for this copy function.
	128	Note that the copy function is passed two B<EVP_MD_CTX *>, the private
	129	data structure is then available with EVP_MD_CTX_md_data().
	130	This copy function is called by EVP_MD_CTX_copy() and
	131	EVP_MD_CTX_copy_ex().
	132
	133	EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra
9d22666e	134	cleanup before the method's private data structure is cleaned out and
706e2462 RL	135	freed.
	136	Note that the cleanup function is passed a B<EVP_MD_CTX *>, the
	137	private data structure is then available with EVP_MD_CTX_md_data().
	138	This cleanup function is called by EVP_MD_CTX_reset() and
	139	EVP_MD_CTX_free().
	140
	141	EVP_MD_meth_set_ctrl() sets the control function for B<md>.
	142
	143
	144	EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(),
	145	EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(),
	146	EVP_MD_meth_get_init(), EVP_MD_meth_get_update(),
	147	EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(),
	148	EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
	149	to retrieve the method data given with the EVP_MD_meth_set_*()
	150	functions above.
	151
	152	=head1 SEE ALSO
	153
	154	L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
	155
	156	=head1 HISTORY
	157
	158	The B<EVP_MD> structure was openly available in OpenSSL before version
	159	1.1. The functions described here were added in OpenSSL version 1.1.
	160
e2f92610 RS	161	=head1 COPYRIGHT
	162
	163	Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
	164
	165	Licensed under the OpenSSL license (the "License"). You may not use
	166	this file except in compliance with the License. You can obtain a copy
	167	in the file LICENSE in the source distribution or at
	168	L<https://www.openssl.org/source/license.html>.
	169
	170	=cut