Fix some SSL_export_keying_material() issues
[openssl.git] / doc / man3 / EVP_PKEY_meth_new.pod
index acff78a..db803fc 100644 (file)
@@ -9,11 +9,16 @@ 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_set_check,
+EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check,
+EVP_PKEY_meth_set_digest_custom,
 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, EVP_PKEY_meth_get_check
+EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check,
+EVP_PKEY_meth_get_public_check, EVP_PKEY_meth_get_param_check,
+EVP_PKEY_meth_get_digest_custom,
+EVP_PKEY_meth_remove
 - manipulating EVP_PKEY_METHOD structure
 
 =head1 SYNOPSIS
@@ -27,6 +32,7 @@ EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check
  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);
+ int EVP_PKEY_meth_remove(const EVP_PKEY_METHOD *pmeth);
 
  void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth,
                              int (*init) (EVP_PKEY_CTX *ctx));
@@ -108,36 +114,43 @@ EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check
                                               const char *value));
  void EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth,
                               int (*check) (EVP_PKEY *pkey));
-
- void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth,
+ void EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth,
+                                     int (*check) (EVP_PKEY *pkey));
+ void EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth,
+                                    int (*check) (EVP_PKEY *pkey));
+ void EVP_PKEY_meth_set_digest_custom(EVP_PKEY_METHOD *pmeth,
+                                     int (*digest_custom) (EVP_PKEY_CTX *ctx,
+                                                           EVP_MD_CTX *mctx));
+
+ void EVP_PKEY_meth_get_init(const EVP_PKEY_METHOD *pmeth,
                              int (**pinit) (EVP_PKEY_CTX *ctx));
- void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth,
+ void EVP_PKEY_meth_get_copy(const 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 EVP_PKEY_meth_get_cleanup(const EVP_PKEY_METHOD *pmeth,
                                 void (**pcleanup) (EVP_PKEY_CTX *ctx));
- void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth,
+ void EVP_PKEY_meth_get_paramgen(const 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,
+ void EVP_PKEY_meth_get_keygen(const 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,
+ void EVP_PKEY_meth_get_sign(const 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,
+ void EVP_PKEY_meth_get_verify(const 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,
+ void EVP_PKEY_meth_get_verify_recover(const EVP_PKEY_METHOD *pmeth,
                                        int (**pverify_recover_init) (EVP_PKEY_CTX
                                                                      *ctx),
                                        int (**pverify_recover) (EVP_PKEY_CTX
@@ -148,47 +161,54 @@ EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl, EVP_PKEY_meth_get_check
                                                                 const unsigned
                                                                 char *tbs,
                                                                 size_t tbslen));
- void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth,
+ void EVP_PKEY_meth_get_signctx(const 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,
+ void EVP_PKEY_meth_get_verifyctx(const 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,
+ void EVP_PKEY_meth_get_encrypt(const 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,
+ void EVP_PKEY_meth_get_decrypt(const 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,
+ void EVP_PKEY_meth_get_derive(const 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,
+ void EVP_PKEY_meth_get_ctrl(const 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));
- void EVP_PKEY_meth_get_check(EVP_PKEY_METHOD *pmeth,
+ void EVP_PKEY_meth_get_check(const EVP_PKEY_METHOD *pmeth,
                               int (**pcheck) (EVP_PKEY *pkey));
+ void EVP_PKEY_meth_get_public_check(const EVP_PKEY_METHOD *pmeth,
+                                     int (**pcheck) (EVP_PKEY *pkey));
+ void EVP_PKEY_meth_get_param_check(const EVP_PKEY_METHOD *pmeth,
+                                    int (**pcheck) (EVP_PKEY *pkey));
+ void EVP_PKEY_meth_get_digest_custom(EVP_PKEY_METHOD *pmeth,
+                                     int (**pdigest_custom) (EVP_PKEY_CTX *ctx,
+                                                             EVP_MD_CTX *mctx));
 
 =head1 DESCRIPTION
 
@@ -314,9 +334,22 @@ a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)>
 and L<EVP_DigestVerify(3)>.
 
  int (*check) (EVP_PKEY *pkey);
+ int (*public_check) (EVP_PKEY *pkey);
+ int (*param_check) (EVP_PKEY *pkey);
+
+The check(), public_check() and param_check() methods are used to validate a
+key-pair, the public component and parameters respectively for a given B<pkey>.
+They could be called by L<EVP_PKEY_check(3)>, L<EVP_PKEY_public_check(3)> and
+L<EVP_PKEY_param_check(3)> respectively.
+
+ int (*digest_custom) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx);
 
-The check() method is used to validate a key-pair for a given B<pkey>. It
-could be called by L<EVP_PKEY_check(3)>.
+The digest_custom() method is used to generate customized digest content before
+the real message is passed to functions like L<EVP_DigestSignUpdate(3)> or
+L<EVP_DigestVerifyInit(3)>. This is usually required by some public key
+signature algorithms like SM2 which requires a hashed prefix to the message to
+be signed. The digest_custom() function will be called by L<EVP_DigestSignInit(3)>
+and L<EVP_DigestVerifyInit(3)>.
 
 =head2 Functions
 
@@ -350,6 +383,9 @@ then the built-in objects.
 
 EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods.
 
+EVP_PKEY_meth_remove() removes an B<EVP_PKEY_METHOD> object added by
+EVP_PKEY_meth_add0().
+
 The EVP_PKEY_meth_set functions set the corresponding fields of
 B<EVP_PKEY_METHOD> structure with the arguments passed.
 
@@ -369,13 +405,16 @@ object or returns NULL if not found.
 EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0
 if an error occurred.
 
+EVP_PKEY_meth_remove() returns 1 if method is removed 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.
+Copyright 2017-2018 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