← Back to branch summary

~andersk/ubuntu/oneiric/openssl/spurious-reboot

« back to all changes in this revision

Viewing changes to doc/crypto/EVP_PKEY_keygen.pod

  • Committer: Bazaar Package Importer
  • Author(s): Colin Watson
  • Date: 2011-05-01 23:51:53 UTC
  • mfrom: (11.1.20 sid)
  • Revision ID: james.westby@ubuntu.com-20110501235153-bjcxitndquaezb68
Tags: 1.0.0d-2ubuntu1
https://launchpad.net/bugs/675566
* Resynchronise with Debian (LP: #675566).  Remaining changes:
  - debian/libssl1.0.0.postinst:
    + Display a system restart required notification bubble on libssl1.0.0
      upgrade.
    + Use a different priority for libssl1.0.0/restart-services depending
      on whether a desktop, or server dist-upgrade is being performed.
  - debian/{libssl1.0.0-udeb.dirs, control, rules}: Create
    libssl1.0.0-udeb, for the benefit of wget-udeb (no wget-udeb package
    in Debian).
  - debian/{libcrypto1.0.0-udeb.dirs, libssl1.0.0.dirs, libssl1.0.0.files,
    rules}: Move runtime libraries to /lib, for the benefit of
    wpasupplicant.
  - debian/patches/aesni.patch: Backport Intel AES-NI support, now from
    http://rt.openssl.org/Ticket/Display.html?id=2065 rather than the
    0.9.8 variant.
  - debian/patches/Bsymbolic-functions.patch: Link using
    -Bsymbolic-functions.
  - debian/patches/perlpath-quilt.patch: Don't change perl #! paths under
    .pc.
  - debian/rules:
    + Don't run 'make test' when cross-building.
    + Use host compiler when cross-building.  Patch from Neil Williams.
    + Don't build for processors no longer supported: i486, i586 (on
      i386), v8 (on sparc).
    + Fix Makefile to properly clean up libs/ dirs in clean target.
    + Replace duplicate files in the doc directory with symlinks.
* Update architectures affected by Bsymbolic-functions.patch.
* Drop debian/patches/no-sslv2.patch; Debian now adds the 'no-ssl2'
  configure option, which compiles out SSLv2 support entirely, so this is
  no longer needed.
* Drop openssl-doc in favour of the libssl-doc package introduced by
  Debian.  Add Conflicts/Replaces until the next LTS release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/crypto/EVP_PKEY_keygen.pod
 
1
=pod
 
2
 
 
3
=head1 NAME
 
4
 
 
5
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_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - key and parameter generation functions
 
6
 
 
7
=head1 SYNOPSIS
 
8
 
 
9
 #include <openssl/evp.h>
 
10
 
 
11
 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
 
12
 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 
13
 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
 
14
 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 
15
 
 
16
 typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
 
17
 
 
18
 void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
 
19
 EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
 
20
 
 
21
 int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
 
22
 
 
23
 void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
 
24
 void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
 
25
 
 
26
=head1 DESCRIPTION
 
27
 
 
28
The EVP_PKEY_keygen_init() function initializes a public key algorithm
 
29
context using key B<pkey> for a key genration operation.
 
30
 
 
31
The EVP_PKEY_keygen() function performs a key generation operation, the 
 
32
generated key is written to B<ppkey>.
 
33
 
 
34
The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
 
35
except parameters are generated.
 
36
 
 
37
The function EVP_PKEY_set_cb() sets the key or parameter generation callback
 
38
to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
 
39
generation callback.
 
40
 
 
41
The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
 
42
with the generation operation. If B<idx> is -1 the total number of
 
43
parameters available is returned. Any non negative value returns the value of
 
44
that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
 
45
B<idx> should only be called within the generation callback.
 
46
 
 
47
If the callback returns 0 then the key genration operation is aborted and an
 
48
error occurs. This might occur during a time consuming operation where
 
49
a user clicks on a "cancel" button.
 
