From: Dr. Stephen Henson Date: Mon, 2 Oct 2017 22:15:32 +0000 (+0100) Subject: Fix backport by moving file. X-Git-Tag: OpenSSL_1_0_2m~16 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=720aa0f534ffd5d5ace4f24a97aab5c9762e482f;p=oweals%2Fopenssl.git Fix backport by moving file. Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/4453) --- diff --git a/doc/crypto/EVP_PKEY_meth_new.pod b/doc/crypto/EVP_PKEY_meth_new.pod new file mode 100644 index 0000000000..041492a8f0 --- /dev/null +++ b/doc/crypto/EVP_PKEY_meth_new.pod @@ -0,0 +1,376 @@ +=pod + +=head1 NAME + +EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, +EVP_PKEY_meth_add0, EVP_PKEY_METHOD, +EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, +EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, +EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, +EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, +EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, +EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, +EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, +EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, +EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, +EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl +- manipulating EVP_PKEY_METHOD structure + +=head1 SYNOPSIS + + #include + + typedef struct evp_pkey_method_st EVP_PKEY_METHOD; + + EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags); + void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth); + void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src); + const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type); + int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth); + + void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth, + int (*init) (EVP_PKEY_CTX *ctx)); + void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth, + int (*copy) (EVP_PKEY_CTX *dst, + EVP_PKEY_CTX *src)); + void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth, + void (*cleanup) (EVP_PKEY_CTX *ctx)); + void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth, + int (*paramgen_init) (EVP_PKEY_CTX *ctx), + int (*paramgen) (EVP_PKEY_CTX *ctx, + EVP_PKEY *pkey)); + void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth, + int (*keygen_init) (EVP_PKEY_CTX *ctx), + int (*keygen) (EVP_PKEY_CTX *ctx, + EVP_PKEY *pkey)); + void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth, + int (*sign_init) (EVP_PKEY_CTX *ctx), + int (*sign) (EVP_PKEY_CTX *ctx, + unsigned char *sig, size_t *siglen, + const unsigned char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth, + int (*verify_init) (EVP_PKEY_CTX *ctx), + int (*verify) (EVP_PKEY_CTX *ctx, + const unsigned char *sig, + size_t siglen, + const unsigned char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth, + int (*verify_recover_init) (EVP_PKEY_CTX + *ctx), + int (*verify_recover) (EVP_PKEY_CTX + *ctx, + unsigned char + *sig, + size_t *siglen, + const unsigned + char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth, + int (*signctx_init) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx), + int (*signctx) (EVP_PKEY_CTX *ctx, + unsigned char *sig, + size_t *siglen, + EVP_MD_CTX *mctx)); + void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth, + int (*verifyctx_init) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx), + int (*verifyctx) (EVP_PKEY_CTX *ctx, + const unsigned char *sig, + int siglen, + EVP_MD_CTX *mctx)); + void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth, + int (*encrypt_init) (EVP_PKEY_CTX *ctx), + int (*encryptfn) (EVP_PKEY_CTX *ctx, + unsigned char *out, + size_t *outlen, + const unsigned char *in, + size_t inlen)); + void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth, + int (*decrypt_init) (EVP_PKEY_CTX *ctx), + int (*decrypt) (EVP_PKEY_CTX *ctx, + unsigned char *out, + size_t *outlen, + const unsigned char *in, + size_t inlen)); + void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth, + int (*derive_init) (EVP_PKEY_CTX *ctx), + int (*derive) (EVP_PKEY_CTX *ctx, + unsigned char *key, + size_t *keylen)); + void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth, + int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, + void *p2), + int (*ctrl_str) (EVP_PKEY_CTX *ctx, + const char *type, + const char *value)); + + void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth, + int (**pinit) (EVP_PKEY_CTX *ctx)); + void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth, + int (**pcopy) (EVP_PKEY_CTX *dst, + EVP_PKEY_CTX *src)); + void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth, + void (**pcleanup) (EVP_PKEY_CTX *ctx)); + void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth, + int (**pparamgen_init) (EVP_PKEY_CTX *ctx), + int (**pparamgen) (EVP_PKEY_CTX *ctx, + EVP_PKEY *pkey)); + void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth, + int (**pkeygen_init) (EVP_PKEY_CTX *ctx), + int (**pkeygen) (EVP_PKEY_CTX *ctx, + EVP_PKEY *pkey)); + void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth, + int (**psign_init) (EVP_PKEY_CTX *ctx), + int (**psign) (EVP_PKEY_CTX *ctx, + unsigned char *sig, size_t *siglen, + const unsigned char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth, + int (**pverify_init) (EVP_PKEY_CTX *ctx), + int (**pverify) (EVP_PKEY_CTX *ctx, + const unsigned char *sig, + size_t siglen, + const unsigned char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth, + int (**pverify_recover_init) (EVP_PKEY_CTX + *ctx), + int (**pverify_recover) (EVP_PKEY_CTX + *ctx, + unsigned char + *sig, + size_t *siglen, + const unsigned + char *tbs, + size_t tbslen)); + void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth, + int (**psignctx_init) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx), + int (**psignctx) (EVP_PKEY_CTX *ctx, + unsigned char *sig, + size_t *siglen, + EVP_MD_CTX *mctx)); + void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth, + int (**pverifyctx_init) (EVP_PKEY_CTX *ctx, + EVP_MD_CTX *mctx), + int (**pverifyctx) (EVP_PKEY_CTX *ctx, + const unsigned char *sig, + int siglen, + EVP_MD_CTX *mctx)); + void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth, + int (**pencrypt_init) (EVP_PKEY_CTX *ctx), + int (**pencryptfn) (EVP_PKEY_CTX *ctx, + unsigned char *out, + size_t *outlen, + const unsigned char *in, + size_t inlen)); + void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth, + int (**pdecrypt_init) (EVP_PKEY_CTX *ctx), + int (**pdecrypt) (EVP_PKEY_CTX *ctx, + unsigned char *out, + size_t *outlen, + const unsigned char *in, + size_t inlen)); + void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth, + int (**pderive_init) (EVP_PKEY_CTX *ctx), + int (**pderive) (EVP_PKEY_CTX *ctx, + unsigned char *key, + size_t *keylen)); + void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth, + int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1, + void *p2), + int (**pctrl_str) (EVP_PKEY_CTX *ctx, + const char *type, + const char *value)); + +=head1 DESCRIPTION + +B is a structure which holds a set of methods for a +specific public key cryptographic algorithm. Those methods are usually +used to perform different jobs, such as generating a key, signing or +verifying, encrypting or decrypting, etc. + +There are two places where the B objects are stored: one +is a built-in static array representing the standard methods for different +algorithms, and the other one is a stack of user-defined application-specific +methods, which can be manipulated by using L. + +The B objects are usually referenced by B +objects. + +=head2 Methods + +The methods are the underlying implementations of a particular public key +algorithm present by the B object. + + int (*init) (EVP_PKEY_CTX *ctx); + int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src); + void (*cleanup) (EVP_PKEY_CTX *ctx); + +The init() method is called to initialize algorithm-specific data when a new +B is created. As opposed to init(), the cleanup() method is called +when an B is freed. The copy() method is called when an B +is being duplicated. Refer to L, L, +L and L. + + int (*paramgen_init) (EVP_PKEY_CTX *ctx); + int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); + +The paramgen_init() and paramgen() methods deal with key parameter generation. +They are called by L and L to +handle the parameter generation process. + + int (*keygen_init) (EVP_PKEY_CTX *ctx); + int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); + +The keygen_init() and keygen() methods are used to generate the actual key for +the specified algorithm. They are called by L and +L. + + int (*sign_init) (EVP_PKEY_CTX *ctx); + int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, + const unsigned char *tbs, size_t tbslen); + +The sign_init() and sign() methods are used to generate the signature of a +piece of data using a private key. They are called by L +and L. + + int (*verify_init) (EVP_PKEY_CTX *ctx); + int (*verify) (EVP_PKEY_CTX *ctx, + const unsigned char *sig, size_t siglen, + const unsigned char *tbs, size_t tbslen); + +The verify_init() and verify() methods are used to verify whether a signature is +valid. They are called by L and L. + + int (*verify_recover_init) (EVP_PKEY_CTX *ctx); + int (*verify_recover) (EVP_PKEY_CTX *ctx, + unsigned char *rout, size_t *routlen, + const unsigned char *sig, size_t siglen); + +The verify_recover_init() and verify_recover() methods are used to verify a +signature and then recover the digest from the signature (for instance, a +signature that was generated by RSA signing algorithm). They are called by +L and L. + + int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); + int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, + EVP_MD_CTX *mctx); + +The signctx_init() and signctx() methods are used to sign a digest present by +a B object. They are called by the EVP_DigestSign functions. See +L for detail. + + int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); + int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen, + EVP_MD_CTX *mctx); + +The verifyctx_init() and verifyctx() methods are used to verify a signature +against the data in a B object. They are called by the various +EVP_DigestVerify functions. See L for detail. + + int (*encrypt_init) (EVP_PKEY_CTX *ctx); + int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +The encrypt_init() and encrypt() methods are used to encrypt a piece of data. +They are called by L and L. + + int (*decrypt_init) (EVP_PKEY_CTX *ctx); + int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +The decrypt_init() and decrypt() methods are used to decrypt a piece of data. +They are called by L and L. + + int (*derive_init) (EVP_PKEY_CTX *ctx); + int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); + +The derive_init() and derive() methods are used to derive the shared secret +from a public key algorithm (for instance, the DH algorithm). They are called by +L and L. + + int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2); + int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value); + +The ctrl() and ctrl_str() methods are used to adjust algorithm-specific +settings. See L and related functions for detail. + + int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen, + const unsigned char *tbs, size_t tbslen); + int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig, + size_t siglen, const unsigned char *tbs, + size_t tbslen); + +The digestsign() and digestverify() methods are used to generate or verify +a signature in a one-shot mode. They could be called by L +and L. + +=head2 Functions + +EVP_PKEY_meth_new() creates and returns a new B object, +and associates the given B and B. The following flags are +supported: + + EVP_PKEY_FLAG_AUTOARGLEN + EVP_PKEY_FLAG_SIGCTX_CUSTOM + +If an B is set with the B flag, the +maximum size of the output buffer will be automatically calculated or checked +in corresponding EVP methods by the EVP framework. Thus the implementations of +these methods don't need to care about handling the case of returning output +buffer size by themselves. For details on the output buffer size, refer to +L. + +The B is used to indicate the signctx() method +of an B is always called by the EVP framework while doing a +digest signing operation by calling L. + +EVP_PKEY_meth_free() frees an existing B pointed by +B. + +EVP_PKEY_meth_copy() copies an B object from B +to B. + +EVP_PKEY_meth_find() finds an B object with the B. +This function first searches through the user-defined method objects and +then the built-in objects. + +EVP_PKEY_meth_add0() adds B to the user defined stack of methods. + +The EVP_PKEY_meth_set functions set the corresponding fields of +B structure with the arguments passed. + +The EVP_PKEY_meth_get functions get the corresponding fields of +B structure to the arguments provided. + +=head1 RETURN VALUES + +EVP_PKEY_meth_new() returns a pointer to a new B +object or returns NULL on error. + +EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values. + +EVP_PKEY_meth_find() returns a pointer to the found B +object or returns NULL if not found. + +EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0 +if an error occurred. + +All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return +values. For the 'get' functions, function pointers are returned by +arguments. + +=head1 COPYRIGHT + +Copyright 2017 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. + +=cut diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod deleted file mode 100644 index 041492a8f0..0000000000 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ /dev/null @@ -1,376 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, -EVP_PKEY_meth_add0, EVP_PKEY_METHOD, -EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, -EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, -EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, -EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, -EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, -EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, -EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, -EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, -EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, -EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl -- manipulating EVP_PKEY_METHOD structure - -=head1 SYNOPSIS - - #include - - typedef struct evp_pkey_method_st EVP_PKEY_METHOD; - - EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags); - void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth); - void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src); - const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type); - int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth); - - void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth, - int (*init) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth, - int (*copy) (EVP_PKEY_CTX *dst, - EVP_PKEY_CTX *src)); - void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth, - void (*cleanup) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth, - int (*paramgen_init) (EVP_PKEY_CTX *ctx), - int (*paramgen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth, - int (*keygen_init) (EVP_PKEY_CTX *ctx), - int (*keygen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth, - int (*sign_init) (EVP_PKEY_CTX *ctx), - int (*sign) (EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth, - int (*verify_init) (EVP_PKEY_CTX *ctx), - int (*verify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - size_t siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth, - int (*verify_recover_init) (EVP_PKEY_CTX - *ctx), - int (*verify_recover) (EVP_PKEY_CTX - *ctx, - unsigned char - *sig, - size_t *siglen, - const unsigned - char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth, - int (*signctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (*signctx) (EVP_PKEY_CTX *ctx, - unsigned char *sig, - size_t *siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth, - int (*verifyctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (*verifyctx) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - int siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth, - int (*encrypt_init) (EVP_PKEY_CTX *ctx), - int (*encryptfn) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth, - int (*decrypt_init) (EVP_PKEY_CTX *ctx), - int (*decrypt) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth, - int (*derive_init) (EVP_PKEY_CTX *ctx), - int (*derive) (EVP_PKEY_CTX *ctx, - unsigned char *key, - size_t *keylen)); - void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth, - int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, - void *p2), - int (*ctrl_str) (EVP_PKEY_CTX *ctx, - const char *type, - const char *value)); - - void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth, - int (**pinit) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth, - int (**pcopy) (EVP_PKEY_CTX *dst, - EVP_PKEY_CTX *src)); - void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth, - void (**pcleanup) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth, - int (**pparamgen_init) (EVP_PKEY_CTX *ctx), - int (**pparamgen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth, - int (**pkeygen_init) (EVP_PKEY_CTX *ctx), - int (**pkeygen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth, - int (**psign_init) (EVP_PKEY_CTX *ctx), - int (**psign) (EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth, - int (**pverify_init) (EVP_PKEY_CTX *ctx), - int (**pverify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - size_t siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth, - int (**pverify_recover_init) (EVP_PKEY_CTX - *ctx), - int (**pverify_recover) (EVP_PKEY_CTX - *ctx, - unsigned char - *sig, - size_t *siglen, - const unsigned - char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth, - int (**psignctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (**psignctx) (EVP_PKEY_CTX *ctx, - unsigned char *sig, - size_t *siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth, - int (**pverifyctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (**pverifyctx) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - int siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth, - int (**pencrypt_init) (EVP_PKEY_CTX *ctx), - int (**pencryptfn) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth, - int (**pdecrypt_init) (EVP_PKEY_CTX *ctx), - int (**pdecrypt) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth, - int (**pderive_init) (EVP_PKEY_CTX *ctx), - int (**pderive) (EVP_PKEY_CTX *ctx, - unsigned char *key, - size_t *keylen)); - void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth, - int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1, - void *p2), - int (**pctrl_str) (EVP_PKEY_CTX *ctx, - const char *type, - const char *value)); - -=head1 DESCRIPTION - -B is a structure which holds a set of methods for a -specific public key cryptographic algorithm. Those methods are usually -used to perform different jobs, such as generating a key, signing or -verifying, encrypting or decrypting, etc. - -There are two places where the B objects are stored: one -is a built-in static array representing the standard methods for different -algorithms, and the other one is a stack of user-defined application-specific -methods, which can be manipulated by using L. - -The B objects are usually referenced by B -objects. - -=head2 Methods - -The methods are the underlying implementations of a particular public key -algorithm present by the B object. - - int (*init) (EVP_PKEY_CTX *ctx); - int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src); - void (*cleanup) (EVP_PKEY_CTX *ctx); - -The init() method is called to initialize algorithm-specific data when a new -B is created. As opposed to init(), the cleanup() method is called -when an B is freed. The copy() method is called when an B -is being duplicated. Refer to L, L, -L and L. - - int (*paramgen_init) (EVP_PKEY_CTX *ctx); - int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); - -The paramgen_init() and paramgen() methods deal with key parameter generation. -They are called by L and L to -handle the parameter generation process. - - int (*keygen_init) (EVP_PKEY_CTX *ctx); - int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); - -The keygen_init() and keygen() methods are used to generate the actual key for -the specified algorithm. They are called by L and -L. - - int (*sign_init) (EVP_PKEY_CTX *ctx); - int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); - -The sign_init() and sign() methods are used to generate the signature of a -piece of data using a private key. They are called by L -and L. - - int (*verify_init) (EVP_PKEY_CTX *ctx); - int (*verify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, size_t siglen, - const unsigned char *tbs, size_t tbslen); - -The verify_init() and verify() methods are used to verify whether a signature is -valid. They are called by L and L. - - int (*verify_recover_init) (EVP_PKEY_CTX *ctx); - int (*verify_recover) (EVP_PKEY_CTX *ctx, - unsigned char *rout, size_t *routlen, - const unsigned char *sig, size_t siglen); - -The verify_recover_init() and verify_recover() methods are used to verify a -signature and then recover the digest from the signature (for instance, a -signature that was generated by RSA signing algorithm). They are called by -L and L. - - int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); - int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, - EVP_MD_CTX *mctx); - -The signctx_init() and signctx() methods are used to sign a digest present by -a B object. They are called by the EVP_DigestSign functions. See -L for detail. - - int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); - int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen, - EVP_MD_CTX *mctx); - -The verifyctx_init() and verifyctx() methods are used to verify a signature -against the data in a B object. They are called by the various -EVP_DigestVerify functions. See L for detail. - - int (*encrypt_init) (EVP_PKEY_CTX *ctx); - int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -The encrypt_init() and encrypt() methods are used to encrypt a piece of data. -They are called by L and L. - - int (*decrypt_init) (EVP_PKEY_CTX *ctx); - int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -The decrypt_init() and decrypt() methods are used to decrypt a piece of data. -They are called by L and L. - - int (*derive_init) (EVP_PKEY_CTX *ctx); - int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); - -The derive_init() and derive() methods are used to derive the shared secret -from a public key algorithm (for instance, the DH algorithm). They are called by -L and L. - - int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2); - int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value); - -The ctrl() and ctrl_str() methods are used to adjust algorithm-specific -settings. See L and related functions for detail. - - int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); - int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig, - size_t siglen, const unsigned char *tbs, - size_t tbslen); - -The digestsign() and digestverify() methods are used to generate or verify -a signature in a one-shot mode. They could be called by L -and L. - -=head2 Functions - -EVP_PKEY_meth_new() creates and returns a new B object, -and associates the given B and B. The following flags are -supported: - - EVP_PKEY_FLAG_AUTOARGLEN - EVP_PKEY_FLAG_SIGCTX_CUSTOM - -If an B is set with the B flag, the -maximum size of the output buffer will be automatically calculated or checked -in corresponding EVP methods by the EVP framework. Thus the implementations of -these methods don't need to care about handling the case of returning output -buffer size by themselves. For details on the output buffer size, refer to -L. - -The B is used to indicate the signctx() method -of an B is always called by the EVP framework while doing a -digest signing operation by calling L. - -EVP_PKEY_meth_free() frees an existing B pointed by -B. - -EVP_PKEY_meth_copy() copies an B object from B -to B. - -EVP_PKEY_meth_find() finds an B object with the B. -This function first searches through the user-defined method objects and -then the built-in objects. - -EVP_PKEY_meth_add0() adds B to the user defined stack of methods. - -The EVP_PKEY_meth_set functions set the corresponding fields of -B structure with the arguments passed. - -The EVP_PKEY_meth_get functions get the corresponding fields of -B structure to the arguments provided. - -=head1 RETURN VALUES - -EVP_PKEY_meth_new() returns a pointer to a new B -object or returns NULL on error. - -EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values. - -EVP_PKEY_meth_find() returns a pointer to the found B -object or returns NULL if not found. - -EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0 -if an error occurred. - -All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return -values. For the 'get' functions, function pointers are returned by -arguments. - -=head1 COPYRIGHT - -Copyright 2017 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. - -=cut