summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/doc
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/doc')
-rw-r--r--src/lib/libcrypto/doc/EVP_BytesToKey.pod68
-rw-r--r--src/lib/libcrypto/doc/EVP_DigestInit.pod277
-rw-r--r--src/lib/libcrypto/doc/EVP_DigestSignInit.pod85
-rw-r--r--src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod80
-rw-r--r--src/lib/libcrypto/doc/EVP_EncryptInit.pod548
-rw-r--r--src/lib/libcrypto/doc/EVP_OpenInit.pod61
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod135
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod53
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_cmp.pod62
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod93
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_derive.pod94
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod93
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod41
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_keygen.pod170
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_new.pod43
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_print_private.pod54
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod76
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_sign.pod96
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_verify.pod92
-rw-r--r--src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod105
-rw-r--r--src/lib/libcrypto/doc/EVP_SealInit.pod82
-rw-r--r--src/lib/libcrypto/doc/EVP_SignInit.pod103
-rw-r--r--src/lib/libcrypto/doc/EVP_VerifyInit.pod96
-rw-r--r--src/lib/libcrypto/doc/evp.pod107
24 files changed, 0 insertions, 2714 deletions
diff --git a/src/lib/libcrypto/doc/EVP_BytesToKey.pod b/src/lib/libcrypto/doc/EVP_BytesToKey.pod
deleted file mode 100644
index 2dffaa1efa..0000000000
--- a/src/lib/libcrypto/doc/EVP_BytesToKey.pod
+++ /dev/null
@@ -1,68 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_BytesToKey - password based encryption routine
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md,
12 const unsigned char *salt,
13 const unsigned char *data, int datal, int count,
14 unsigned char *key,unsigned char *iv);
15
16=head1 DESCRIPTION
17
18EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
19the cipher to derive the key and IV for. B<md> is the message digest to use.
20The B<salt> parameter is used as a salt in the derivation: it should point to
21an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
22B<datal> bytes which is used to derive the keying data. B<count> is the
23iteration count to use. The derived key and IV will be written to B<key>
24and B<iv> respectively.
25
26=head1 NOTES
27
28A typical application of this function is to derive keying material for an
29encryption algorithm from a password in the B<data> parameter.
30
31Increasing the B<count> parameter slows down the algorithm which makes it
32harder for an attacker to perform a brute force attack using a large number
33of candidate passwords.
34
35If the total key and IV length is less than the digest length and
36B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
37otherwise a non standard extension is used to derive the extra data.
38
39Newer applications should use more standard algorithms such as PBKDF2 as
40defined in PKCS#5v2.1 for key derivation.
41
42=head1 KEY DERIVATION ALGORITHM
43
44The key and IV is derived by concatenating D_1, D_2, etc until
45enough data is available for the key and IV. D_i is defined as:
46
47 D_i = HASH^count(D_(i-1) || data || salt)
48
49where || denotes concatenation, D_0 is empty, HASH is the digest
50algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data)
51is HASH(HASH(data)) and so on.
52
53The initial bytes are used for the key and the subsequent bytes for
54the IV.
55
56=head1 RETURN VALUES
57
58EVP_BytesToKey() returns the size of the derived key in bytes.
59
60=head1 SEE ALSO
61
62L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
63L<PKCS5_PBKDF2_HMAC(3)|PKCS5_PBKDF2_HMAC(3)>,
64L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>
65
66=head1 HISTORY
67
68=cut
diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod
deleted file mode 100644
index c83dcc736f..0000000000
--- a/src/lib/libcrypto/doc/EVP_DigestInit.pod
+++ /dev/null
@@ -1,277 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate,
6EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE,
7EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type,
8EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
9EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5,
10EVP_sha1, EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1,
11EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid,
12EVP_get_digestbyobj, EVP_DigestInit, EVP_DigestFinal - EVP digest routines
13
14=head1 SYNOPSIS
15
16 #include <openssl/evp.h>
17
18 void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
19 EVP_MD_CTX *EVP_MD_CTX_create(void);
20
21 int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
22 int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
23 int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
24 unsigned int *s);
25
26 int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
27 void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
28
29 int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
30
31 int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
32 int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
33 unsigned int *s);
34
35 int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
36
37 #define EVP_MAX_MD_SIZE 64 /* SHA512 */
38
39 int EVP_MD_type(const EVP_MD *md);
40 int EVP_MD_pkey_type(const EVP_MD *md);
41 int EVP_MD_size(const EVP_MD *md);
42 int EVP_MD_block_size(const EVP_MD *md);
43
44 const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
45 #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e))
46 #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
47 #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
48
49 const EVP_MD *EVP_md_null(void);
50 const EVP_MD *EVP_md2(void);
51 const EVP_MD *EVP_md5(void);
52 const EVP_MD *EVP_sha1(void);
53 const EVP_MD *EVP_dss(void);
54 const EVP_MD *EVP_dss1(void);
55 const EVP_MD *EVP_ripemd160(void);
56
57 const EVP_MD *EVP_sha224(void);
58 const EVP_MD *EVP_sha256(void);
59 const EVP_MD *EVP_sha384(void);
60 const EVP_MD *EVP_sha512(void);
61
62 const EVP_MD *EVP_get_digestbyname(const char *name);
63 #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
64 #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))
65
66=head1 DESCRIPTION
67
68The EVP digest routines are a high level interface to message digests.
69
70EVP_MD_CTX_init() initializes digest context B<ctx>.
71
72EVP_MD_CTX_create() allocates, initializes and returns a digest context.
73
74EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
75B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
76function. B<type> will typically be supplied by a function such as EVP_sha1().
77If B<impl> is NULL then the default implementation of digest B<type> is used.
78
79EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
80digest context B<ctx>. This function can be called several times on the
81same B<ctx> to hash additional data.
82
83EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places
84it in B<md>. If the B<s> parameter is not NULL then the number of
85bytes of data written (i.e. the length of the digest) will be written
86to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
87After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate()
88can be made, but EVP_DigestInit_ex() can be called to initialize a new
89digest operation.
90
91EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called
92after a digest context is no longer needed.
93
94EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the
95space allocated to it, it should be called only on a context created
96using EVP_MD_CTX_create().
97
98EVP_MD_CTX_copy_ex() can be used to copy the message digest state from
99B<in> to B<out>. This is useful if large amounts of data are to be
100hashed which only differ in the last few bytes. B<out> must be initialized
101before calling this function.
102
103EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except
104the passed context B<ctx> does not have to be initialized, and it always
105uses the default digest implementation.
106
107EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
108context B<ctx> is automatically cleaned up.
109
110EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
111B<out> does not have to be initialized.
112
113EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest
114when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the
115hash.
116
117EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the
118message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure.
119
120EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER
121representing the given message digest when passed an B<EVP_MD> structure.
122For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is
123normally used when setting ASN1 OIDs.
124
125EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed
126B<EVP_MD_CTX>.
127
128EVP_MD_pkey_type() returns the NID of the public key signing algorithm
129associated with this digest. For example EVP_sha1() is associated with RSA so
130this will return B<NID_sha1WithRSAEncryption>. Since digests and signature
131algorithms are no longer linked this function is only retained for
132compatibility reasons.
133
134EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(),
135EVP_sha512() and EVP_ripemd160() return B<EVP_MD> structures for the MD2, MD5,
136SHA1, SHA224, SHA256, SHA384, SHA512 and RIPEMD160 digest algorithms
137respectively.
138
139EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA1 digest
140algorithms but using DSS (DSA) for the signature algorithm. Note: there is
141no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are
142however retained for compatibility.
143
144EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it
145returns is of zero length.
146
147EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
148return an B<EVP_MD> structure when passed a digest name, a digest NID or
149an ASN1_OBJECT structure respectively. The digest table must be initialized
150using, for example, OpenSSL_add_all_digests() for these functions to work.
151
152=head1 RETURN VALUES
153
154EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for
155success and 0 for failure.
156
157EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
158
159EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
160corresponding OBJECT IDENTIFIER or NID_undef if none exists.
161
162EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
163EVP_MD_CTX_block_size() return the digest or block size in bytes.
164
165EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), EVP_dss(),
166EVP_dss1() and EVP_ripemd160() return pointers to the
167corresponding EVP_MD structures.
168
169EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
170return either an B<EVP_MD> structure or NULL if an error occurs.
171
172=head1 NOTES
173
174The B<EVP> interface to message digests should almost always be used in
175preference to the low level interfaces. This is because the code then becomes
176transparent to the digest used and much more flexible.
177
178New applications should use the SHA2 digest algorithms such as SHA256.
179The other digest algorithms are still in common use.
180
181For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
182set to NULL to use the default digest implementation.
183
184The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
185obsolete but are retained to maintain compatibility with existing code. New
186applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
187EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
188instead of initializing and cleaning it up on each call and allow non default
189implementations of digests to be specified.
190
191In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use
192memory leaks will occur.
193
194Stack allocation of EVP_MD_CTX structures is common, for example:
195
196 EVP_MD_CTX mctx;
197 EVP_MD_CTX_init(&mctx);
198
199This will cause binary compatibility issues if the size of EVP_MD_CTX
200structure changes (this will only happen with a major release of OpenSSL).
201Applications wishing to avoid this should use EVP_MD_CTX_create() instead:
202
203 EVP_MD_CTX *mctx;
204 mctx = EVP_MD_CTX_create();
205
206
207=head1 EXAMPLE
208
209This example digests the data "Test Message\n" and "Hello World\n", using the
210digest name passed on the command line.
211
212 #include <stdio.h>
213 #include <openssl/evp.h>
214
215 int
216 main(int argc, char *argv[])
217 {
218 EVP_MD_CTX *mdctx;
219 const EVP_MD *md;
220 const char mess1[] = "Test Message\n";
221 const char mess2[] = "Hello World\n";
222 unsigned char md_value[EVP_MAX_MD_SIZE];
223 int md_len, i;
224
225 OpenSSL_add_all_digests();
226
227 if (argc <= 1) {
228 printf("Usage: mdtest digestname\n");
229 exit(1);
230 }
231
232 md = EVP_get_digestbyname(argv[1]);
233 if (md == NULL) {
234 printf("Unknown message digest %s\n", argv[1]);
235 exit(1);
236 }
237
238 mdctx = EVP_MD_CTX_create();
239 EVP_DigestInit_ex(mdctx, md, NULL);
240 EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
241 EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
242 EVP_DigestFinal_ex(mdctx, md_value, &md_len);
243 EVP_MD_CTX_destroy(mdctx);
244
245 printf("Digest is: ");
246 for(i = 0; i < md_len; i++)
247 printf("%02x", md_value[i]);
248 printf("\n");
249 }
250
251=head1 SEE ALSO
252
253L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
254L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>,
255L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
256
257=head1 HISTORY
258
259EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are
260available in all versions of SSLeay and OpenSSL.
261
262EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(),
263EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex()
264and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7.
265
266EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(),
267EVP_dss(), EVP_dss1() and EVP_ripemd160() were
268changed to return truely const EVP_MD * in OpenSSL 0.9.7.
269
270The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
271later, so now EVP_sha1() can be used with RSA and DSA, there is no need to
272use EVP_dss1() any more.
273
274OpenSSL 1.0 and later does not include the MD2 digest algorithm in the
275default configuration due to its security weaknesses.
276
277=cut
diff --git a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod b/src/lib/libcrypto/doc/EVP_DigestSignInit.pod
deleted file mode 100644
index 00205d2ae9..0000000000
--- a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod
+++ /dev/null
@@ -1,85 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing
6functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
13 const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
14 int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
15 int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
16
17=head1 DESCRIPTION
18
19The EVP signature routines are a high level interface to digital signatures.
20
21EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
22ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with
23EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the
24EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
25be used to set alternative signing options.
26
27EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
28signature context B<ctx>. This function can be called several times on the
29same B<ctx> to include additional data. This function is currently implemented
30using a macro.
31
32EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
33If B<sig> is B<NULL> then the maximum size of the output buffer is written to
34the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
35B<siglen> parameter should contain the length of the B<sig> buffer, if the
36call is successful the signature is written to B<sig> and the amount of data
37written to B<siglen>.
38
39=head1 RETURN VALUES
40
41EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
421 for success and 0 or a negative value for failure. In particular a return
43value of -2 indicates the operation is not supported by the public key
44algorithm.
45
46The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
47
48=head1 NOTES
49
50The B<EVP> interface to digital signatures should almost always be used in
51preference to the low level interfaces. This is because the code then becomes
52transparent to the algorithm used and much more flexible.
53
54In previous versions of OpenSSL there was a link between message digest types
55and public key algorithms. This meant that "clone" digests such as EVP_dss1()
56needed to be used to sign using SHA1 and DSA. This is no longer necessary and
57the use of clone digest is now discouraged.
58
59The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
60context. This means that calls to EVP_DigestSignUpdate() and
61EVP_DigestSignFinal() can be called later to digest and sign additional data.
62
63Since only a copy of the digest context is ever finalized the context must
64be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
65will occur.
66
67The use of EVP_PKEY_size() with these functions is discouraged because some
68signature operations may have a signature length which depends on the
69parameters set. As a result EVP_PKEY_size() would have to return a value
70which indicates the maximum possible signature for any set of parameters.
71
72=head1 SEE ALSO
73
74L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>,
75L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
76L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
77L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>,
78L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
79
80=head1 HISTORY
81
82EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
83were first added to OpenSSL 1.0.0.
84
85=cut
diff --git a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod b/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod
deleted file mode 100644
index 5dcfec1837..0000000000
--- a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod
+++ /dev/null
@@ -1,80 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP
6signature verification functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
13 const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
14 int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
15 int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen);
16
17=head1 DESCRIPTION
18
19The EVP signature routines are a high level interface to digital signatures.
20
21EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest
22B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized
23with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the
24EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
25can be used to set alternative verification options.
26
27EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
28verification context B<ctx>. This function can be called several times on the
29same B<ctx> to include additional data. This function is currently implemented
30using a macro.
31
32EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in
33B<sig> of length B<siglen>.
34
35=head1 RETURN VALUES
36
37EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0
38or a negative value for failure. In particular a return value of -2 indicates
39the operation is not supported by the public key algorithm.
40
41Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only
42indicates that the signature did not verify successfully (that is tbs did
43not match the original data or the signature was of invalid form) it is not an
44indication of a more serious error.
45
46The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
47
48=head1 NOTES
49
50The B<EVP> interface to digital signatures should almost always be used in
51preference to the low level interfaces. This is because the code then becomes
52transparent to the algorithm used and much more flexible.
53
54In previous versions of OpenSSL there was a link between message digest types
55and public key algorithms. This meant that "clone" digests such as EVP_dss1()
56needed to be used to sign using SHA1 and DSA. This is no longer necessary and
57the use of clone digest is now discouraged.
58
59The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
60context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can
61be called later to digest and verify additional data.
62
63Since only a copy of the digest context is ever finalized the context must
64be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
65will occur.
66
67=head1 SEE ALSO
68
69L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,
70L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
71L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
72L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>,
73L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
74
75=head1 HISTORY
76
77EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal()
78were first added to OpenSSL 1.0.0.
79
80=cut
diff --git a/src/lib/libcrypto/doc/EVP_EncryptInit.pod b/src/lib/libcrypto/doc/EVP_EncryptInit.pod
deleted file mode 100644
index 7ae3fe31ea..0000000000
--- a/src/lib/libcrypto/doc/EVP_EncryptInit.pod
+++ /dev/null
@@ -1,548 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
6EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
7EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
8EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
9EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit,
10EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
11EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
12EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
13EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
14EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
15EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
16EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
17EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
18EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
19EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
20EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
21EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
22EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
23EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc,
24EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
25EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
26EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb,
27EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm,
28EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_rc5_32_12_16_cbc,
29EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_ofb
30- EVP cipher routines
31
32=head1 SYNOPSIS
33
34 #include <openssl/evp.h>
35
36 void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
37
38 int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
39 ENGINE *impl, unsigned char *key, unsigned char *iv);
40 int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
41 int *outl, unsigned char *in, int inl);
42 int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
43 int *outl);
44
45 int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
46 ENGINE *impl, unsigned char *key, unsigned char *iv);
47 int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
48 int *outl, unsigned char *in, int inl);
49 int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
50 int *outl);
51
52 int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
53 ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
54 int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
55 int *outl, unsigned char *in, int inl);
56 int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
57 int *outl);
58
59 int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
60 unsigned char *key, unsigned char *iv);
61 int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
62 int *outl);
63
64 int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
65 unsigned char *key, unsigned char *iv);
66 int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
67 int *outl);
68
69 int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
70 unsigned char *key, unsigned char *iv, int enc);
71 int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
72 int *outl);
73
74 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
75 int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
76 int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
77 int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
78
79 const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
80 #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
81 #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
82
83 #define EVP_CIPHER_nid(e) ((e)->nid)
84 #define EVP_CIPHER_block_size(e) ((e)->block_size)
85 #define EVP_CIPHER_key_length(e) ((e)->key_len)
86 #define EVP_CIPHER_iv_length(e) ((e)->iv_len)
87 #define EVP_CIPHER_flags(e) ((e)->flags)
88 #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
89 int EVP_CIPHER_type(const EVP_CIPHER *ctx);
90
91 #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
92 #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
93 #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
94 #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
95 #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
96 #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
97 #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
98 #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
99 #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
100 #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)
101
102 int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
103 int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
104
105=head1 DESCRIPTION
106
107The EVP cipher routines are a high level interface to certain
108symmetric ciphers.
109
110EVP_CIPHER_CTX_init() initializes cipher context B<ctx>.
111
112EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
113with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
114before calling this function. B<type> is normally supplied
115by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
116default implementation is used. B<key> is the symmetric key to use
117and B<iv> is the IV to use (if necessary), the actual number of bytes
118used for the key and IV depends on the cipher. It is possible to set
119all parameters to NULL except B<type> in an initial call and supply
120the remaining parameters in subsequent calls, all of which have B<type>
121set to NULL. This is done when the default cipher parameters are not
122appropriate.
123
124EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
125writes the encrypted version to B<out>. This function can be called
126multiple times to encrypt successive blocks of data. The amount
127of data written depends on the block alignment of the encrypted data:
128as a result the amount of data written may be anything from zero bytes
129to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
130room. The actual number of bytes written is placed in B<outl>.
131
132If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
133the "final" data, that is any data that remains in a partial block.
134It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted
135final data is written to B<out> which should have sufficient space for
136one cipher block. The number of bytes written is placed in B<outl>. After
137this function is called the encryption operation is finished and no further
138calls to EVP_EncryptUpdate() should be made.
139
140If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
141data and it will return an error if any data remains in a partial block:
142that is if the total data length is not a multiple of the block size.
143
144EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the
145corresponding decryption operations. EVP_DecryptFinal() will return an
146error code if padding is enabled and the final block is not correctly
147formatted. The parameters and restrictions are identical to the encryption
148operations except that if padding is enabled the decrypted data buffer B<out>
149passed to EVP_DecryptUpdate() should have sufficient room for
150(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in
151which case B<inl> bytes is sufficient.
152
153EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are
154functions that can be used for decryption or encryption. The operation
155performed depends on the value of the B<enc> parameter. It should be set
156to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
157(the actual value of 'enc' being supplied in a previous call).
158
159EVP_CIPHER_CTX_cleanup() clears all information from a cipher context
160and free up any allocated memory associate with it. It should be called
161after all operations using a cipher are complete so sensitive information
162does not remain in memory.
163
164EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
165similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
166EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
167initialized and they always use the default cipher implementation.
168
169EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
170identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
171EVP_CipherFinal_ex(). In previous releases of OpenSSL they also used to clean
172up the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
173must be called to free any context resources.
174
175EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
176return an EVP_CIPHER structure when passed a cipher name, a NID or an
177ASN1_OBJECT structure.
178
179EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when
180passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID
181value is an internal value which may not have a corresponding OBJECT
182IDENTIFIER.
183
184EVP_CIPHER_CTX_set_padding() enables or disables padding. By default
185encryption operations are padded using standard block padding and the
186padding is checked and removed when decrypting. If the B<pad> parameter
187is zero then no padding is performed, the total amount of data encrypted
188or decrypted must then be a multiple of the block size or an error will
189occur.
190
191EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
192length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
193structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
194for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
195given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
196for variable key length ciphers.
197
198EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
199If the cipher is a fixed length cipher then attempting to set the key
200length to any value other than the fixed value is an error.
201
202EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
203length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>.
204It will return zero if the cipher does not use an IV. The constant
205B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
206
207EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
208size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
209structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block
210length for all ciphers.
211
212EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
213cipher or context. This "type" is the actual NID of the cipher OBJECT
214IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
215128 bit RC2 have the same NID. If the cipher does not have an object
216identifier or does not have ASN1 support this function will return
217B<NID_undef>.
218
219EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed
220an B<EVP_CIPHER_CTX> structure.
221
222EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
223EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
224EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
225EVP_CIPH_STREAM_CIPHER is returned.
226
227EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
228on the passed cipher. This will typically include any parameters and an
229IV. The cipher IV (if any) must be set when this call is made. This call
230should be made before the cipher is actually "used" (before any
231EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function
232may fail if the cipher does not have any ASN1 support.
233
234EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
235AlgorithmIdentifier "parameter". The precise effect depends on the cipher
236In the case of RC2, for example, it will set the IV and effective key length.
237This function should be called after the base cipher type is set but before
238the key is set. For example EVP_CipherInit() will be called with the IV and
239key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
240EVP_CipherInit() again with all parameters except the key set to NULL. It is
241possible for this function to fail if the cipher does not have any ASN1 support
242or the parameters cannot be set (for example the RC2 effective key length
243is not supported.
244
245EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
246and set. Currently only the RC2 effective key length and the number of rounds of
247RC5 can be set.
248
249=head1 RETURN VALUES
250
251EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
252return 1 for success and 0 for failure.
253
254EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for
255failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for
256success.
257
258EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for
259failure. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for
260success.
261
262EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
263
264EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
265return an B<EVP_CIPHER> structure or NULL on error.
266
267EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID.
268
269EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block
270size.
271
272EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
273length.
274
275EVP_CIPHER_CTX_set_padding() always returns 1.
276
277EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV
278length or zero if the cipher does not use an IV.
279
280EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's
281OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER.
282
283EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
284
285EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for
286success or zero for failure.
287
288=head1 CIPHER LISTING
289
290All algorithms have a fixed key length unless otherwise stated.
291
292=over 4
293
294=item EVP_enc_null(void)
295
296Null cipher: does nothing.
297
298=item EVP_aes_128_cbc(void), EVP_aes_128_ecb(void), EVP_aes_128_cfb(void), EVP_aes_128_ofb(void)
299
300128-bit AES in CBC, ECB, CFB and OFB modes respectively.
301
302=item EVP_aes_192_cbc(void), EVP_aes_192_ecb(void), EVP_aes_192_cfb(void), EVP_aes_192_ofb(void)
303
304192-bit AES in CBC, ECB, CFB and OFB modes respectively.
305
306=item EVP_aes_256_cbc(void), EVP_aes_256_ecb(void), EVP_aes_256_cfb(void), EVP_aes_256_ofb(void)
307
308256-bit AES in CBC, ECB, CFB and OFB modes respectively.
309
310=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)
311
312DES in CBC, ECB, CFB and OFB modes respectively.
313
314=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void),
315EVP_des_ede_cfb(void)
316
317Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
318
319=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void),
320EVP_des_ede3_cfb(void)
321
322Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
323
324=item EVP_desx_cbc(void)
325
326DESX algorithm in CBC mode.
327
328=item EVP_rc4(void)
329
330RC4 stream cipher. This is a variable key length cipher with default key length
331128 bits.
332
333=item EVP_rc4_40(void)
334
335RC4 stream cipher with 40 bit key length. This is obsolete and new code should
336use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function.
337
338=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void),
339EVP_idea_ofb(void), EVP_idea_cbc(void)
340
341IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
342
343=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)
344
345RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a
346variable key length cipher with an additional parameter called "effective key
347bits" or "effective key length". By default both are set to 128 bits.
348
349=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)
350
351RC2 algorithm in CBC mode with a default key length and effective key length of
35240 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(),
353EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length
354and effective key length.
355
356=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);
357
358Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This
359is a variable key length cipher.
360
361=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void),
362EVP_cast5_ofb(void)
363
364CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is
365a variable key length cipher.
366
367=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void),
368EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)
369
370RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a
371variable key length cipher with an additional "number of rounds" parameter. By
372default the key length is set to 128 bits and 12 rounds.
373
374=back
375
376=head1 NOTES
377
378Where possible the B<EVP> interface to symmetric ciphers should be used in
379preference to the low level interfaces. This is because the code then becomes
380transparent to the cipher used and much more flexible.
381
382PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
383length of the encrypted data a multiple of the block size. Padding is always
384added so if the data is already a multiple of the block size B<n> will equal
385the block size. For example if the block size is 8 and 11 bytes are to be
386encrypted then 5 padding bytes of value 5 will be added.
387
388When decrypting the final block is checked to see if it has the correct form.
389
390Although the decryption operation can produce an error if padding is enabled,
391it is not a strong test that the input data or key is correct. A random block
392has better than 1 in 256 chance of being of the correct format and problems with
393the input data earlier on will not produce a final decrypt error.
394
395If padding is disabled then the decryption operation will always succeed if
396the total amount of data decrypted is a multiple of the block size.
397
398The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(),
399EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for
400compatibility with existing code. New code should use EVP_EncryptInit_ex(),
401EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
402EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
403existing context without allocating and freeing it up on each call.
404
405=head1 BUGS
406
407For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
408a limitation of the current RC5 code rather than the EVP interface.
409
410EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
411default key lengths. If custom ciphers exceed these values the results are
412unpredictable. This is because it has become standard practice to define a
413generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
414
415The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
416for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
417
418=head1 EXAMPLES
419
420Get the number of rounds used in RC5:
421
422 int nrounds;
423 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
424
425Get the RC2 effective key length:
426
427 int key_bits;
428 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
429
430Set the number of rounds used in RC5:
431
432 int nrounds;
433 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
434
435Set the effective key length used in RC2:
436
437 int key_bits;
438 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
439
440Encrypt a string using blowfish:
441
442 int
443 do_crypt(char *outfile)
444 {
445 unsigned char outbuf[1024];
446 int outlen, tmplen;
447 /*
448 * Bogus key and IV: we'd normally set these from
449 * another source.
450 */
451 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
452 unsigned char iv[] = {1,2,3,4,5,6,7,8};
453 const char intext[] = "Some Crypto Text";
454 EVP_CIPHER_CTX ctx;
455 FILE *out;
456 EVP_CIPHER_CTX_init(&ctx);
457 EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
458
459 if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext,
460 strlen(intext))) {
461 /* Error */
462 return 0;
463 }
464 /*
465 * Buffer passed to EVP_EncryptFinal() must be after data just
466 * encrypted to avoid overwriting it.
467 */
468 if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) {
469 /* Error */
470 return 0;
471 }
472 outlen += tmplen;
473 EVP_CIPHER_CTX_cleanup(&ctx);
474 /*
475 * Need binary mode for fopen because encrypted data is
476 * binary data. Also cannot use strlen() on it because
477 * it won't be NUL terminated and may contain embedded
478 * NULs.
479 */
480 out = fopen(outfile, "wb");
481 fwrite(outbuf, 1, outlen, out);
482 fclose(out);
483 return 1;
484 }
485
486The ciphertext from the above example can be decrypted using the B<openssl>
487utility with the command line:
488
489 S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>
490
491General encryption, decryption function example using FILE I/O and RC2 with an
49280 bit key:
493
494 int
495 do_crypt(FILE *in, FILE *out, int do_encrypt)
496 {
497 /* Allow enough space in output buffer for additional block */
498 inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
499 int inlen, outlen;
500 /*
501 * Bogus key and IV: we'd normally set these from
502 * another source.
503 */
504 unsigned char key[] = "0123456789";
505 unsigned char iv[] = "12345678";
506
507 /* Don't set key or IV because we will modify the parameters */
508 EVP_CIPHER_CTX_init(&ctx);
509 EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
510 EVP_CIPHER_CTX_set_key_length(&ctx, 10);
511 /* We finished modifying parameters so now we can set key and IV */
512 EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
513
514 for(;;) {
515 inlen = fread(inbuf, 1, 1024, in);
516 if (inlen <= 0)
517 break;
518 if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf,
519 inlen)) {
520 /* Error */
521 EVP_CIPHER_CTX_cleanup(&ctx);
522 return 0;
523 }
524 fwrite(outbuf, 1, outlen, out);
525 }
526 if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) {
527 /* Error */
528 EVP_CIPHER_CTX_cleanup(&ctx);
529 return 0;
530 }
531 fwrite(outbuf, 1, outlen, out);
532
533 EVP_CIPHER_CTX_cleanup(&ctx);
534 return 1;
535 }
536
537=head1 SEE ALSO
538
539L<evp(3)|evp(3)>
540
541=head1 HISTORY
542
543EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(),
544EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
545EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
546OpenSSL 0.9.7.
547
548=cut
diff --git a/src/lib/libcrypto/doc/EVP_OpenInit.pod b/src/lib/libcrypto/doc/EVP_OpenInit.pod
deleted file mode 100644
index 0242f66715..0000000000
--- a/src/lib/libcrypto/doc/EVP_OpenInit.pod
+++ /dev/null
@@ -1,61 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek,
12 int ekl,unsigned char *iv,EVP_PKEY *priv);
13 int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
14 int *outl, unsigned char *in, int inl);
15 int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
16 int *outl);
17
18=head1 DESCRIPTION
19
20The EVP envelope routines are a high level interface to envelope
21decryption. They decrypt a public key encrypted symmetric key and
22then decrypt data using it.
23
24EVP_OpenInit() initializes a cipher context B<ctx> for decryption
25with cipher B<type>. It decrypts the encrypted symmetric key of length
26B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>.
27The IV is supplied in the B<iv> parameter.
28
29EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties
30as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as
31documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual
32page.
33
34=head1 NOTES
35
36It is possible to call EVP_OpenInit() twice in the same way as
37EVP_DecryptInit(). The first call should have B<priv> set to NULL
38and (after setting any cipher parameters) it should be called again
39with B<type> set to NULL.
40
41If the cipher passed in the B<type> parameter is a variable length
42cipher then the key length will be set to the value of the recovered
43key length. If the cipher is a fixed length cipher then the recovered
44key length must match the fixed cipher length.
45
46=head1 RETURN VALUES
47
48EVP_OpenInit() returns 0 on error or a non zero integer (actually the
49recovered secret key size) if successful.
50
51EVP_OpenUpdate() returns 1 for success or 0 for failure.
52
53EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success.
54
55=head1 SEE ALSO
56
57L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
58L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
59L<EVP_SealInit(3)|EVP_SealInit(3)>
60
61=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod
deleted file mode 100644
index e8776e1e67..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod
+++ /dev/null
@@ -1,135 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid,
6EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding,
7EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
8EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
9EVP_PKEY_CTX_set_dh_paramgen_prime_len,
10EVP_PKEY_CTX_set_dh_paramgen_generator,
11EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations
12
13=head1 SYNOPSIS
14
15 #include <openssl/evp.h>
16
17 int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
18 int cmd, int p1, void *p2);
19 int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
20 const char *value);
21
22 int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid);
23
24 #include <openssl/rsa.h>
25
26 int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
27
28 int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
29 int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
30 int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
31 int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
32
33 #include <openssl/dsa.h>
34 int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
35
36 #include <openssl/dh.h>
37 int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
38 int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
39
40 #include <openssl/ec.h>
41 int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
42
43=head1 DESCRIPTION
44
45The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
46B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter
47B<optype> is a mask indicating which operations the control can be applied to.
48The control command is indicated in B<cmd> and any additional arguments in
49B<p1> and B<p2>.
50
51Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
52instead call one of the algorithm specific macros below.
53
54The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
55specific control operation to a context B<ctx> in string form. This is
56intended to be used for options specified on the command line or in text
57files. The commands supported are documented in the openssl utility
58command line pages for the option B<-pkeyopt> which is supported by the
59B<pkeyutl>, B<genpkey> and B<req> commands.
60
61All the remaining "functions" are implemented as macros.
62
63The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
64in a signature. It can be used with any public key algorithm supporting
65signature operations.
66
67The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>.
68The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding,
69RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding,
70RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only),
71RSA_X931_PADDING for X9.31 padding (signature operations only) and
72RSA_PKCS1_PSS_PADDING (sign and verify only).
73
74Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() is
75used. If this macro is called for PKCS#1 padding the plaintext buffer is an
76actual digest value and is encapsulated in a DigestInfo structure according to
77PKCS#1 when signing and this structure is expected (and stripped off) when
78verifying. If this control is not used with RSA and PKCS#1 padding then the
79supplied data is used directly and not encapsulated. In the case of X9.31
80padding for RSA the algorithm identifier byte is added or checked and removed
81if this control is called. If it is not called then the first byte of the
82plaintext buffer is expected to be the algorithm identifier byte.
83
84The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
85B<len> as its name implies it is only supported for PSS padding. Two special
86values are supported: -1 sets the salt length to the digest length. When
87signing -2 sets the salt length to the maximum permissible value. When
88verifying -2 causes the salt length to be automatically determined based on the
89B<PSS> block structure. If this macro is not called a salt length value of -2
90is used by default.
91
92The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for
93RSA key generation to B<bits>. If not specified 1024 bits is used.
94
95The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value
96for RSA key generation to B<pubexp> currently it should be an odd integer. The
97B<pubexp> pointer is used internally by this function so it should not be
98modified or free after the call. If this macro is not called then 65537 is used.
99
100The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used
101for DSA parameter generation to B<bits>. If not specified 1024 is used.
102
103The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH
104prime parameter B<p> for DH parameter generation. If this macro is not called
105then 1024 is used.
106
107The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
108for DH parameter generation. If not specified 2 is used.
109
110The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
111generation to B<nid>. For EC parameter generation this macro must be called
112or an error occurs because there is no default curve.
113
114=head1 RETURN VALUES
115
116EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0
117or a negative value for failure. In particular a return value of -2
118indicates the operation is not supported by the public key algorithm.
119
120=head1 SEE ALSO
121
122L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
123L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
124L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
125L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
126L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
127L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
128L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
129L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>
130
131=head1 HISTORY
132
133These functions were first added to OpenSSL 1.0.0.
134
135=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod
deleted file mode 100644
index 60ad61e853..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod
+++ /dev/null
@@ -1,53 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free -
6public key algorithm context functions.
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
13 EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
14 EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
15 void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
16
17=head1 DESCRIPTION
18
19The EVP_PKEY_CTX_new() function allocates public key algorithm context using
20the algorithm specified in B<pkey> and ENGINE B<e>.
21
22The EVP_PKEY_CTX_new_id() function allocates public key algorithm context
23using the algorithm specified by B<id> and ENGINE B<e>. It is normally used
24when no B<EVP_PKEY> structure is associated with the operations, for example
25during parameter generation of key generation for some algorithms.
26
27EVP_PKEY_CTX_dup() duplicates the context B<ctx>.
28
29EVP_PKEY_CTX_free() frees up the context B<ctx>.
30
31=head1 NOTES
32
33The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used
34by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
35threads: that is it is not permissible to use the same context simultaneously
36in two threads.
37
38=head1 RETURN VALUES
39
40EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either
41the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred.
42
43EVP_PKEY_CTX_free() does not return a value.
44
45=head1 SEE ALSO
46
47L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>
48
49=head1 HISTORY
50
51These functions were first added to OpenSSL 1.0.0.
52
53=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod b/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod
deleted file mode 100644
index 7a690247bf..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod
+++ /dev/null
@@ -1,62 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters,
6EVP_PKEY_cmp - public key parameter and comparison functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey);
13 int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from);
14
15 int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b);
16 int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b);
17
18=head1 DESCRIPTION
19
20The function EVP_PKEY_missing_parameters() returns 1 if the public key
21parameters of B<pkey> are missing and 0 if they are present or the algorithm
22doesn't use parameters.
23
24The function EVP_PKEY_copy_parameters() copies the parameters from key
25B<from> to key B<to>.
26
27The function EVP_PKEY_cmp_parameters() compares the parameters of keys
28B<a> and B<b>.
29
30The function EVP_PKEY_cmp() compares the public key components and parameters
31(if present) of keys B<a> and B<b>.
32
33=head1 NOTES
34
35The main purpose of the functions EVP_PKEY_missing_parameters() and
36EVP_PKEY_copy_parameters() is to handle public keys in certificates where the
37parameters are sometimes omitted from a public key if they are inherited from
38the CA that signed it.
39
40Since OpenSSL private keys contain public key components too the function
41EVP_PKEY_cmp() can also be used to determine if a private key matches
42a public key.
43
44=head1 RETURN VALUES
45
46The function EVP_PKEY_missing_parameters() returns 1 if the public key
47parameters of B<pkey> are missing and 0 if they are present or the algorithm
48doesn't use parameters.
49
50These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for
51failure.
52
53The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the
54keys match, 0 if they don't match, -1 if the key types are different and
55-2 if the operation is not supported.
56
57=head1 SEE ALSO
58
59L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
60L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>
61
62=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod
deleted file mode 100644
index a64ef12866..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod
+++ /dev/null
@@ -1,93 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);
12 int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx,
13 unsigned char *out, size_t *outlen,
14 const unsigned char *in, size_t inlen);
15
16=head1 DESCRIPTION
17
18The EVP_PKEY_decrypt_init() function initializes a public key algorithm
19context using key B<pkey> for a decryption operation.
20
21The EVP_PKEY_decrypt() function performs a public key decryption operation
22using B<ctx>. The data to be decrypted is specified using the B<in> and
23B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
24buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
25before the call the B<outlen> parameter should contain the length of the
26B<out> buffer, if the call is successful the decrypted data is written to
27B<out> and the amount of data written to B<outlen>.
28
29=head1 NOTES
30
31After the call to EVP_PKEY_decrypt_init() algorithm specific control
32operations can be performed to set any appropriate parameters for the
33operation.
34
35The function EVP_PKEY_decrypt() can be called more than once on the same
36context if several operations are performed using the same parameters.
37
38=head1 RETURN VALUES
39
40EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
41or a negative value for failure. In particular a return value of -2
42indicates the operation is not supported by the public key algorithm.
43
44=head1 EXAMPLE
45
46Decrypt data using OAEP (for RSA keys):
47
48 #include <openssl/evp.h>
49 #include <openssl/rsa.h>
50
51 EVP_PKEY_CTX *ctx;
52 unsigned char *out, *in;
53 size_t outlen, inlen;
54 EVP_PKEY *key;
55 /* NB: assumes key in, inlen are already set up
56 * and that key is an RSA private key
57 */
58 ctx = EVP_PKEY_CTX_new(key);
59 if (!ctx)
60 /* Error occurred */
61 if (EVP_PKEY_decrypt_init(ctx) <= 0)
62 /* Error */
63 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)
64 /* Error */
65
66 /* Determine buffer length */
67 if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0)
68 /* Error */
69
70 out = malloc(outlen);
71
72 if (!out)
73 /* malloc failure */
74
75 if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0)
76 /* Error */
77
78 /* Decrypted data is outlen bytes written to buffer out */
79
80=head1 SEE ALSO
81
82L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
83L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
84L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
85L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
86L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
87L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
88
89=head1 HISTORY
90
91These functions were first added to OpenSSL 1.0.0.
92
93=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod b/src/lib/libcrypto/doc/EVP_PKEY_derive.pod
deleted file mode 100644
index 09654e1b81..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod
+++ /dev/null
@@ -1,94 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public
6key algorithm shared secret.
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
13 int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
14 int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
15
16=head1 DESCRIPTION
17
18The EVP_PKEY_derive_init() function initializes a public key algorithm
19context using key B<pkey> for shared secret derivation.
20
21The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
22be a public key.
23
24The EVP_PKEY_derive() derives a shared secret using B<ctx>.
25If B<key> is B<NULL> then the maximum size of the output buffer is written to
26the B<keylen> parameter. If B<key> is not B<NULL> then before the call the
27B<keylen> parameter should contain the length of the B<key> buffer, if the call
28is successful the shared secret is written to B<key> and the amount of data
29written to B<keylen>.
30
31=head1 NOTES
32
33After the call to EVP_PKEY_derive_init() algorithm specific control
34operations can be performed to set any appropriate parameters for the
35operation.
36
37The function EVP_PKEY_derive() can be called more than once on the same
38context if several operations are performed using the same parameters.
39
40=head1 RETURN VALUES
41
42EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
43or a negative value for failure. In particular a return value of -2
44indicates the operation is not supported by the public key algorithm.
45
46=head1 EXAMPLE
47
48Derive shared secret (for example DH or EC keys):
49
50 #include <openssl/evp.h>
51 #include <openssl/rsa.h>
52
53 EVP_PKEY_CTX *ctx;
54 unsigned char *skey;
55 size_t skeylen;
56 EVP_PKEY *pkey, *peerkey;
57 /* NB: assumes pkey, peerkey have been already set up */
58
59 ctx = EVP_PKEY_CTX_new(pkey);
60 if (!ctx)
61 /* Error occurred */
62 if (EVP_PKEY_derive_init(ctx) <= 0)
63 /* Error */
64 if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
65 /* Error */
66
67 /* Determine buffer length */
68 if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
69 /* Error */
70
71 skey = malloc(skeylen);
72
73 if (!skey)
74 /* malloc failure */
75
76 if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
77 /* Error */
78
79 /* Shared secret is skey bytes written to buffer skey */
80
81=head1 SEE ALSO
82
83L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
84L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
85L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
86L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
87L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
88L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
89
90=head1 HISTORY
91
92These functions were first added to OpenSSL 1.0.0.
93
94=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod
deleted file mode 100644
index b3ca123df0..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod
+++ /dev/null
@@ -1,93 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);
12 int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx,
13 unsigned char *out, size_t *outlen,
14 const unsigned char *in, size_t inlen);
15
16=head1 DESCRIPTION
17
18The EVP_PKEY_encrypt_init() function initializes a public key algorithm
19context using key B<pkey> for an encryption operation.
20
21The EVP_PKEY_encrypt() function performs a public key encryption operation
22using B<ctx>. The data to be encrypted is specified using the B<in> and
23B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output
24buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then
25before the call the B<outlen> parameter should contain the length of the
26B<out> buffer, if the call is successful the encrypted data is written to
27B<out> and the amount of data written to B<outlen>.
28
29=head1 NOTES
30
31After the call to EVP_PKEY_encrypt_init() algorithm specific control
32operations can be performed to set any appropriate parameters for the
33operation.
34
35The function EVP_PKEY_encrypt() can be called more than once on the same
36context if several operations are performed using the same parameters.
37
38=head1 RETURN VALUES
39
40EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
41or a negative value for failure. In particular a return value of -2
42indicates the operation is not supported by the public key algorithm.
43
44=head1 EXAMPLE
45
46Encrypt data using OAEP (for RSA keys):
47
48 #include <openssl/evp.h>
49 #include <openssl/rsa.h>
50
51 EVP_PKEY_CTX *ctx;
52 unsigned char *out, *in;
53 size_t outlen, inlen;
54 EVP_PKEY *key;
55 /* NB: assumes key in, inlen are already set up
56 * and that key is an RSA public key
57 */
58 ctx = EVP_PKEY_CTX_new(key);
59 if (!ctx)
60 /* Error occurred */
61 if (EVP_PKEY_encrypt_init(ctx) <= 0)
62 /* Error */
63 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0)
64 /* Error */
65
66 /* Determine buffer length */
67 if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0)
68 /* Error */
69
70 out = malloc(outlen);
71
72 if (!out)
73 /* malloc failure */
74
75 if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0)
76 /* Error */
77
78 /* Encrypted data is outlen bytes written to buffer out */
79
80=head1 SEE ALSO
81
82L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
83L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
84L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
85L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
86L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
87L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
88
89=head1 HISTORY
90
91These functions were first added to OpenSSL 1.0.0.
92
93=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod b/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod
deleted file mode 100644
index 8ff597d44a..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod
+++ /dev/null
@@ -1,41 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_get_default_digest_nid - get default signature digest
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10 int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid);
11
12=head1 DESCRIPTION
13
14The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default
15message digest NID for the public key signature operations associated with key
16B<pkey>.
17
18=head1 NOTES
19
20For all current standard OpenSSL public key algorithms SHA1 is returned.
21
22=head1 RETURN VALUES
23
24The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest
25is advisory (that is other digests can be used) and 2 if it is mandatory (other
26digests can not be used). It returns 0 or a negative value for failure. In
27particular a return value of -2 indicates the operation is not supported by the
28public key algorithm.
29
30=head1 SEE ALSO
31
32L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
33L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
34L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
35L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
36
37=head1 HISTORY
38
39This function was first added to OpenSSL 1.0.0.
40
41=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod b/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod
deleted file mode 100644
index adcf3560e0..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod
+++ /dev/null
@@ -1,170 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init,
6EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
7EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
8EVP_PKEY_CTX_get_app_data - key and parameter generation functions
9
10=head1 SYNOPSIS
11
12 #include <openssl/evp.h>
13
14 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
15 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
16 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
17 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
18
19 typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
20
21 void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
22 EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
23
24 int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
25
26 void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
27 void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);
28
29=head1 DESCRIPTION
30
31The EVP_PKEY_keygen_init() function initializes a public key algorithm
32context using key B<pkey> for a key generation operation.
33
34The EVP_PKEY_keygen() function performs a key generation operation, the
35generated key is written to B<ppkey>.
36
37The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar
38except parameters are generated.
39
40The function EVP_PKEY_set_cb() sets the key or parameter generation callback
41to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
42generation callback.
43
44The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated
45with the generation operation. If B<idx> is -1 the total number of
46parameters available is returned. Any non negative value returns the value of
47that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
48B<idx> should only be called within the generation callback.
49
50If the callback returns 0 then the key generation operation is aborted and an
51error occurs. This might occur during a time consuming operation where
52a user clicks on a "cancel" button.
53
54The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set
55and retrieve an opaque pointer. This can be used to set some application
56defined value which can be retrieved in the callback: for example a handle
57which is used to update a "progress dialog".
58
59=head1 NOTES
60
61After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
62specific control operations can be performed to set any appropriate parameters
63for the operation.
64
65The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than
66once on the same context if several operations are performed using the same
67parameters.
68
69The meaning of the parameters passed to the callback will depend on the
70algorithm and the specific implementation of the algorithm. Some might not
71give any useful information at all during key or parameter generation. Others
72might not even call the callback.
73
74The operation performed by key or parameter generation depends on the algorithm
75used. In some cases (e.g. EC with a supplied named curve) the "generation"
76option merely sets the appropriate fields in an EVP_PKEY structure.
77
78In OpenSSL an EVP_PKEY structure containing a private key also contains the
79public key components and parameters (if any). An OpenSSL private key is
80equivalent to what some libraries call a "key pair". A private key can be used
81in functions which require the use of a public key or parameters.
82
83=head1 RETURN VALUES
84
85EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
86EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
87In particular a return value of -2 indicates the operation is not supported by
88the public key algorithm.
89
90=head1 EXAMPLES
91
92Generate a 2048 bit RSA key:
93
94 #include <openssl/evp.h>
95 #include <openssl/rsa.h>
96
97 EVP_PKEY_CTX *ctx;
98 EVP_PKEY *pkey = NULL;
99 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
100 if (!ctx)
101 /* Error occurred */
102 if (EVP_PKEY_keygen_init(ctx) <= 0)
103 /* Error */
104 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
105 /* Error */
106
107 /* Generate key */
108 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
109 /* Error */
110
111Generate a key from a set of parameters:
112
113 #include <openssl/evp.h>
114 #include <openssl/rsa.h>
115
116 EVP_PKEY_CTX *ctx;
117 EVP_PKEY *pkey = NULL, *param;
118 /* Assumed param is set up already */
119 ctx = EVP_PKEY_CTX_new(param);
120 if (!ctx)
121 /* Error occurred */
122 if (EVP_PKEY_keygen_init(ctx) <= 0)
123 /* Error */
124
125 /* Generate key */
126 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
127 /* Error */
128
129Example of generation callback for OpenSSL public key implementations:
130
131 /* Application data is a BIO to output status to */
132
133 EVP_PKEY_CTX_set_app_data(ctx, status_bio);
134
135 static int
136 genpkey_cb(EVP_PKEY_CTX *ctx)
137 {
138 char c = '*';
139 BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
140 int p;
141
142 p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
143 if (p == 0)
144 c='.';
145 if (p == 1)
146 c='+';
147 if (p == 2)
148 c='*';
149 if (p == 3)
150 c='\n';
151 BIO_write(b,&c,1);
152 (void)BIO_flush(b);
153 return 1;
154 }
155
156=head1 SEE ALSO
157
158L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
159L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
160L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
161L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
162L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
163L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
164L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
165
166=head1 HISTORY
167
168These functions were first added to OpenSSL 1.0.0.
169
170=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_new.pod
deleted file mode 100644
index 7792714659..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_new.pod
+++ /dev/null
@@ -1,43 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_new, EVP_PKEY_free - private key allocation functions.
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 EVP_PKEY *EVP_PKEY_new(void);
12 void EVP_PKEY_free(EVP_PKEY *key);
13
14
15=head1 DESCRIPTION
16
17The EVP_PKEY_new() function allocates an empty B<EVP_PKEY>
18structure which is used by OpenSSL to store private keys.
19
20EVP_PKEY_free() frees up the private key B<key>.
21
22=head1 NOTES
23
24The B<EVP_PKEY> structure is used by various OpenSSL functions
25which require a general private key without reference to any
26particular algorithm.
27
28The structure returned by EVP_PKEY_new() is empty. To add a
29private key to this empty structure the functions described in
30L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> should be used.
31
32=head1 RETURN VALUES
33
34EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY>
35structure of B<NULL> if an error occurred.
36
37EVP_PKEY_free() does not return a value.
38
39=head1 SEE ALSO
40
41L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>
42
43=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod b/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod
deleted file mode 100644
index eabbaed264..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod
+++ /dev/null
@@ -1,54 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public
6key algorithm printing routines.
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey,
13 int indent, ASN1_PCTX *pctx);
14 int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey,
15 int indent, ASN1_PCTX *pctx);
16 int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey,
17 int indent, ASN1_PCTX *pctx);
18
19=head1 DESCRIPTION
20
21The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and
22EVP_PKEY_print_params() print out the public, private or parameter components
23of key B<pkey> respectively. The key is sent to BIO B<out> in human readable
24form. The parameter B<indent> indicated how far the printout should be indented.
25
26The B<pctx> parameter allows the print output to be finely tuned by using
27ASN1 printing options. If B<pctx> is set to NULL then default values will
28be used.
29
30=head1 NOTES
31
32Currently no public key algorithms include any options in the B<pctx> parameter
33parameter.
34
35If the key does not include all the components indicated by the function then
36only those contained in the key will be printed. For example passing a public
37key to EVP_PKEY_print_private() will only print the public components.
38
39=head1 RETURN VALUES
40
41These functions all return 1 for success and 0 or a negative value for failure.
42In particular a return value of -2 indicates the operation is not supported by
43the public key algorithm.
44
45=head1 SEE ALSO
46
47L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
48L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>
49
50=head1 HISTORY
51
52These functions were first added to OpenSSL 1.0.0.
53
54=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod b/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod
deleted file mode 100644
index 096e969fa3..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod
+++ /dev/null
@@ -1,76 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
6EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
7EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
8EVP_PKEY_assign_EC_KEY, EVP_PKEY_type - EVP_PKEY assignment functions.
9
10=head1 SYNOPSIS
11
12 #include <openssl/evp.h>
13
14 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key);
15 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key);
16 int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key);
17 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
18
19 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
20 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
21 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
22 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
23
24 int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key);
25 int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key);
26 int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key);
27 int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key);
28
29 int EVP_PKEY_type(int type);
30
31=head1 DESCRIPTION
32
33EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
34EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>.
35
36EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
37EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
38B<NULL> if the key is not of the correct type.
39
40EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
41and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
42however these use the supplied B<key> internally and so B<key>
43will be freed when the parent B<pkey> is freed.
44
45EVP_PKEY_type() returns the type of key corresponding to the value
46B<type>. The type of a key can be obtained with
47EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA,
48EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding
49key types or NID_undef if the key type is unassigned.
50
51=head1 NOTES
52
53In accordance with the OpenSSL naming convention the key obtained
54from or assigned to the B<pkey> using the B<1> functions must be
55freed as well as B<pkey>.
56
57EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
58EVP_PKEY_assign_EC_KEY() are implemented as macros.
59
60=head1 RETURN VALUES
61
62EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
63EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
64
65EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
66EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
67an error occurred.
68
69EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
70and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
71
72=head1 SEE ALSO
73
74L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>
75
76=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod b/src/lib/libcrypto/doc/EVP_PKEY_sign.pod
deleted file mode 100644
index 1925706d96..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod
+++ /dev/null
@@ -1,96 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
12 int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
13 unsigned char *sig, size_t *siglen,
14 const unsigned char *tbs, size_t tbslen);
15
16=head1 DESCRIPTION
17
18The EVP_PKEY_sign_init() function initializes a public key algorithm
19context using key B<pkey> for a signing operation.
20
21The EVP_PKEY_sign() function performs a public key signing operation
22using B<ctx>. The data to be signed is specified using the B<tbs> and
23B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output
24buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then
25before the call the B<siglen> parameter should contain the length of the
26B<sig> buffer, if the call is successful the signature is written to
27B<sig> and the amount of data written to B<siglen>.
28
29=head1 NOTES
30
31After the call to EVP_PKEY_sign_init() algorithm specific control
32operations can be performed to set any appropriate parameters for the
33operation.
34
35The function EVP_PKEY_sign() can be called more than once on the same
36context if several operations are performed using the same parameters.
37
38=head1 RETURN VALUES
39
40EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
41or a negative value for failure. In particular a return value of -2
42indicates the operation is not supported by the public key algorithm.
43
44=head1 EXAMPLE
45
46Sign data using RSA with PKCS#1 padding and SHA256 digest:
47
48 #include <openssl/evp.h>
49 #include <openssl/rsa.h>
50
51 EVP_PKEY_CTX *ctx;
52 unsigned char *md, *sig;
53 size_t mdlen, siglen;
54 EVP_PKEY *signing_key;
55 /* NB: assumes signing_key, md and mdlen are already set up
56 * and that signing_key is an RSA private key
57 */
58 ctx = EVP_PKEY_CTX_new(signing_key);
59 if (!ctx)
60 /* Error occurred */
61 if (EVP_PKEY_sign_init(ctx) <= 0)
62 /* Error */
63 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
64 /* Error */
65 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
66 /* Error */
67
68 /* Determine buffer length */
69 if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
70 /* Error */
71
72 sig = malloc(siglen);
73
74 if (!sig)
75 /* malloc failure */
76
77 if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
78 /* Error */
79
80 /* Signature is siglen bytes written to buffer sig */
81
82
83=head1 SEE ALSO
84
85L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
86L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
87L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
88L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
89L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
90L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
91
92=head1 HISTORY
93
94These functions were first added to OpenSSL 1.0.0.
95
96=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify.pod
deleted file mode 100644
index 0f092ca8e1..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod
+++ /dev/null
@@ -1,92 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public
6key algorithm
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
13 int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
14 const unsigned char *sig, size_t siglen,
15 const unsigned char *tbs, size_t tbslen);
16
17=head1 DESCRIPTION
18
19The EVP_PKEY_verify_init() function initializes a public key algorithm
20context using key B<pkey> for a signature verification operation.
21
22The EVP_PKEY_verify() function performs a public key verification operation
23using B<ctx>. The signature is specified using the B<sig> and
24B<siglen> parameters. The verified data (i.e. the data believed originally
25signed) is specified using the B<tbs> and B<tbslen> parameters.
26
27=head1 NOTES
28
29After the call to EVP_PKEY_verify_init() algorithm specific control
30operations can be performed to set any appropriate parameters for the
31operation.
32
33The function EVP_PKEY_verify() can be called more than once on the same
34context if several operations are performed using the same parameters.
35
36=head1 RETURN VALUES
37
38EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was
39successful and 0 if it failed. Unlike other functions the return value 0 from
40EVP_PKEY_verify() only indicates that the signature did not verify
41successfully (that is tbs did not match the original data or the signature was
42of invalid form) it is not an indication of a more serious error.
43
44A negative value indicates an error other that signature verification failure.
45In particular a return value of -2 indicates the operation is not supported by
46the public key algorithm.
47
48=head1 EXAMPLE
49
50Verify signature using PKCS#1 and SHA256 digest:
51
52 #include <openssl/evp.h>
53 #include <openssl/rsa.h>
54
55 EVP_PKEY_CTX *ctx;
56 unsigned char *md, *sig;
57 size_t mdlen, siglen;
58 EVP_PKEY *verify_key;
59 /* NB: assumes verify_key, sig, siglen md and mdlen are already set up
60 * and that verify_key is an RSA public key
61 */
62 ctx = EVP_PKEY_CTX_new(verify_key);
63 if (!ctx)
64 /* Error occurred */
65 if (EVP_PKEY_verify_init(ctx) <= 0)
66 /* Error */
67 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
68 /* Error */
69 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
70 /* Error */
71
72 /* Perform operation */
73 ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
74
75 /* ret == 1 indicates success, 0 verify failure and < 0 for some
76 * other error.
77 */
78
79=head1 SEE ALSO
80
81L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
82L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
83L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
84L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
85L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
86L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
87
88=head1 HISTORY
89
90These functions were first added to OpenSSL 1.0.0.
91
92=cut
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod
deleted file mode 100644
index 095e53ea2f..0000000000
--- a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod
+++ /dev/null
@@ -1,105 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using
6a public key algorithm
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
13 int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
14 unsigned char *rout, size_t *routlen,
15 const unsigned char *sig, size_t siglen);
16
17=head1 DESCRIPTION
18
19The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
20context using key B<pkey> for a verify recover operation.
21
22The EVP_PKEY_verify_recover() function recovers signed data
23using B<ctx>. The signature is specified using the B<sig> and
24B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output
25buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then
26before the call the B<routlen> parameter should contain the length of the
27B<rout> buffer, if the call is successful recovered data is written to
28B<rout> and the amount of data written to B<routlen>.
29
30=head1 NOTES
31
32Normally an application is only interested in whether a signature verification
33operation is successful in those cases the EVP_verify() function should be
34used.
35
36Sometimes however it is useful to obtain the data originally signed using a
37signing operation. Only certain public key algorithms can recover a signature
38in this way (for example RSA in PKCS padding mode).
39
40After the call to EVP_PKEY_verify_recover_init() algorithm specific control
41operations can be performed to set any appropriate parameters for the
42operation.
43
44The function EVP_PKEY_verify_recover() can be called more than once on the same
45context if several operations are performed using the same parameters.
46
47=head1 RETURN VALUES
48
49EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for
50success
51and 0 or a negative value for failure. In particular a return value of -2
52indicates the operation is not supported by the public key algorithm.
53
54=head1 EXAMPLE
55
56Recover digest originally signed using PKCS#1 and SHA256 digest:
57
58 #include <openssl/evp.h>
59 #include <openssl/rsa.h>
60
61 EVP_PKEY_CTX *ctx;
62 unsigned char *rout, *sig;
63 size_t routlen, siglen;
64 EVP_PKEY *verify_key;
65 /* NB: assumes verify_key, sig and siglen are already set up
66 * and that verify_key is an RSA public key
67 */
68 ctx = EVP_PKEY_CTX_new(verify_key);
69 if (!ctx)
70 /* Error occurred */
71 if (EVP_PKEY_verify_recover_init(ctx) <= 0)
72 /* Error */
73 if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
74 /* Error */
75 if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
76 /* Error */
77
78 /* Determine buffer length */
79 if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
80 /* Error */
81
82 rout = malloc(routlen);
83
84 if (!rout)
85 /* malloc failure */
86
87 if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
88 /* Error */
89
90 /* Recovered data is routlen bytes written to buffer rout */
91
92=head1 SEE ALSO
93
94L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
95L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
96L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
97L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
98L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
99L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
100
101=head1 HISTORY
102
103These functions were first added to OpenSSL 1.0.0.
104
105=cut
diff --git a/src/lib/libcrypto/doc/EVP_SealInit.pod b/src/lib/libcrypto/doc/EVP_SealInit.pod
deleted file mode 100644
index 76eebb72a9..0000000000
--- a/src/lib/libcrypto/doc/EVP_SealInit.pod
+++ /dev/null
@@ -1,82 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
12 unsigned char **ek, int *ekl, unsigned char *iv,
13 EVP_PKEY **pubk, int npubk);
14 int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
15 int *outl, unsigned char *in, int inl);
16 int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
17 int *outl);
18
19=head1 DESCRIPTION
20
21The EVP envelope routines are a high level interface to envelope
22encryption. They generate a random key and IV (if required) then
23"envelope" it by using public key encryption. Data can then be
24encrypted using this key.
25
26EVP_SealInit() initializes a cipher context B<ctx> for encryption
27with cipher B<type> using a random secret key and IV. B<type> is normally
28supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted
29using one or more public keys, this allows the same encrypted data to be
30decrypted using any of the corresponding private keys. B<ek> is an array of
31buffers where the public key encrypted secret key will be written, each buffer
32must contain enough room for the corresponding encrypted key: that is
33B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual
34size of each encrypted secret key is written to the array B<ekl>. B<pubk> is
35an array of B<npubk> public keys.
36
37The B<iv> parameter is a buffer where the generated IV is written to. It must
38contain enough room for the corresponding cipher's IV, as determined by (for
39example) EVP_CIPHER_iv_length(type).
40
41If the cipher does not require an IV then the B<iv> parameter is ignored
42and can be B<NULL>.
43
44EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties
45as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as
46documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual
47page.
48
49=head1 RETURN VALUES
50
51EVP_SealInit() returns 0 on error or B<npubk> if successful.
52
53EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
54failure.
55
56=head1 NOTES
57
58The public key must be RSA because it is the only OpenSSL public key
59algorithm that supports key transport.
60
61Envelope encryption is the usual method of using public key encryption
62on large amounts of data, this is because public key encryption is slow
63but symmetric encryption is fast. So symmetric encryption is used for
64bulk encryption and the small random symmetric key used is transferred
65using public key encryption.
66
67It is possible to call EVP_SealInit() twice in the same way as
68EVP_EncryptInit(). The first call should have B<npubk> set to 0
69and (after setting any cipher parameters) it should be called again
70with B<type> set to NULL.
71
72=head1 SEE ALSO
73
74L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
75L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
76L<EVP_OpenInit(3)|EVP_OpenInit(3)>
77
78=head1 HISTORY
79
80EVP_SealFinal() did not return a value before OpenSSL 0.9.7.
81
82=cut
diff --git a/src/lib/libcrypto/doc/EVP_SignInit.pod b/src/lib/libcrypto/doc/EVP_SignInit.pod
deleted file mode 100644
index 6882211e02..0000000000
--- a/src/lib/libcrypto/doc/EVP_SignInit.pod
+++ /dev/null
@@ -1,103 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_SignInit, EVP_SignUpdate, EVP_SignFinal, EVP_PKEY_size
6- EVP signing functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
13 int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
14 int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
15
16 void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
17
18 int EVP_PKEY_size(EVP_PKEY *pkey);
19
20=head1 DESCRIPTION
21
22The EVP signature routines are a high level interface to digital
23signatures.
24
25EVP_SignInit_ex() sets up signing context B<ctx> to use digest
26B<type> from ENGINE B<impl>. B<ctx> must be initialized with
27EVP_MD_CTX_init() before calling this function.
28
29EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the
30signature context B<ctx>. This function can be called several times on the
31same B<ctx> to include additional data.
32
33EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
34places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
35bytes in size. B<s> is an OUT parameter, and not used as an IN parameter.
36The number of bytes of data written (i.e. the length of the signature)
37will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
38will be written.
39
40EVP_SignInit() initializes a signing context B<ctx> to use the default
41implementation of digest B<type>.
42
43EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual
44signature returned by EVP_SignFinal() may be smaller.
45
46=head1 RETURN VALUES
47
48EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1
49for success and 0 for failure.
50
51EVP_PKEY_size() returns the maximum size of a signature in bytes.
52
53The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
54
55=head1 NOTES
56
57The B<EVP> interface to digital signatures should almost always be used in
58preference to the low level interfaces. This is because the code then becomes
59transparent to the algorithm used and much more flexible.
60
61Due to the link between message digests and public key algorithms the correct
62digest algorithm must be used with the correct public key type. A list of
63algorithms and associated public key algorithms appears in
64L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
65
66The call to EVP_SignFinal() internally finalizes a copy of the digest context.
67This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
68later to digest and sign additional data.
69
70Since only a copy of the digest context is ever finalized the context must
71be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
72will occur.
73
74=head1 BUGS
75
76Older versions of this documentation wrongly stated that calls to
77EVP_SignUpdate() could not be made after calling EVP_SignFinal().
78
79Since the private key is passed in the call to EVP_SignFinal() any error
80relating to the private key (for example an unsuitable key and digest
81combination) will not be indicated until after potentially large amounts of
82data have been passed through EVP_SignUpdate().
83
84It is not possible to change the signing parameters using these function.
85
86The previous two bugs are fixed in the newer EVP_SignDigest*() function.
87
88=head1 SEE ALSO
89
90L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
91L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
92L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
93L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>,
94L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
95
96=head1 HISTORY
97
98EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are
99available in all versions of SSLeay and OpenSSL.
100
101EVP_SignInit_ex() was added in OpenSSL 0.9.7.
102
103=cut
diff --git a/src/lib/libcrypto/doc/EVP_VerifyInit.pod b/src/lib/libcrypto/doc/EVP_VerifyInit.pod
deleted file mode 100644
index b0d3f8e4c9..0000000000
--- a/src/lib/libcrypto/doc/EVP_VerifyInit.pod
+++ /dev/null
@@ -1,96 +0,0 @@
1=pod
2
3=head1 NAME
4
5EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification
6functions
7
8=head1 SYNOPSIS
9
10 #include <openssl/evp.h>
11
12 int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
13 int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
14 int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey);
15
16 int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
17
18=head1 DESCRIPTION
19
20The EVP signature verification routines are a high level interface to digital
21signatures.
22
23EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
24B<type> from ENGINE B<impl>. B<ctx> must be initialized by calling
25EVP_MD_CTX_init() before calling this function.
26
27EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
28verification context B<ctx>. This function can be called several times on the
29same B<ctx> to include additional data.
30
31EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
32and against the B<siglen> bytes at B<sigbuf>.
33
34EVP_VerifyInit() initializes verification context B<ctx> to use the default
35implementation of digest B<type>.
36
37=head1 RETURN VALUES
38
39EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
40failure.
41
42EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if
43some other error occurred.
44
45The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
46
47=head1 NOTES
48
49The B<EVP> interface to digital signatures should almost always be used in
50preference to the low level interfaces. This is because the code then becomes
51transparent to the algorithm used and much more flexible.
52
53Due to the link between message digests and public key algorithms the correct
54digest algorithm must be used with the correct public key type. A list of
55algorithms and associated public key algorithms appears in
56L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
57
58The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
59This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
60later to digest and verify additional data.
61
62Since only a copy of the digest context is ever finalized the context must
63be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
64will occur.
65
66=head1 BUGS
67
68Older versions of this documentation wrongly stated that calls to
69EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
70
71Since the public key is passed in the call to EVP_SignFinal() any error
72relating to the private key (for example an unsuitable key and digest
73combination) will not be indicated until after potentially large amounts of
74data have been passed through EVP_SignUpdate().
75
76It is not possible to change the signing parameters using these function.
77
78The previous two bugs are fixed in the newer EVP_VerifyDigest*() function.
79
80=head1 SEE ALSO
81
82L<evp(3)|evp(3)>,
83L<EVP_SignInit(3)|EVP_SignInit(3)>,
84L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
85L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
86L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>,
87L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
88
89=head1 HISTORY
90
91EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are
92available in all versions of SSLeay and OpenSSL.
93
94EVP_VerifyInit_ex() was added in OpenSSL 0.9.7
95
96=cut
diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod
deleted file mode 100644
index dfd96d3b98..0000000000
--- a/src/lib/libcrypto/doc/evp.pod
+++ /dev/null
@@ -1,107 +0,0 @@
1=pod
2
3=head1 NAME
4
5evp - high-level cryptographic functions
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11=head1 DESCRIPTION
12
13The EVP library provides a high-level interface to cryptographic
14functions.
15
16L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)>
17provide public key encryption and decryption to implement digital "envelopes".
18
19The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and
20L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement
21digital signatures and Message Authentication Codes (MACs). Also see the older
22L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)>
23functions.
24
25Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)>
26functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests.
27
28Authenticated encryption with additional data (AEAD) is available with
29the L<B<EVP_AEAD>I<...>|EVP_AEAD_CTX_init(3)> functions.
30
31The B<EVP_PKEY>I<...> functions provide a high level interface to
32asymmetric algorithms. To create a new EVP_PKEY see
33L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated
34with a private key of a particular algorithm by using the functions
35described on the L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> page, or
36new keys can be generated using L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>.
37EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)|EVP_PKEY_cmp(3)>, or printed using
38L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>.
39
40The EVP_PKEY functions support the full range of asymmetric algorithm operations:
41
42=over
43
44=item For key agreement see L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
45
46=item For signing and verifying see L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
47L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>.
48However, note that
49these functions do not perform a digest of the data to be signed. Therefore
50normally you would use the L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)>
51functions for this purpose.
52
53=item For encryption and decryption see L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>
54and L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)> respectively. However, note that
55these functions perform encryption and decryption only. As public key
56encryption is an expensive operation, normally you would wrap
57an encrypted message in a "digital envelope" using the L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and
58L<B<EVP_Open>I<...>|EVP_OpenInit(3)> functions.
59
60=back
61
62The L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> function provides some limited support for password
63based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible
64implementation. However, new applications should not typically use this (preferring, for example,
65PBKDF2 from PCKS#5).
66
67Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>.
68
69All the symmetric algorithms (ciphers), digests and asymmetric algorithms
70(public key algorithms) can be replaced by L<ENGINE|engine(3)> modules providing alternative
71implementations. If ENGINE implementations of ciphers or digests are registered
72as defaults, then the various EVP functions will automatically use those
73implementations automatically in preference to built in software
74implementations. For more information, consult the engine(3) man page.
75
76Although low level algorithm specific functions exist for many algorithms
77their use is discouraged. They cannot be used with an ENGINE and ENGINE
78versions of new algorithms cannot be accessed using the low level functions.
79Also makes code harder to adapt to new algorithms and some options are not
80cleanly supported at the low level and some operations are more efficient
81using the high level interface.
82
83=head1 SEE ALSO
84
85L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
86L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
87L<EVP_AEAD_CTX_init(3)|EVP_AEAD_CTX_init(3)>,
88L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
89L<EVP_SealInit(3)|EVP_SealInit(3)>,
90L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>,
91L<EVP_SignInit(3)|EVP_SignInit(3)>,
92L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
93L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>,
94L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>,
95L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>,
96L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>,
97L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
98L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
99L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
100L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
101L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
102L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>,
103L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>,
104L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>,
105L<engine(3)|engine(3)>
106
107=cut