trace: add PROVIDER_CONF trace category

[openssl.git] / doc / man3 / EVP_PKEY_keygen.pod

diff --git a/doc/man3/EVP_PKEY_keygen.pod b/doc/man3/EVP_PKEY_keygen.pod
index b7f2128baa61c04bbfb28b0446178b58bd23ce31..439d7d11fdbf5077e3edc7f8c68d0f4df9d236a5 100644 (file)
--- a/doc/man3/EVP_PKEY_keygen.pod
+++ b/doc/man3/EVP_PKEY_keygen.pod
@@ -6,8 +6,9 @@ EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
 EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
 EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
 EVP_PKEY_CTX_get_app_data,
-EVP_PKEY_gen_cb
-- key and parameter generation functions
+EVP_PKEY_gen_cb, EVP_PKEY_check, EVP_PKEY_public_check,
+EVP_PKEY_param_check
+- key and parameter generation and check functions
 
 =head1 SYNOPSIS
 
@@ -18,7 +19,7 @@ EVP_PKEY_gen_cb
  int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 
- typedef int (*EVP_PKEY_gen_cb)(EVP_PKEY_CTX *ctx);
+ typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
 
  void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
  EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
@@ -28,6 +29,10 @@ EVP_PKEY_gen_cb
  void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
  void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
 
+ int EVP_PKEY_check(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_public_check(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_param_check(EVP_PKEY_CTX *ctx);
+
 =head1 DESCRIPTION
 
 The EVP_PKEY_keygen_init() function initializes a public key algorithm
@@ -58,6 +63,18 @@ and retrieve an opaque pointer. This can be used to set some application
 defined value which can be retrieved in the callback: for example a handle
 which is used to update a "progress dialog".
 
+EVP_PKEY_check() validates the key-pair given by B<ctx>. This function first tries
+to use customized key check method in B<EVP_PKEY_METHOD> if it's present; otherwise
+it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>.
+
+EVP_PKEY_public_check() validates the public component of the key-pair given by B<ctx>.
+This function first tries to use customized key check method in B<EVP_PKEY_METHOD>
+if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>.
+
+EVP_PKEY_param_check() validates the algorithm parameters of the key-pair given by B<ctx>.
+This function first tries to use customized key check method in B<EVP_PKEY_METHOD>
+if it's present; otherwise it calls a default one defined in B<EVP_PKEY_ASN1_METHOD>.
+
 =head1 NOTES
 
 After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
@@ -89,6 +106,10 @@ EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
+EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() return 1
+for success or others for failure. They return -2 if the operation is not supported
+for the specific algorithm.
+
 =head1 EXAMPLES
 
 Generate a 2048 bit RSA key:
@@ -117,10 +138,11 @@ Generate a key from a set of parameters:
  #include <openssl/rsa.h>
 
  EVP_PKEY_CTX *ctx;
+ ENGINE *eng;
  EVP_PKEY *pkey = NULL, *param;
 
- /* Assumed param is set up already */
- ctx = EVP_PKEY_CTX_new(param);
+ /* Assumed param, eng are set up already */
+ ctx = EVP_PKEY_CTX_new(param, eng);
  if (!ctx)
      /* Error occurred */
  if (EVP_PKEY_keygen_init(ctx) <= 0)
@@ -167,13 +189,16 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were first added to OpenSSL 1.0.0.
+These functions were added in OpenSSL 1.0.0.
+
+EVP_PKEY_check(), EVP_PKEY_public_check() and EVP_PKEY_param_check() were added
+in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.