50
 
 
51
The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
 
52
and retrieve an opaque pointer. This can be used to set some application
 
53
defined value which can be retrieved in the callback: for example a handle
 
54
which is used to update a "progress dialog".
 
55
 
 
56
=head1 NOTES
 
57
 
 
58
After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
 
59
specific control operations can be performed to set any appropriate parameters
 
60
for the operation.
 
61
 
 
62
The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
 
63
once on the same context if several operations are performed using the same
 
64
parameters.
 
65
 
 
66
The meaning of the parameters passed to the callback will depend on the
 
67
algorithm and the specifiic implementation of the algorithm. Some might not
 
68
give any useful information at all during key or parameter generation. Others
 
69
might not even call the callback.
 
70
 
 
71
The operation performed by key or parameter generation depends on the algorithm
 
72
used. In some cases (e.g. EC with a supplied named curve) the "generation"
 
73
option merely sets the appropriate fields in an EVP_PKEY structure.
 
74
 
 
75
In OpenSSL an EVP_PKEY structure containing a private key also contains the
 
76
public key components and parameters (if any). An OpenSSL private key is
 
77
equivalent to what some libraries call a "key pair". A private key can be used
 
78
in functions which require the use of a public key or parameters.
 
79
 
 
80
=head1 RETURN VALUES
 
81
 
 
82
EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
 
83
EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
 
84
In particular a return value of -2 indicates the operation is not supported by
 
85
the public key algorithm.
 
86
 
 
87
=head1 EXAMPLES
 
88
 
 
89
Generate a 2048 bit RSA key:
 
90
 
 
91
 #include <openssl/evp.h>
 
92
 #include <openssl/rsa.h>
 
93
 
 
94
 EVP_PKEY_CTX *ctx;
 
95
 EVP_PKEY *pkey = NULL;
 
96
 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
 
97
 if (!ctx)
 
98
        /* Error occurred */
 
99
 if (EVP_PKEY_keygen_init(ctx) <= 0)
 
100
        /* Error */
 
101
 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
 
102
        /* Error */
 
103
 
 
104
 /* Generate key */
 
105
 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 
106
        /* Error */
 
107
 
 
108
Generate a key from a set of parameters:
 
109
 
 
110
 #include <openssl/evp.h>
 
111
 #include <openssl/rsa.h>
 
112
 
 
113
 EVP_PKEY_CTX *ctx;
 
114
 EVP_PKEY *pkey = NULL, *param;
 
115
 /* Assumed param is set up already */
 
116
 ctx = EVP_PKEY_CTX_new(param);
 
117
 if (!ctx)
 
118
        /* Error occurred */
 
119
 if (EVP_PKEY_keygen_init(ctx) <= 0)
 
120
        /* Error */
 
121
 
 
122
 /* Generate key */
 
123
 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
 
124
        /* Error */
 
125
 
 
126
Example of generation callback for OpenSSL public key implementations:
 
127
 
 
128
 /* Application data is a BIO to output status to */
 
129
 
 
130
 EVP_PKEY_CTX_set_app_data(ctx, status_bio);
 
131
 
 
132
 static int genpkey_cb(EVP_PKEY_CTX *ctx)
 
133
        {
 
134
        char c='*';
 
135
        BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
 
136
        int p;
 
137
        p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
 
138
        if (p == 0) c='.';
 
139
        if (p == 1) c='+';
 
140
        if (p == 2) c='*';
 
141
        if (p == 3) c='\n';
 
142
        BIO_write(b,&c,1);
 
143
        (void)BIO_flush(b);
 
144
        return 1;
 
145
        }
 
146
 
 
147
=head1 SEE ALSO
 
148
 
 
149
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
 
150
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
 
151
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
 
152
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
 
153
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
 
154
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
 
155
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> 
 
156
 
 
157
=head1 HISTORY
 
158
 
 
159
These functions were first added to OpenSSL 1.0.0.
 
160
 
 
161
=cut