1 files changed, 235 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_keygen.3 b/src/lib/libcrypto/man/EVP_PKEY_keygen.3
new file mode 100644
index 0000000000..8a5c7be0c6
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKEY_keygen.3
@@ -0,0 +1,235 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt EVP_PKEY_KEYGEN 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_keygen_init ,
+.Nm EVP_PKEY_keygen ,
+.Nm EVP_PKEY_paramgen_init ,
+.Nm EVP_PKEY_paramgen ,
+.Nm EVP_PKEY_CTX_set_cb ,
+.Nm EVP_PKEY_CTX_get_cb ,
+.Nm EVP_PKEY_CTX_get_keygen_info ,
+.Nm EVP_PKEY_CTX_set_app_data ,
+.Nm EVP_PKEY_CTX_get_app_data
+.Nd key and parameter generation functions
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft int
+.Fo EVP_PKEY_keygen_init
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_PKEY_keygen
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "EVP_PKEY **ppkey"
+.Fc
+.Ft int
+.Fo EVP_PKEY_paramgen_init
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_PKEY_paramgen
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "EVP_PKEY **ppkey"
+.Fc
+.Ft typedef int
+.Fo EVP_PKEY_gen_cb
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft void
+.Fo EVP_PKEY_CTX_set_cb
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "EVP_PKEY_gen_cb *cb"
+.Fc
+.Ft EVP_PKEY_gen_cb *
+.Fo EVP_PKEY_CTX_get_cb
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_PKEY_CTX_get_keygen_info
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "int idx"
+.Fc
+.Ft void
+.Fo EVP_PKEY_CTX_set_app_data
+.Fa "EVP_PKEY_CTX *ctx"
+.Fa "void *data"
+.Fc
+.Ft void *
+.Fo EVP_PKEY_CTX_get_app_data
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn EVP_PKEY_keygen_init
+function initializes a public key algorithm context using key
+.Fa ctx->pkey
+for a key generation operation.
+.Pp
+The
+.Fn EVP_PKEY_keygen
+function performs a key generation operation, the generated key is
+written to
+.Fa ppkey .
+.Pp
+The functions
+.Fn EVP_PKEY_paramgen_init
+and
+.Fn EVP_PKEY_paramgen
+are similar except parameters are generated.
+.Pp
+The function
+.Fn EVP_PKEY_CTX_set_cb
+sets the key or parameter generation callback to
+.Fa cb .
+The function
+.Fn EVP_PKEY_CTX_get_cb
+returns the key or parameter generation callback.
+.Pp
+The function
+.Fn EVP_PKEY_CTX_get_keygen_info
+returns parameters associated with the generation operation.
+If
+.Fa idx
+is -1, the total number of parameters available is returned.
+Any non negative value returns the value of that parameter.
+.Fn EVP_PKEY_CTX_get_keygen_info
+with a non-negative value for
+.Fa idx
+should only be called within the generation callback.
+.Pp
+If the callback returns 0, then the key generation operation is aborted
+and an error occurs.
+This might occur during a time consuming operation where a user clicks
+on a "cancel" button.
+.Pp
+The functions
+.Fn EVP_PKEY_CTX_set_app_data
+and
+.Fn EVP_PKEY_CTX_get_app_data
+set 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".
+.Pp
+After the call to
+.Fn EVP_PKEY_keygen_init
+or
+.Fn EVP_PKEY_paramgen_init ,
+algorithm specific control operations can be performed to set any
+appropriate parameters for the operation.
+.Pp
+The functions
+.Fn EVP_PKEY_keygen
+and
+.Fn EVP_PKEY_paramgen
+can be called more than once on the same context if several operations
+are performed using the same parameters.
+.Pp
+The meaning of the parameters passed to the callback will depend on the
+algorithm and the specific implementation of the algorithm.
+Some might not give any useful information at all during key or
+parameter generation.
+Others might not even call the callback.
+.Pp
+The operation performed by key or parameter generation depends on the
+algorithm used.
+In some cases (e.g. EC with a supplied named curve) the "generation"
+option merely sets the appropriate fields in an
+.Vt EVP_PKEY
+structure.
+.Pp
+In OpenSSL, an
+.Vt EVP_PKEY
+structure containing a private key also contains the public key
+components and parameters (if any).
+An OpenSSL private key is equivalent to what some libraries call a "key
+pair".
+A private key can be used in functions which require the use of a public
+key or parameters.
+.Sh RETURN VALUES
+.Fn EVP_PKEY_keygen_init ,
+.Fn EVP_PKEY_paramgen_init ,
+.Fn EVP_PKEY_keygen ,
+and
+.Fn 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.
+.Sh EXAMPLES
+Generate a 2048 bit RSA key:
+.Bd -literal
+#include <openssl/evp.h>
+#include <openssl/rsa.h>
+
+EVP_PKEY_CTX *ctx;
+EVP_PKEY *pkey = NULL;
+ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
+if (!ctx)
+        /* Error occurred */
+if (EVP_PKEY_keygen_init(ctx) <= 0)
+        /* Error */
+if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
+        /* Error */
+
+/* Generate key */
+if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
+        /* Error */
+.Ed
+.Pp
+Generate a key from a set of parameters:
+.Bd -literal
+#include <openssl/evp.h>
+#include <openssl/rsa.h>
+
+EVP_PKEY_CTX *ctx;
+EVP_PKEY *pkey = NULL, *param;
+/* Assumed param is set up already */
+ctx = EVP_PKEY_CTX_new(param);
+if (!ctx)
+        /* Error occurred */
+if (EVP_PKEY_keygen_init(ctx) <= 0)
+        /* Error */
+
+/* Generate key */
+if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
+        /* Error */
+.Ed
+.Pp
+Example of generation callback for OpenSSL public key implementations:
+.Bd -literal
+/* Application data is a BIO to output status to */
+
+EVP_PKEY_CTX_set_app_data(ctx, status_bio);
+
+static int
+genpkey_cb(EVP_PKEY_CTX *ctx)
+{
+        char c = '*';
+        BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
+        int p;
+
+        p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
+        if (p == 0)
+                c='.';
+        if (p == 1)
+                c='+';
+        if (p == 2)
+                c='*';
+        if (p == 3)
+                c='\en';
+        BIO_write(b,&c,1);
+        (void)BIO_flush(b);
+        return 1;
+}
+.Ed
+.Sh SEE ALSO
+.Xr EVP_PKEY_CTX_new 3 ,
+.Xr EVP_PKEY_decrypt 3 ,
+.Xr EVP_PKEY_derive 3 ,
+.Xr EVP_PKEY_encrypt 3 ,
+.Xr EVP_PKEY_sign 3 ,
+.Xr EVP_PKEY_verify 3 ,
+.Xr EVP_PKEY_verify_recover 3
+.Sh HISTORY
+These functions were first added to OpenSSL 1.0.0.