summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod498
-rw-r--r--src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod41
-rw-r--r--src/lib/libcrypto/doc/PKCS12_create.pod73
-rw-r--r--src/lib/libcrypto/doc/PKCS12_parse.pod57
-rw-r--r--src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod64
-rw-r--r--src/lib/libcrypto/doc/PKCS7_decrypt.pod57
-rw-r--r--src/lib/libcrypto/doc/PKCS7_encrypt.pod73
-rw-r--r--src/lib/libcrypto/doc/PKCS7_sign.pod116
-rw-r--r--src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod87
-rw-r--r--src/lib/libcrypto/doc/PKCS7_verify.pod118
-rw-r--r--src/lib/libcrypto/doc/SMIME_read_PKCS7.pod73
-rw-r--r--src/lib/libcrypto/doc/SMIME_write_PKCS7.pod65
-rw-r--r--src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod44
-rw-r--r--src/lib/libcrypto/man/Makefile28
-rw-r--r--src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3997
-rw-r--r--src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.340
-rw-r--r--src/lib/libcrypto/man/PKCS12_create.3122
-rw-r--r--src/lib/libcrypto/man/PKCS12_parse.390
-rw-r--r--src/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3106
-rw-r--r--src/lib/libcrypto/man/PKCS7_decrypt.30
-rw-r--r--src/lib/libcrypto/man/PKCS7_encrypt.3113
-rw-r--r--src/lib/libcrypto/man/PKCS7_sign.3190
-rw-r--r--src/lib/libcrypto/man/PKCS7_sign_add_signer.3128
-rw-r--r--src/lib/libcrypto/man/PKCS7_verify.3193
-rw-r--r--src/lib/libcrypto/man/SMIME_read_PKCS7.3101
-rw-r--r--src/lib/libcrypto/man/SMIME_write_PKCS7.393
-rw-r--r--src/lib/libcrypto/man/i2d_PKCS7_bio_stream.344
27 files changed, 2231 insertions, 1380 deletions
diff --git a/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod b/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod
deleted file mode 100644
index 6d87079a84..0000000000
--- a/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod
+++ /dev/null
@@ -1,498 +0,0 @@
1=pod
2
3=head1 NAME
4
5PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
6PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
7PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
8PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY,
9PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey,
10PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
11PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
12PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
13PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
14PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
15PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
16PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
17PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
18PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
19PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
20PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
21PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
22PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
23PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
24PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7,
25PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE,
26PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE,
27PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines
28
29=head1 SYNOPSIS
30
31 #include <openssl/pem.h>
32
33 EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
34 pem_password_cb *cb, void *u);
35
36 EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
37 pem_password_cb *cb, void *u);
38
39 int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
40 unsigned char *kstr, int klen,
41 pem_password_cb *cb, void *u);
42
43 int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
44 unsigned char *kstr, int klen,
45 pem_password_cb *cb, void *u);
46
47 int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
48 char *kstr, int klen,
49 pem_password_cb *cb, void *u);
50
51 int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
52 char *kstr, int klen,
53 pem_password_cb *cb, void *u);
54
55 int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
56 char *kstr, int klen,
57 pem_password_cb *cb, void *u);
58
59 int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
60 char *kstr, int klen,
61 pem_password_cb *cb, void *u);
62
63 EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
64 pem_password_cb *cb, void *u);
65
66 EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
67 pem_password_cb *cb, void *u);
68
69 int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
70 int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
71
72 RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
73 pem_password_cb *cb, void *u);
74
75 RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
76 pem_password_cb *cb, void *u);
77
78 int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
79 unsigned char *kstr, int klen,
80 pem_password_cb *cb, void *u);
81
82 int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
83 unsigned char *kstr, int klen,
84 pem_password_cb *cb, void *u);
85
86 RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
87 pem_password_cb *cb, void *u);
88
89 RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
90 pem_password_cb *cb, void *u);
91
92 int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
93
94 int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
95
96 RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
97 pem_password_cb *cb, void *u);
98
99 RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
100 pem_password_cb *cb, void *u);
101
102 int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
103
104 int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
105
106 DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
107 pem_password_cb *cb, void *u);
108
109 DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
110 pem_password_cb *cb, void *u);
111
112 int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
113 unsigned char *kstr, int klen,
114 pem_password_cb *cb, void *u);
115
116 int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
117 unsigned char *kstr, int klen,
118 pem_password_cb *cb, void *u);
119
120 DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
121 pem_password_cb *cb, void *u);
122
123 DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
124 pem_password_cb *cb, void *u);
125
126 int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
127
128 int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
129
130 DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
131
132 DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
133
134 int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
135
136 int PEM_write_DSAparams(FILE *fp, DSA *x);
137
138 DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
139
140 DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
141
142 int PEM_write_bio_DHparams(BIO *bp, DH *x);
143
144 int PEM_write_DHparams(FILE *fp, DH *x);
145
146 X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
147
148 X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
149
150 int PEM_write_bio_X509(BIO *bp, X509 *x);
151
152 int PEM_write_X509(FILE *fp, X509 *x);
153
154 X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
155
156 X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
157
158 int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
159
160 int PEM_write_X509_AUX(FILE *fp, X509 *x);
161
162 X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
163 pem_password_cb *cb, void *u);
164
165 X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
166 pem_password_cb *cb, void *u);
167
168 int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
169
170 int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
171
172 int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
173
174 int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
175
176 X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
177 pem_password_cb *cb, void *u);
178 X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
179 pem_password_cb *cb, void *u);
180 int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
181 int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
182
183 PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
184
185 PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
186
187 int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
188
189 int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
190
191 NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
192 NETSCAPE_CERT_SEQUENCE **x,
193 pem_password_cb *cb, void *u);
194
195 NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
196 NETSCAPE_CERT_SEQUENCE **x,
197 pem_password_cb *cb, void *u);
198
199 int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
200
201 int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
202
203=head1 DESCRIPTION
204
205The PEM functions read or write structures in PEM format. In
206this sense PEM format is simply base64 encoded data surrounded
207by header lines.
208
209For more details about the meaning of arguments see the
210B<PEM FUNCTION ARGUMENTS> section.
211
212Each operation has four functions associated with it. For
213clarity the term "B<foobar> functions" will be used to collectively
214refer to the PEM_read_bio_foobar(), PEM_read_foobar(),
215PEM_write_bio_foobar() and PEM_write_foobar() functions.
216
217The B<PrivateKey> functions read or write a private key in
218PEM format using an EVP_PKEY structure. The write routines use
219"traditional" private key format and can handle both RSA and DSA
220private keys. The read functions can additionally transparently
221handle PKCS#8 format encrypted and unencrypted keys too.
222
223PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey()
224write a private key in an EVP_PKEY structure in PKCS#8
225EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
226algorithms. The B<cipher> argument specifies the encryption algorithm to
227use: unlike all other PEM routines the encryption is applied at the
228PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no
229encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
230
231PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
232also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
233it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
234to use is specified in the B<nid> parameter and should be the NID of the
235corresponding OBJECT IDENTIFIER (see NOTES section).
236
237The B<PUBKEY> functions process a public key using an EVP_PKEY
238structure. The public key is encoded as a SubjectPublicKeyInfo
239structure.
240
241The B<RSAPrivateKey> functions process an RSA private key using an
242RSA structure. It handles the same formats as the B<PrivateKey>
243functions but an error occurs if the private key is not RSA.
244
245The B<RSAPublicKey> functions process an RSA public key using an
246RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
247structure.
248
249The B<RSA_PUBKEY> functions also process an RSA public key using
250an RSA structure. However the public key is encoded using a
251SubjectPublicKeyInfo structure and an error occurs if the public
252key is not RSA.
253
254The B<DSAPrivateKey> functions process a DSA private key using a
255DSA structure. It handles the same formats as the B<PrivateKey>
256functions but an error occurs if the private key is not DSA.
257
258The B<DSA_PUBKEY> functions process a DSA public key using
259a DSA structure. The public key is encoded using a
260SubjectPublicKeyInfo structure and an error occurs if the public
261key is not DSA.
262
263The B<DSAparams> functions process DSA parameters using a DSA
264structure. The parameters are encoded using a foobar structure.
265
266The B<DHparams> functions process DH parameters using a DH
267structure. The parameters are encoded using a PKCS#3 DHparameter
268structure.
269
270The B<X509> functions process an X509 certificate using an X509
271structure. They will also process a trusted X509 certificate but
272any trust settings are discarded.
273
274The B<X509_AUX> functions process a trusted X509 certificate using
275an X509 structure.
276
277The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10
278certificate request using an X509_REQ structure. The B<X509_REQ>
279write functions use B<CERTIFICATE REQUEST> in the header whereas
280the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST>
281(as required by some CAs). The B<X509_REQ> read functions will
282handle either form so there are no B<X509_REQ_NEW> read functions.
283
284The B<X509_CRL> functions process an X509 CRL using an X509_CRL
285structure.
286
287The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7
288structure.
289
290The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate
291Sequence using a NETSCAPE_CERT_SEQUENCE structure.
292
293=head1 PEM FUNCTION ARGUMENTS
294
295The PEM functions have many common arguments.
296
297The B<bp> BIO parameter (if present) specifies the BIO to read from
298or write to.
299
300The B<fp> FILE parameter (if present) specifies the FILE pointer to
301read from or write to.
302
303The PEM read functions all take an argument B<TYPE **x> and return
304a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
305uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
306NULL but B<*x> is NULL then the structure returned will be written
307to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
308to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
309Irrespective of the value of B<x> a pointer to the structure is always
310returned (or NULL if an error occurred).
311
312The PEM functions which write private keys take an B<enc> parameter
313which specifies the encryption algorithm to use, encryption is done
314at the PEM level. If this parameter is set to NULL then the private
315key is written in unencrypted form.
316
317The B<cb> argument is the callback to use when querying for the pass
318phrase used for encrypted PEM structures (normally only private keys).
319
320For the PEM write routines if the B<kstr> parameter is not NULL then
321B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
322ignored.
323
324If the B<cb> parameters is set to NULL and the B<u> parameter is not
325NULL then the B<u> parameter is interpreted as a null terminated string
326to use as the passphrase. If both B<cb> and B<u> are NULL then the
327default callback routine is used which will typically prompt for the
328passphrase on the current terminal with echoing turned off.
329
330The default passphrase callback is sometimes inappropriate (for example
331in a GUI application) so an alternative can be supplied. The callback
332routine has the following form:
333
334 int cb(char *buf, int size, int rwflag, void *u);
335
336B<buf> is the buffer to write the passphrase to. B<size> is the maximum
337length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
338which is set to 0 when reading and 1 when writing. A typical routine
339will ask the user to verify the passphrase (for example by prompting
340for it twice) if B<rwflag> is 1. The B<u> parameter has the same
341value as the B<u> parameter passed to the PEM routine. It allows
342arbitrary data to be passed to the callback by the application
343(for example a window handle in a GUI application). The callback
344B<must> return the number of characters in the passphrase or 0 if
345an error occurred.
346
347=head1 EXAMPLES
348
349Although the PEM routines take several arguments in almost all applications
350most of them are set to 0 or NULL.
351
352Read a certificate in PEM format from a BIO:
353
354 X509 *x;
355 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
356 if (x == NULL) {
357 /* Error */
358 }
359
360Alternative method:
361
362 X509 *x = NULL;
363 if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
364 /* Error */
365 }
366
367Write a certificate to a BIO:
368
369 if (!PEM_write_bio_X509(bp, x)) {
370 /* Error */
371 }
372
373Write an unencrypted private key to a FILE pointer:
374
375 if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
376 /* Error */
377 }
378
379Write a private key (using traditional format) to a BIO using
380triple DES encryption, the pass phrase is prompted for:
381
382 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
383 NULL, 0, 0, NULL)) {
384 /* Error */
385 }
386
387Write a private key (using PKCS#8 format) to a BIO using triple
388DES encryption, using the pass phrase "hello":
389
390 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
391 NULL, 0, 0, "hello")) {
392 /* Error */
393 }
394
395Read a private key from a BIO using the pass phrase "hello":
396
397 key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
398 if (key == NULL) {
399 /* Error */
400 }
401
402Read a private key from a BIO using a pass phrase callback:
403
404 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
405 if (key == NULL) {
406 /* Error */
407 }
408
409Skeleton pass phrase callback:
410
411 int
412 pass_cb(char *buf, int size, int rwflag, void *u)
413 {
414 int len;
415 char *tmp;
416
417 /* We'd probably do something else if 'rwflag' is 1 */
418 printf("Enter pass phrase for \"%s\"\n", u);
419
420 /* get pass phrase, length 'len' into 'tmp' */
421 tmp = "hello";
422 len = strlen(tmp);
423
424 if (len == 0)
425 return 0;
426 /* if too long, truncate */
427 if (len > size)
428 len = size;
429 memcpy(buf, tmp, len);
430 return len;
431 }
432
433=head1 NOTES
434
435The old B<PrivateKey> write routines are retained for compatibility.
436New applications should write private keys using the
437PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines
438because they are more secure (they use an iteration count of 2048 whereas
439the traditional routines use a count of 1) unless compatibility with older
440versions of OpenSSL is important.
441
442The B<PrivateKey> read routines can be used in all applications because
443they handle all formats transparently.
444
445A frequent cause of problems is attempting to use the PEM routines like
446this:
447
448 X509 *x;
449 PEM_read_bio_X509(bp, &x, 0, NULL);
450
451this is a bug because an attempt will be made to reuse the data at B<x>
452which is an uninitialised pointer.
453
454=head1 PEM ENCRYPTION FORMAT
455
456This old B<PrivateKey> routines use a non standard technique for encryption.
457
458The private key (or other data) takes the following form:
459
460 -----BEGIN RSA PRIVATE KEY-----
461 Proc-Type: 4,ENCRYPTED
462 DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
463
464 ...base64 encoded data...
465 -----END RSA PRIVATE KEY-----
466
467The line beginning DEK-Info contains two comma separated pieces of information:
468the encryption algorithm name as used by EVP_get_cipherbyname() and an 8
469byte B<salt> encoded as a set of hexadecimal digits.
470
471After this is the base64 encoded encrypted data.
472
473The encryption key is determined using EVP_bytestokey(), using B<salt> and an
474iteration count of 1. The IV used is the value of B<salt> and *not* the IV
475returned by EVP_bytestokey().
476
477=head1 BUGS
478
479The PEM read routines in some versions of OpenSSL will not correctly reuse
480an existing structure. Therefore the following:
481
482 PEM_read_bio_X509(bp, &x, 0, NULL);
483
484where B<x> already contains a valid certificate, may not work, whereas:
485
486 X509_free(x);
487 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
488
489is guaranteed to work.
490
491=head1 RETURN CODES
492
493The read routines return either a pointer to the structure read or NULL
494if an error occurred.
495
496The write routines return 1 for success or 0 for failure.
497
498=cut
diff --git a/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod b/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod
deleted file mode 100644
index 16fc9b6845..0000000000
--- a/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod
+++ /dev/null
@@ -1,41 +0,0 @@
1=pod
2
3=head1 NAME
4
5PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format.
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10 #include <openssl/pem.h>
11
12 int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
13
14=head1 DESCRIPTION
15
16PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format.
17
18It is otherwise identical to the function SMIME_write_PKCS7().
19
20=head1 NOTES
21
22This function is effectively a version of the PEM_write_bio_PKCS7() supporting
23streaming.
24
25=head1 RETURN VALUES
26
27PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure.
28
29=head1 SEE ALSO
30
31L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
32L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
33L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>,
34L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>,
35L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)>
36
37=head1 HISTORY
38
39PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0
40
41=cut
diff --git a/src/lib/libcrypto/doc/PKCS12_create.pod b/src/lib/libcrypto/doc/PKCS12_create.pod
deleted file mode 100644
index 3b27c11a10..0000000000
--- a/src/lib/libcrypto/doc/PKCS12_create.pod
+++ /dev/null
@@ -1,73 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS12_create - create a PKCS#12 structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs12.h>
10
11 PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey,
12 X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert,
13 int iter, int mac_iter, int keytype);
14
15=head1 DESCRIPTION
16
17PKCS12_create() creates a PKCS#12 structure.
18
19B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for
20the supplied certificate and key. B<pkey> is the private key to include in
21the structure and B<cert> its corresponding certificates. B<ca> is an optional
22set of certificates to also include in the structure.
23Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or
24certificate is required.
25
26B<nid_key> and B<nid_cert> are the encryption algorithms that should be used
27for the key and certificate respectively. If either B<nid_key> or B<nid_cert>
28is set to -1, no encryption will be used.
29
30B<iter> is the encryption algorithm iteration count to use and B<mac_iter> is
31the MAC iteration count to use. If B<mac_iter> is set to -1, the MAC will be
32omitted entirely.
33
34B<keytype> is the type of key.
35
36=head1 NOTES
37
38The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype>
39can all be set to zero and sensible defaults will be used.
40
41These defaults are: 40 bit RC2 encryption for certificates, triple DES
42encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER
43(currently 2048) and a MAC iteration count of 1.
44
45The default MAC iteration count is 1 in order to retain compatibility with
46old software which did not interpret MAC iteration counts. If such compatibility
47is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER.
48
49B<keytype> adds a flag to the store private key. This is a non standard
50extension that is only currently interpreted by MSIE. If set to zero the flag
51is omitted, if set to B<KEY_SIG> the key can be used for signing only, if set
52to B<KEY_EX> it can be used for signing and encryption. This option was useful
53for old export grade software which could use signing only keys of arbitrary
54size but had restrictions on the permissible sizes of keys which could be used
55for encryption.
56
57If a certificate contains an B<alias> or B<keyid> then this will be
58used for the corresponding B<friendlyName> or B<localKeyID> in the
59PKCS12 structure.
60
61=head1 SEE ALSO
62
63L<d2i_PKCS12(3)|d2i_PKCS12(3)>
64
65=head1 HISTORY
66
67PKCS12_create was added in OpenSSL 0.9.3.
68
69Before OpenSSL 0.9.8, neither B<pkey> nor B<cert> were allowed to be B<NULL>,
70and a value of B<-1> was not allowed for B<nid_key>, B<nid_cert> and
71B<mac_iter>.
72
73=cut
diff --git a/src/lib/libcrypto/doc/PKCS12_parse.pod b/src/lib/libcrypto/doc/PKCS12_parse.pod
deleted file mode 100644
index c54cf2ad61..0000000000
--- a/src/lib/libcrypto/doc/PKCS12_parse.pod
+++ /dev/null
@@ -1,57 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS12_parse - parse a PKCS#12 structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs12.h>
10
11int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca);
12
13=head1 DESCRIPTION
14
15PKCS12_parse() parses a PKCS12 structure.
16
17B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
18If successful the private key will be written to B<*pkey>, the corresponding
19certificate to B<*cert> and any additional certificates to B<*ca>.
20
21=head1 NOTES
22
23The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
24which case additional certificates will be discarded. B<*ca> can also be a
25valid STACK in which case additional certificates are appended to B<*ca>. If
26B<*ca> is B<NULL> a new STACK will be allocated.
27
28The B<friendlyName> and B<localKeyID> attributes (if present) on each
29certificate will be stored in the B<alias> and B<keyid> attributes of the
30B<X509> structure.
31
32=head1 RETURN VALUES
33
34PKCS12_parse() returns 1 for success and zero if an error occurred.
35
36The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
37
38=head1 BUGS
39
40Only a single private key and corresponding certificate is returned by this
41function. More complex PKCS#12 files with multiple private keys will only
42return the first match.
43
44Only B<friendlyName> and B<localKeyID> attributes are currently stored in
45certificates. Other attributes are discarded.
46
47Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
48
49=head1 SEE ALSO
50
51L<d2i_PKCS12(3)|d2i_PKCS12(3)>
52
53=head1 HISTORY
54
55PKCS12_parse was added in OpenSSL 0.9.3
56
57=cut
diff --git a/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod b/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod
deleted file mode 100644
index 0c164a0ed6..0000000000
--- a/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod
+++ /dev/null
@@ -1,64 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int PKCS5_PBKDF2_HMAC(const char *pass, int passlen,
12 const unsigned char *salt, int saltlen, int iter,
13 const EVP_MD *digest,
14 int keylen, unsigned char *out);
15
16int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen,
17 const unsigned char *salt, int saltlen, int iter,
18 int keylen, unsigned char *out);
19
20=head1 DESCRIPTION
21
22PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count
23as specified in RFC 2898.
24
25B<pass> is the password used in the derivation of length B<passlen>. B<pass>
26is an optional parameter and can be NULL. If B<passlen> is -1, then the
27function will calculate the length of B<pass> using strlen().
28
29B<salt> is the salt used in the derivation of length B<saltlen>. If the
30B<salt> is NULL, then B<saltlen> must be 0. The function will not
31attempt to calculate the length of the B<salt> because it is not assumed to
32be NULL terminated.
33
34B<iter> is the iteration count and its value should be greater than or
35equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any
36B<iter> less than 1 is treated as a single iteration.
37
38B<digest> is the message digest function used in the derivation. Values include
39any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls
40PKCS5_PBKDF2_HMAC() with EVP_sha1().
41
42The derived key will be written to B<out>. The size of the B<out> buffer
43is specified via B<keylen>.
44
45=head1 NOTES
46
47A typical application of this function is to derive keying material for an
48encryption algorithm from a password in the B<pass>, a salt in B<salt>,
49and an iteration count.
50
51Increasing the B<iter> parameter slows down the algorithm which makes it
52harder for an attacker to perform a brute force attack using a large number
53of candidate passwords.
54
55=head1 RETURN VALUES
56
57PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error.
58
59=head1 SEE ALSO
60
61L<evp(3)|evp(3)>, L<rand(3)|rand(3)>,
62L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>
63
64=cut
diff --git a/src/lib/libcrypto/doc/PKCS7_decrypt.pod b/src/lib/libcrypto/doc/PKCS7_decrypt.pod
deleted file mode 100644
index 78919998ce..0000000000
--- a/src/lib/libcrypto/doc/PKCS7_decrypt.pod
+++ /dev/null
@@ -1,57 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags);
12
13=head1 DESCRIPTION
14
15PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData
16structure. B<pkey> is the private key of the recipient, B<cert> is the
17recipients certificate, B<data> is a BIO to write the content to and
18B<flags> is an optional set of flags.
19
20=head1 NOTES
21
22OpenSSL_add_all_algorithms() (or equivalent) should be called before using this
23function or errors about unknown algorithms will occur.
24
25Although the recipients certificate is not needed to decrypt the data it is
26needed to locate the appropriate (of possible several) recipients in the PKCS#7
27structure.
28
29The following flags can be passed in the B<flags> parameter.
30
31If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
32from the content. If the content is not of type B<text/plain> then an error is
33returned.
34
35=head1 RETURN VALUES
36
37PKCS7_decrypt() returns either 1 for success or 0 for failure.
38The error can be obtained from ERR_get_error(3)
39
40=head1 BUGS
41
42PKCS7_decrypt() must be passed the correct recipient key and certificate. It
43would be better if it could look up the correct key and certificate from a
44database.
45
46The lack of single pass processing and need to hold all data in memory as
47mentioned in PKCS7_sign() also applies to PKCS7_verify().
48
49=head1 SEE ALSO
50
51L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
52
53=head1 HISTORY
54
55PKCS7_decrypt() was added to OpenSSL 0.9.5
56
57=cut
diff --git a/src/lib/libcrypto/doc/PKCS7_encrypt.pod b/src/lib/libcrypto/doc/PKCS7_encrypt.pod
deleted file mode 100644
index 8bc77407b9..0000000000
--- a/src/lib/libcrypto/doc/PKCS7_encrypt.pod
+++ /dev/null
@@ -1,73 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS7_encrypt - create a PKCS#7 envelopedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags);
12
13=head1 DESCRIPTION
14
15PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
16is a list of recipient certificates. B<in> is the content to be encrypted.
17B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
18
19=head1 NOTES
20
21Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
22certificates supplied to this function must all contain RSA public keys, though
23they do not have to be signed using the RSA algorithm.
24
25The algorithm passed in the B<cipher> parameter must support ASN1 encoding of
26its parameters.
27
28Many browsers implement a "sign and encrypt" option which is simply an S/MIME
29envelopedData containing an S/MIME signed message. This can be readily produced
30by storing the S/MIME signed message in a memory BIO and passing it to
31PKCS7_encrypt().
32
33The following flags can be passed in the B<flags> parameter.
34
35If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are
36prepended to the data.
37
38Normally the supplied content is translated into MIME canonical format (as
39required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
40occurs. This option should be used if the supplied data is in binary format
41otherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then
42B<PKCS7_TEXT> is ignored.
43
44If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
45suitable for streaming I/O: no data is read from the BIO B<in>.
46
47=head1 NOTES
48
49If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
50complete and outputting its contents via a function that does not
51properly finalize the B<PKCS7> structure will give unpredictable
52results.
53
54Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
55PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
56can be performed by obtaining the streaming ASN1 B<BIO> directly using
57BIO_new_PKCS7().
58
59=head1 RETURN VALUES
60
61PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred.
62The error can be obtained from ERR_get_error(3).
63
64=head1 SEE ALSO
65
66L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
67
68=head1 HISTORY
69
70PKCS7_decrypt() was added to OpenSSL 0.9.5
71The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0.
72
73=cut
diff --git a/src/lib/libcrypto/doc/PKCS7_sign.pod b/src/lib/libcrypto/doc/PKCS7_sign.pod
deleted file mode 100644
index 64a3036c0a..0000000000
--- a/src/lib/libcrypto/doc/PKCS7_sign.pod
+++ /dev/null
@@ -1,116 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS7_sign - create a PKCS#7 signedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags);
12
13=head1 DESCRIPTION
14
15PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is
16the certificate to sign with, B<pkey> is the corresponding private key.
17B<certs> is an optional additional set of certificates to include in the PKCS#7
18structure (for example any intermediate CAs in the chain).
19
20The data to be signed is read from BIO B<data>.
21
22B<flags> is an optional set of flags.
23
24=head1 NOTES
25
26Any of the following flags (ored together) can be passed in the B<flags>
27parameter.
28
29Many S/MIME clients expect the signed content to include valid MIME headers. If
30the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended
31to the data.
32
33If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
34PKCS7 structure, the signer's certificate must still be supplied in the
35B<signcert> parameter though. This can reduce the size of the signature if the
36signers certificate can be obtained by other means: for example a previously
37signed message.
38
39The data being signed is included in the PKCS7 structure, unless
40B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7
41detached signatures which are used in S/MIME plaintext signed messages for
42example.
43
44Normally the supplied content is translated into MIME canonical format (as
45required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation
46occurs. This option should be used if the supplied data is in binary format
47otherwise the translation will corrupt it.
48
49The signedData structure includes several PKCS#7 authenticatedAttributes
50including the signing time, the PKCS#7 content type and the supported list of
51ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
52authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
53the SMIMECapabilities are omitted.
54
55If present the SMIMECapabilities attribute indicates support for the following
56algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
57these algorithms is disabled then it will not be included.
58
59If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is
60just initialized ready to perform the signing operation. The signing is however
61B<not> performed and the data to be signed is not read from the B<data>
62parameter. Signing is deferred until after the data has been written. In this
63way data can be signed in a single pass.
64
65If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
66which additional signers and capabilities can be added before finalization.
67
68
69=head1 NOTES
70
71If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
72complete and outputting its contents via a function that does not properly
73finalize the B<PKCS7> structure will give unpredictable results.
74
75Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(),
76PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization
77can be performed by obtaining the streaming ASN1 B<BIO> directly using
78BIO_new_PKCS7().
79
80If a signer is specified it will use the default digest for the signing
81algorithm. This is B<SHA1> for both RSA and DSA keys.
82
83In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be
84B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added
85using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be
86called to finalize the structure if streaming is not enabled. Alternative
87signing digests can also be specified using this method.
88
89In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only
90PKCS#7 structure is output.
91
92In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must
93B<NOT> be NULL.
94
95=head1 BUGS
96
97Some advanced attributes such as counter signatures are not supported.
98
99=head1 RETURN VALUES
100
101PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error
102occurred. The error can be obtained from ERR_get_error(3).
103
104=head1 SEE ALSO
105
106L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
107
108=head1 HISTORY
109
110PKCS7_sign() was added to OpenSSL 0.9.5
111
112The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0
113
114The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0
115
116=cut
diff --git a/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod b/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod
deleted file mode 100644
index 280455d476..0000000000
--- a/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod
+++ /dev/null
@@ -1,87 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS7_sign_add_signer - add a signer PKCS7 signed data structure.
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags);
12
13
14=head1 DESCRIPTION
15
16PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private
17key B<pkey> using message digest B<md> to a PKCS7 signed data structure
18B<p7>.
19
20The PKCS7 structure should be obtained from an initial call to PKCS7_sign()
21with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7
22signed data structure.
23
24If the B<md> parameter is B<NULL> then the default digest for the public
25key algorithm will be used.
26
27Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure
28is not complete and must be finalized either by streaming (if applicable) or
29a call to PKCS7_final().
30
31
32=head1 NOTES
33
34The main purpose of this function is to provide finer control over a PKCS#7
35signed data structure where the simpler PKCS7_sign() function defaults are
36not appropriate. For example if multiple signers or non default digest
37algorithms are needed.
38
39Any of the following flags (ored together) can be passed in the B<flags>
40parameter.
41
42If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content
43digest value from the PKCS7 structure: to add a signer to an existing structure.
44An error occurs if a matching digest value cannot be found to copy. The
45returned PKCS7 structure will be valid and finalized when this flag is set.
46
47If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the
48B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes
49can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is
50needed to finalize it.
51
52If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the
53PKCS7 structure, the signer's certificate must still be supplied in the
54B<signcert> parameter though. This can reduce the size of the signature if the
55signers certificate can be obtained by other means: for example a previously
56signed message.
57
58The signedData structure includes several PKCS#7 authenticatedAttributes
59including the signing time, the PKCS#7 content type and the supported list of
60ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no
61authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just
62the SMIMECapabilities are omitted.
63
64If present the SMIMECapabilities attribute indicates support for the following
65algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of
66these algorithms is disabled then it will not be included.
67
68
69PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
70structure just added, this can be used to set additional attributes
71before it is finalized.
72
73=head1 RETURN VALUES
74
75PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO
76structure just added or NULL if an error occurs.
77
78=head1 SEE ALSO
79
80L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
81L<PKCS7_final(3)|PKCS7_final(3)>,
82
83=head1 HISTORY
84
85PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0
86
87=cut
diff --git a/src/lib/libcrypto/doc/PKCS7_verify.pod b/src/lib/libcrypto/doc/PKCS7_verify.pod
deleted file mode 100644
index 059fbff8e9..0000000000
--- a/src/lib/libcrypto/doc/PKCS7_verify.pod
+++ /dev/null
@@ -1,118 +0,0 @@
1=pod
2
3=head1 NAME
4
5PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
12
13 STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
14
15=head1 DESCRIPTION
16
17PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7
18structure to verify. B<certs> is a set of certificates in which to search for
19the signer's certificate. B<store> is a trusted certificate store (used for
20chain verification). B<indata> is the signed data if the content is not
21present in B<p7> (that is it is detached). The content is written to B<out>
22if it is not NULL.
23
24B<flags> is an optional set of flags, which can be used to modify the verify
25operation.
26
27PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does
28B<not> check their validity or whether any signatures are valid. The B<certs>
29and B<flags> parameters have the same meanings as in PKCS7_verify().
30
31=head1 VERIFY PROCESS
32
33Normally the verify process proceeds as follows.
34
35Initially some sanity checks are performed on B<p7>. The type of B<p7> must
36be signedData. There must be at least one signature on the data and if
37the content is detached B<indata> cannot be B<NULL>.
38
39An attempt is made to locate all the signer's certificates, first looking in
40the B<certs> parameter (if it is not B<NULL>) and then looking in any
41certificates contained in the B<p7> structure itself. If any signer's
42certificates cannot be located the operation fails.
43
44Each signer's certificate is chain verified using the B<smimesign> purpose and
45the supplied trusted certificate store. Any internal certificates in the message
46are used as untrusted CAs. If any chain verify fails an error code is returned.
47
48Finally the signed content is read (and written to B<out> is it is not NULL) and
49the signature's checked.
50
51If all signature's verify correctly then the function is successful.
52
53Any of the following flags (ored together) can be passed in the B<flags>
54parameter to change the default verify behaviour. Only the flag
55B<PKCS7_NOINTERN> is meaningful to PKCS7_get0_signers().
56
57If B<PKCS7_NOINTERN> is set the certificates in the message itself are not
58searched when locating the signer's certificate. This means that all the signers
59certificates must be in the B<certs> parameter.
60
61If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted
62from the content. If the content is not of type B<text/plain> then an error is
63returned.
64
65If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified.
66
67If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are
68not used as untrusted CAs. This means that the whole verify chain (apart from
69the signer's certificate) must be contained in the trusted store.
70
71If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked.
72
73=head1 NOTES
74
75One application of B<PKCS7_NOINTERN> is to only accept messages signed by
76a small number of certificates. The acceptable certificates would be passed
77in the B<certs> parameter. In this case if the signer is not one of the
78certificates supplied in B<certs> then the verify will fail because the
79signer cannot be found.
80
81Care should be taken when modifying the default verify behaviour, for example
82setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification
83and any signed message will be considered valid. This combination is however
84useful if one merely wishes to write the content to B<out> and its validity
85is not considered important.
86
87Chain verification should arguably be performed using the signing time rather
88than the current time. However since the signing time is supplied by the
89signer it cannot be trusted without additional evidence (such as a trusted
90timestamp).
91
92=head1 RETURN VALUES
93
94PKCS7_verify() returns 1 for a successful verification and zero or a negative
95value if an error occurs.
96
97PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.
98
99The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
100
101=head1 BUGS
102
103The trusted certificate store is not searched for the signers certificate,
104this is primarily due to the inadequacies of the current B<X509_STORE>
105functionality.
106
107The lack of single pass processing and need to hold all data in memory as
108mentioned in PKCS7_sign() also applies to PKCS7_verify().
109
110=head1 SEE ALSO
111
112L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>
113
114=head1 HISTORY
115
116PKCS7_verify() was added to OpenSSL 0.9.5
117
118=cut
diff --git a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod
deleted file mode 100644
index 9d46715941..0000000000
--- a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod
+++ /dev/null
@@ -1,73 +0,0 @@
1=pod
2
3=head1 NAME
4
5SMIME_read_PKCS7 - parse S/MIME message.
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont);
12
13=head1 DESCRIPTION
14
15SMIME_read_PKCS7() parses a message in S/MIME format.
16
17B<in> is a BIO to read the message from.
18
19If cleartext signing is used then the content is saved in
20a memory bio which is written to B<*bcont>, otherwise
21B<*bcont> is set to B<NULL>.
22
23The parsed PKCS#7 structure is returned or B<NULL> if an
24error occurred.
25
26=head1 NOTES
27
28If B<*bcont> is not B<NULL> then the message is clear text
29signed. B<*bcont> can then be passed to PKCS7_verify() with
30the B<PKCS7_DETACHED> flag set.
31
32Otherwise the type of the returned structure can be determined
33using PKCS7_type().
34
35To support future functionality if B<bcont> is not B<NULL>
36B<*bcont> should be initialized to B<NULL>. For example:
37
38 BIO *cont = NULL;
39 PKCS7 *p7;
40
41 p7 = SMIME_read_PKCS7(in, &cont);
42
43=head1 BUGS
44
45The MIME parser used by SMIME_read_PKCS7() is somewhat primitive.
46While it will handle most S/MIME messages more complex compound
47formats may not work.
48
49The parser assumes that the PKCS7 structure is always base64
50encoded and will not handle the case where it is in binary format
51or uses quoted printable format.
52
53The use of a memory BIO to hold the signed content limits the size
54of message which can be processed due to memory restraints: a
55streaming single pass option should be available.
56
57=head1 RETURN VALUES
58
59SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL>
60is an error occurred. The error can be obtained from ERR_get_error(3).
61
62=head1 SEE ALSO
63
64L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)>
65L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
66L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
67L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
68
69=head1 HISTORY
70
71SMIME_read_PKCS7() was added to OpenSSL 0.9.5
72
73=cut
diff --git a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod
deleted file mode 100644
index 4a7cd08c42..0000000000
--- a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod
+++ /dev/null
@@ -1,65 +0,0 @@
1=pod
2
3=head1 NAME
4
5SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format.
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags);
12
13=head1 DESCRIPTION
14
15SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7
16structure to produce an S/MIME message.
17
18B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7>
19structure. If streaming is enabled then the content must be supplied in the
20B<data> argument. B<flags> is an optional set of flags.
21
22=head1 NOTES
23
24The following flags can be passed in the B<flags> parameter.
25
26If B<PKCS7_DETACHED> is set then cleartext signing will be used,
27this option only makes sense for signedData where B<PKCS7_DETACHED>
28is also set when PKCS7_sign() is also called.
29
30If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain>
31are added to the content, this only makes sense if B<PKCS7_DETACHED>
32is also set.
33
34If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should
35only be set if B<PKCS7_STREAM> was also set in the previous call to
36PKCS7_sign() or B<PKCS7_encrypt()>.
37
38If cleartext signing is being used and B<PKCS7_STREAM> not set then
39the data must be read twice: once to compute the signature in PKCS7_sign()
40and once to output the S/MIME message.
41
42If streaming is performed the content is output in BER format using indefinite
43length constructed encoding except in the case of signed data with detached
44content where the content is absent and DER format is used.
45
46=head1 BUGS
47
48SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
49should be an option to disable this.
50
51=head1 RETURN VALUES
52
53SMIME_write_PKCS7() returns 1 for success or 0 for failure.
54
55=head1 SEE ALSO
56
57L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
58L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
59L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
60
61=head1 HISTORY
62
63SMIME_write_PKCS7() was added to OpenSSL 0.9.5
64
65=cut
diff --git a/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod b/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod
deleted file mode 100644
index a37231e267..0000000000
--- a/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod
+++ /dev/null
@@ -1,44 +0,0 @@
1=pod
2
3=head1 NAME
4
5i2d_PKCS7_bio_stream - output PKCS7 structure in BER format.
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs7.h>
10
11 int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags);
12
13=head1 DESCRIPTION
14
15i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format.
16
17It is otherwise identical to the function SMIME_write_PKCS7().
18
19=head1 NOTES
20
21This function is effectively a version of the d2i_PKCS7_bio() supporting
22streaming.
23
24=head1 BUGS
25
26The prefix "i2d" is arguably wrong because the function outputs BER format.
27
28=head1 RETURN VALUES
29
30i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure.
31
32=head1 SEE ALSO
33
34L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>,
35L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)>
36L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>,
37L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>,
38L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)>
39
40=head1 HISTORY
41
42i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0
43
44=cut
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 17efba0d08..dbfce91647 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.41 2016/11/03 12:21:50 schwarze Exp $ 1# $OpenBSD: Makefile,v 1.42 2016/11/03 15:20:36 schwarze Exp $
2 2
3.include <bsd.own.mk> # for NOMAN 3.include <bsd.own.mk> # for NOMAN
4 4
@@ -122,6 +122,18 @@ MAN= \
122 OPENSSL_config.3 \ 122 OPENSSL_config.3 \
123 OPENSSL_load_builtin_modules.3 \ 123 OPENSSL_load_builtin_modules.3 \
124 OpenSSL_add_all_algorithms.3 \ 124 OpenSSL_add_all_algorithms.3 \
125 PEM_read_bio_PrivateKey.3 \
126 PEM_write_bio_PKCS7_stream.3 \
127 PKCS12_create.3 \
128 PKCS12_parse.3 \
129 PKCS5_PBKDF2_HMAC.3 \
130 PKCS7_decrypt.3 \
131 PKCS7_encrypt.3 \
132 PKCS7_sign.3 \
133 PKCS7_sign_add_signer.3 \
134 PKCS7_verify.3 \
135 SMIME_read_PKCS7.3 \
136 SMIME_write_PKCS7.3 \
125 UI_new.3 \ 137 UI_new.3 \
126 bn_dump.3 \ 138 bn_dump.3 \
127 crypto.3 \ 139 crypto.3 \
@@ -129,19 +141,10 @@ MAN= \
129 d2i_PKCS8PrivateKey_bio.3 \ 141 d2i_PKCS8PrivateKey_bio.3 \
130 des_read_pw.3 \ 142 des_read_pw.3 \
131 evp.3 \ 143 evp.3 \
144 i2d_PKCS7_bio_stream.3 \
132 lh_new.3 \ 145 lh_new.3 \
133 146
134GENMAN= \ 147GENMAN= \
135 PKCS5_PBKDF2_HMAC.3 \
136 PEM_read_bio_PrivateKey.3 \
137 PEM_write_bio_PKCS7_stream.3 \
138 PKCS12_create.3 \
139 PKCS12_parse.3 \
140 PKCS7_decrypt.3 \
141 PKCS7_encrypt.3 \
142 PKCS7_sign.3 \
143 PKCS7_sign_add_signer.3 \
144 PKCS7_verify.3 \
145 RAND.3 \ 148 RAND.3 \
146 RAND_add.3 \ 149 RAND_add.3 \
147 RAND_bytes.3 \ 150 RAND_bytes.3 \
@@ -164,8 +167,6 @@ GENMAN= \
164 RSA_sign_ASN1_OCTET_STRING.3 \ 167 RSA_sign_ASN1_OCTET_STRING.3 \
165 RSA_size.3 \ 168 RSA_size.3 \
166 SHA1.3 \ 169 SHA1.3 \
167 SMIME_read_PKCS7.3 \
168 SMIME_write_PKCS7.3 \
169 X509_NAME_ENTRY_get_object.3 \ 170 X509_NAME_ENTRY_get_object.3 \
170 X509_NAME_add_entry_by_txt.3 \ 171 X509_NAME_add_entry_by_txt.3 \
171 X509_NAME_get_index_by_NID.3 \ 172 X509_NAME_get_index_by_NID.3 \
@@ -193,7 +194,6 @@ GENMAN= \
193 dsa.3 \ 194 dsa.3 \
194 ec.3 \ 195 ec.3 \
195 engine.3 \ 196 engine.3 \
196 i2d_PKCS7_bio_stream.3 \
197 lh_stats.3 \ 197 lh_stats.3 \
198 rsa.3 \ 198 rsa.3 \
199 x509.3 \ 199 x509.3 \
diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
new file mode 100644
index 0000000000..7dcea6dbe1
--- /dev/null
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -0,0 +1,997 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PEM_READ_BIO_PRIVATEKEY 3
3.Os
4.Sh NAME
5.Nm PEM ,
6.Nm PEM_read_bio_PrivateKey ,
7.Nm PEM_read_PrivateKey ,
8.Nm PEM_write_bio_PrivateKey ,
9.Nm PEM_write_PrivateKey ,
10.Nm PEM_write_bio_PKCS8PrivateKey ,
11.Nm PEM_write_PKCS8PrivateKey ,
12.Nm PEM_write_bio_PKCS8PrivateKey_nid ,
13.Nm PEM_write_PKCS8PrivateKey_nid ,
14.Nm PEM_read_bio_PUBKEY ,
15.Nm PEM_read_PUBKEY ,
16.Nm PEM_write_bio_PUBKEY ,
17.Nm PEM_write_PUBKEY ,
18.Nm PEM_read_bio_RSAPrivateKey ,
19.Nm PEM_read_RSAPrivateKey ,
20.Nm PEM_write_bio_RSAPrivateKey ,
21.Nm PEM_write_RSAPrivateKey ,
22.Nm PEM_read_bio_RSAPublicKey ,
23.Nm PEM_read_RSAPublicKey ,
24.Nm PEM_write_bio_RSAPublicKey ,
25.Nm PEM_write_RSAPublicKey ,
26.Nm PEM_read_bio_RSA_PUBKEY ,
27.Nm PEM_read_RSA_PUBKEY ,
28.Nm PEM_write_bio_RSA_PUBKEY ,
29.Nm PEM_write_RSA_PUBKEY ,
30.Nm PEM_read_bio_DSAPrivateKey ,
31.Nm PEM_read_DSAPrivateKey ,
32.Nm PEM_write_bio_DSAPrivateKey ,
33.Nm PEM_write_DSAPrivateKey ,
34.Nm PEM_read_bio_DSA_PUBKEY ,
35.Nm PEM_read_DSA_PUBKEY ,
36.Nm PEM_write_bio_DSA_PUBKEY ,
37.Nm PEM_write_DSA_PUBKEY ,
38.Nm PEM_read_bio_DSAparams ,
39.Nm PEM_read_DSAparams ,
40.Nm PEM_write_bio_DSAparams ,
41.Nm PEM_write_DSAparams ,
42.Nm PEM_read_bio_DHparams ,
43.Nm PEM_read_DHparams ,
44.Nm PEM_write_bio_DHparams ,
45.Nm PEM_write_DHparams ,
46.Nm PEM_read_bio_X509 ,
47.Nm PEM_read_X509 ,
48.Nm PEM_write_bio_X509 ,
49.Nm PEM_write_X509 ,
50.Nm PEM_read_bio_X509_AUX ,
51.Nm PEM_read_X509_AUX ,
52.Nm PEM_write_bio_X509_AUX ,
53.Nm PEM_write_X509_AUX ,
54.Nm PEM_read_bio_X509_REQ ,
55.Nm PEM_read_X509_REQ ,
56.Nm PEM_write_bio_X509_REQ ,
57.Nm PEM_write_X509_REQ ,
58.Nm PEM_write_bio_X509_REQ_NEW ,
59.Nm PEM_write_X509_REQ_NEW ,
60.Nm PEM_read_bio_X509_CRL ,
61.Nm PEM_read_X509_CRL ,
62.Nm PEM_write_bio_X509_CRL ,
63.Nm PEM_write_X509_CRL ,
64.Nm PEM_read_bio_PKCS7 ,
65.Nm PEM_read_PKCS7 ,
66.Nm PEM_write_bio_PKCS7 ,
67.Nm PEM_write_PKCS7 ,
68.Nm PEM_read_bio_NETSCAPE_CERT_SEQUENCE ,
69.Nm PEM_read_NETSCAPE_CERT_SEQUENCE ,
70.Nm PEM_write_bio_NETSCAPE_CERT_SEQUENCE ,
71.Nm PEM_write_NETSCAPE_CERT_SEQUENCE
72.Nd PEM routines
73.Sh SYNOPSIS
74.In openssl/pem.h
75.Ft EVP_PKEY *
76.Fo PEM_read_bio_PrivateKey
77.Fa "BIO *bp"
78.Fa "EVP_PKEY **x"
79.Fa "pem_password_cb *cb"
80.Fa "void *u"
81.Fc
82.Ft EVP_PKEY *
83.Fo PEM_read_PrivateKey
84.Fa "FILE *fp"
85.Fa "EVP_PKEY **x"
86.Fa "pem_password_cb *cb"
87.Fa "void *u"
88.Fc
89.Ft int
90.Fo PEM_write_bio_PrivateKey
91.Fa "BIO *bp"
92.Fa "EVP_PKEY *x"
93.Fa "const EVP_CIPHER *enc"
94.Fa "unsigned char *kstr"
95.Fa "int klen"
96.Fa "pem_password_cb *cb"
97.Fa "void *u"
98.Fc
99.Ft int
100.Fo PEM_write_PrivateKey
101.Fa "FILE *fp"
102.Fa "EVP_PKEY *x"
103.Fa "const EVP_CIPHER *enc"
104.Fa "unsigned char *kstr"
105.Fa "int klen"
106.Fa "pem_password_cb *cb"
107.Fa "void *u"
108.Fc
109.Ft int
110.Fo PEM_write_bio_PKCS8PrivateKey
111.Fa "BIO *bp"
112.Fa "EVP_PKEY *x"
113.Fa "const EVP_CIPHER *enc"
114.Fa "char *kstr"
115.Fa "int klen"
116.Fa "pem_password_cb *cb"
117.Fa "void *u"
118.Fc
119.Ft int
120.Fo PEM_write_PKCS8PrivateKey
121.Fa "FILE *fp"
122.Fa "EVP_PKEY *x"
123.Fa "const EVP_CIPHER *enc"
124.Fa "char *kstr"
125.Fa "int klen"
126.Fa "pem_password_cb *cb"
127.Fa "void *u"
128.Fc
129.Ft int
130.Fo PEM_write_bio_PKCS8PrivateKey_nid
131.Fa "BIO *bp"
132.Fa "EVP_PKEY *x"
133.Fa "int nid"
134.Fa "char *kstr"
135.Fa "int klen"
136.Fa "pem_password_cb *cb"
137.Fa "void *u"
138.Fc
139.Ft int
140.Fo PEM_write_PKCS8PrivateKey_nid
141.Fa "FILE *fp"
142.Fa "EVP_PKEY *x"
143.Fa "int nid"
144.Fa "char *kstr"
145.Fa "int klen"
146.Fa "pem_password_cb *cb"
147.Fa "void *u"
148.Fc
149.Ft EVP_PKEY *
150.Fo PEM_read_bio_PUBKEY
151.Fa "BIO *bp"
152.Fa "EVP_PKEY **x"
153.Fa "pem_password_cb *cb"
154.Fa "void *u"
155.Fc
156.Ft EVP_PKEY *
157.Fo PEM_read_PUBKEY
158.Fa "FILE *fp"
159.Fa "EVP_PKEY **x"
160.Fa "pem_password_cb *cb"
161.Fa "void *u"
162.Fc
163.Ft int
164.Fo PEM_write_bio_PUBKEY
165.Fa "BIO *bp"
166.Fa "EVP_PKEY *x"
167.Fc
168.Ft int
169.Fo PEM_write_PUBKEY
170.Fa "FILE *fp"
171.Fa "EVP_PKEY *x"
172.Fc
173.Ft RSA *
174.Fo PEM_read_bio_RSAPrivateKey
175.Fa "BIO *bp"
176.Fa "RSA **x"
177.Fa "pem_password_cb *cb"
178.Fa "void *u"
179.Fc
180.Ft RSA *
181.Fo PEM_read_RSAPrivateKey
182.Fa "FILE *fp"
183.Fa "RSA **x"
184.Fa "pem_password_cb *cb"
185.Fa "void *u"
186.Fc
187.Ft int
188.Fo PEM_write_bio_RSAPrivateKey
189.Fa "BIO *bp"
190.Fa "RSA *x"
191.Fa "const EVP_CIPHER *enc"
192.Fa "unsigned char *kstr"
193.Fa "int klen"
194.Fa "pem_password_cb *cb"
195.Fa "void *u"
196.Fc
197.Ft int
198.Fo PEM_write_RSAPrivateKey
199.Fa "FILE *fp"
200.Fa "RSA *x"
201.Fa "const EVP_CIPHER *enc"
202.Fa "unsigned char *kstr"
203.Fa "int klen"
204.Fa "pem_password_cb *cb"
205.Fa "void *u"
206.Fc
207.Ft RSA *
208.Fo PEM_read_bio_RSAPublicKey
209.Fa "BIO *bp"
210.Fa "RSA **x"
211.Fa "pem_password_cb *cb"
212.Fa "void *u"
213.Fc
214.Ft RSA *
215.Fo PEM_read_RSAPublicKey
216.Fa "FILE *fp"
217.Fa "RSA **x"
218.Fa "pem_password_cb *cb"
219.Fa "void *u"
220.Fc
221.Ft int
222.Fo PEM_write_bio_RSAPublicKey
223.Fa "BIO *bp"
224.Fa "RSA *x"
225.Fc
226.Ft int
227.Fo PEM_write_RSAPublicKey
228.Fa "FILE *fp"
229.Fa "RSA *x"
230.Fc
231.Ft RSA *
232.Fo PEM_read_bio_RSA_PUBKEY
233.Fa "BIO *bp"
234.Fa "RSA **x"
235.Fa "pem_password_cb *cb"
236.Fa "void *u"
237.Fc
238.Ft RSA *
239.Fo PEM_read_RSA_PUBKEY
240.Fa "FILE *fp"
241.Fa "RSA **x"
242.Fa "pem_password_cb *cb"
243.Fa "void *u"
244.Fc
245.Ft int
246.Fo PEM_write_bio_RSA_PUBKEY
247.Fa "BIO *bp"
248.Fa "RSA *x"
249.Fc
250.Ft int
251.Fo PEM_write_RSA_PUBKEY
252.Fa "FILE *fp"
253.Fa "RSA *x"
254.Fc
255.Ft DSA *
256.Fo PEM_read_bio_DSAPrivateKey
257.Fa "BIO *bp"
258.Fa "DSA **x"
259.Fa "pem_password_cb *cb"
260.Fa "void *u"
261.Fc
262.Ft DSA *
263.Fo PEM_read_DSAPrivateKey
264.Fa "FILE *fp"
265.Fa "DSA **x"
266.Fa "pem_password_cb *cb"
267.Fa "void *u"
268.Fc
269.Ft int
270.Fo PEM_write_bio_DSAPrivateKey
271.Fa "BIO *bp"
272.Fa "DSA *x"
273.Fa "const EVP_CIPHER *enc"
274.Fa "unsigned char *kstr"
275.Fa "int klen"
276.Fa "pem_password_cb *cb"
277.Fa "void *u"
278.Fc
279.Ft int
280.Fo PEM_write_DSAPrivateKey
281.Fa "FILE *fp"
282.Fa "DSA *x"
283.Fa "const EVP_CIPHER *enc"
284.Fa "unsigned char *kstr"
285.Fa "int klen"
286.Fa "pem_password_cb *cb"
287.Fa "void *u"
288.Fc
289.Ft DSA *
290.Fo PEM_read_bio_DSA_PUBKEY
291.Fa "BIO *bp"
292.Fa "DSA **x"
293.Fa "pem_password_cb *cb"
294.Fa "void *u"
295.Fc
296.Ft DSA *
297.Fo PEM_read_DSA_PUBKEY
298.Fa "FILE *fp"
299.Fa "DSA **x"
300.Fa "pem_password_cb *cb"
301.Fa "void *u"
302.Fc
303.Ft int
304.Fo PEM_write_bio_DSA_PUBKEY
305.Fa "BIO *bp"
306.Fa "DSA *x"
307.Fc
308.Ft int
309.Fo PEM_write_DSA_PUBKEY
310.Fa "FILE *fp"
311.Fa "DSA *x"
312.Fc
313.Ft DSA *
314.Fo PEM_read_bio_DSAparams
315.Fa "BIO *bp"
316.Fa "DSA **x"
317.Fa "pem_password_cb *cb"
318.Fa "void *u"
319.Fc
320.Ft DSA *
321.Fo PEM_read_DSAparams
322.Fa "FILE *fp"
323.Fa "DSA **x"
324.Fa "pem_password_cb *cb"
325.Fa "void *u"
326.Fc
327.Ft int
328.Fo PEM_write_bio_DSAparams
329.Fa "BIO *bp"
330.Fa "DSA *x"
331.Fc
332.Ft int
333.Fo PEM_write_DSAparams
334.Fa "FILE *fp"
335.Fa "DSA *x"
336.Fc
337.Ft DH *
338.Fo PEM_read_bio_DHparams
339.Fa "BIO *bp"
340.Fa "DH **x"
341.Fa "pem_password_cb *cb"
342.Fa "void *u"
343.Fc
344.Ft DH *
345.Fo PEM_read_DHparams
346.Fa "FILE *fp"
347.Fa "DH **x"
348.Fa "pem_password_cb *cb"
349.Fa "void *u"
350.Fc
351.Ft int
352.Fo PEM_write_bio_DHparams
353.Fa "BIO *bp"
354.Fa "DH *x"
355.Fc
356.Ft int
357.Fo PEM_write_DHparams
358.Fa "FILE *fp"
359.Fa "DH *x"
360.Fc
361.Ft X509 *
362.Fo PEM_read_bio_X509
363.Fa "BIO *bp"
364.Fa "X509 **x"
365.Fa "pem_password_cb *cb"
366.Fa "void *u"
367.Fc
368.Ft X509 *
369.Fo PEM_read_X509
370.Fa "FILE *fp"
371.Fa "X509 **x"
372.Fa "pem_password_cb *cb"
373.Fa "void *u"
374.Fc
375.Ft int
376.Fo PEM_write_bio_X509
377.Fa "BIO *bp"
378.Fa "X509 *x"
379.Fc
380.Ft int
381.Fo PEM_write_X509
382.Fa "FILE *fp"
383.Fa "X509 *x"
384.Fc
385.Ft X509 *
386.Fo PEM_read_bio_X509_AUX
387.Fa "BIO *bp"
388.Fa "X509 **x"
389.Fa "pem_password_cb *cb"
390.Fa "void *u"
391.Fc
392.Ft X509 *
393.Fo PEM_read_X509_AUX
394.Fa "FILE *fp"
395.Fa "X509 **x"
396.Fa "pem_password_cb *cb"
397.Fa "void *u"
398.Fc
399.Ft int
400.Fo PEM_write_bio_X509_AUX
401.Fa "BIO *bp"
402.Fa "X509 *x"
403.Fc
404.Ft int
405.Fo PEM_write_X509_AUX
406.Fa "FILE *fp"
407.Fa "X509 *x"
408.Fc
409.Ft X509_REQ *
410.Fo PEM_read_bio_X509_REQ
411.Fa "BIO *bp"
412.Fa "X509_REQ **x"
413.Fa "pem_password_cb *cb"
414.Fa "void *u"
415.Fc
416.Ft X509_REQ *
417.Fo PEM_read_X509_REQ
418.Fa "FILE *fp"
419.Fa "X509_REQ **x"
420.Fa "pem_password_cb *cb"
421.Fa "void *u"
422.Fc
423.Ft int
424.Fo PEM_write_bio_X509_REQ
425.Fa "BIO *bp"
426.Fa "X509_REQ *x"
427.Fc
428.Ft int
429.Fo PEM_write_X509_REQ
430.Fa "FILE *fp"
431.Fa "X509_REQ *x"
432.Fc
433.Ft int
434.Fo PEM_write_bio_X509_REQ_NEW
435.Fa "BIO *bp"
436.Fa "X509_REQ *x"
437.Fc
438.Ft int
439.Fo PEM_write_X509_REQ_NEW
440.Fa "FILE *fp"
441.Fa "X509_REQ *x"
442.Fc
443.Ft X509_CRL *
444.Fo PEM_read_bio_X509_CRL
445.Fa "BIO *bp"
446.Fa "X509_CRL **x"
447.Fa "pem_password_cb *cb"
448.Fa "void *u"
449.Fc
450.Ft X509_CRL *
451.Fo PEM_read_X509_CRL
452.Fa "FILE *fp"
453.Fa "X509_CRL **x"
454.Fa "pem_password_cb *cb"
455.Fa "void *u"
456.Fc
457.Ft int
458.Fo PEM_write_bio_X509_CRL
459.Fa "BIO *bp"
460.Fa "X509_CRL *x"
461.Fc
462.Ft int
463.Fo PEM_write_X509_CRL
464.Fa "FILE *fp"
465.Fa "X509_CRL *x"
466.Fc
467.Ft PKCS7 *
468.Fo PEM_read_bio_PKCS7
469.Fa "BIO *bp"
470.Fa "PKCS7 **x"
471.Fa "pem_password_cb *cb"
472.Fa "void *u"
473.Fc
474.Ft PKCS7 *
475.Fo PEM_read_PKCS7
476.Fa "FILE *fp"
477.Fa "PKCS7 **x"
478.Fa "pem_password_cb *cb"
479.Fa "void *u"
480.Fc
481.Ft int
482.Fo PEM_write_bio_PKCS7
483.Fa "BIO *bp"
484.Fa "PKCS7 *x"
485.Fc
486.Ft int
487.Fo PEM_write_PKCS7
488.Fa "FILE *fp"
489.Fa "PKCS7 *x"
490.Fc
491.Ft NETSCAPE_CERT_SEQUENCE *
492.Fo PEM_read_bio_NETSCAPE_CERT_SEQUENCE
493.Fa "BIO *bp"
494.Fa "NETSCAPE_CERT_SEQUENCE **x"
495.Fa "pem_password_cb *cb"
496.Fa "void *u"
497.Fc
498.Ft NETSCAPE_CERT_SEQUENCE *
499.Fo PEM_read_NETSCAPE_CERT_SEQUENCE
500.Fa "FILE *fp"
501.Fa "NETSCAPE_CERT_SEQUENCE **x"
502.Fa "pem_password_cb *cb"
503.Fa "void *u"
504.Fc
505.Ft int
506.Fo PEM_write_bio_NETSCAPE_CERT_SEQUENCE
507.Fa "BIO *bp"
508.Fa "NETSCAPE_CERT_SEQUENCE *x"
509.Fc
510.Ft int
511.Fo PEM_write_NETSCAPE_CERT_SEQUENCE
512.Fa "FILE *fp"
513.Fa "NETSCAPE_CERT_SEQUENCE *x"
514.Fc
515.Sh DESCRIPTION
516The PEM functions read or write structures in PEM format.
517In this sense PEM format is simply base64 encoded data surrounded by
518header lines.
519.Pp
520For more details about the meaning of arguments see the
521.Sx PEM function arguments
522section.
523.Pp
524Each operation has four functions associated with it.
525For clarity the term
526.Dq Sy foobar No functions
527will be used to collectively refer to the
528.Fn PEM_read_bio_foobar ,
529.Fn PEM_read_foobar ,
530.Fn PEM_write_bio_foobar ,
531and
532.Fn PEM_write_foobar
533functions.
534.Pp
535The
536.Sy PrivateKey
537functions read or write a private key in PEM format using an
538.Vt EVP_PKEY
539structure.
540The write routines use "traditional" private key format and can handle
541both RSA and DSA private keys.
542The read functions can additionally transparently handle PKCS#8 format
543encrypted and unencrypted keys, too.
544.Pp
545.Fn PEM_write_bio_PKCS8PrivateKey
546and
547.Fn PEM_write_PKCS8PrivateKey
548write a private key in an
549.Vt EVP_PKEY
550structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5
551v2.0 password based encryption algorithms.
552The
553.Fa enc
554argument specifies the encryption algorithm to use: unlike all other PEM
555routines, the encryption is applied at the PKCS#8 level and not in the
556PEM headers.
557If
558.Fa enc
559is
560.Dv NULL ,
561then no encryption is used and a PKCS#8 PrivateKeyInfo structure
562is used instead.
563.Pp
564.Fn PEM_write_bio_PKCS8PrivateKey_nid
565and
566.Fn PEM_write_PKCS8PrivateKey_nid
567also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo.
568However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead.
569The algorithm to use is specified in the
570.Fa nid
571parameter and should be the NID of the corresponding OBJECT IDENTIFIER
572(see NOTES section).
573.Pp
574The
575.Sy PUBKEY
576functions process a public key using an
577.Vt EVP_PKEY
578structure.
579The public key is encoded as a SubjectPublicKeyInfo structure.
580.Pp
581The
582.Sy RSAPrivateKey
583functions process an RSA private key using an
584.Vt RSA
585structure.
586They handle the same formats as the
587.Sy PrivateKey
588functions, but an error occurs if the private key is not RSA.
589.Pp
590The
591.Sy RSAPublicKey
592functions process an RSA public key using an
593.Vt RSA
594structure.
595The public key is encoded using a PKCS#1 RSAPublicKey structure.
596.Pp
597The
598.Sy RSA_PUBKEY
599functions also process an RSA public key using an
600.Vt RSA
601structure.
602However the public key is encoded using a SubjectPublicKeyInfo structure
603and an error occurs if the public key is not RSA.
604.Pp
605The
606.Sy DSAPrivateKey
607functions process a DSA private key using a
608.Vt DSA
609structure.
610They handle the same formats as the
611.Sy PrivateKey
612functions but an error occurs if the private key is not DSA.
613.Pp
614The
615.Sy DSA_PUBKEY
616functions process a DSA public key using a
617.Vt DSA
618structure.
619The public key is encoded using a SubjectPublicKeyInfo structure and an
620error occurs if the public key is not DSA.
621.Pp
622The
623.Sy DSAparams
624functions process DSA parameters using a
625.Vt DSA
626structure.
627The parameters are encoded using a Dss-Parms structure as defined in RFC 2459.
628.Pp
629The
630.Sy DHparams
631functions process DH parameters using a
632.Vt DH
633structure.
634The parameters are encoded using a PKCS#3 DHparameter structure.
635.Pp
636The
637.Sy X509
638functions process an X509 certificate using an
639.Vt X509
640structure.
641They will also process a trusted X509 certificate but any trust settings
642are discarded.
643.Pp
644The
645.Sy X509_AUX
646functions process a trusted X509 certificate using an
647.Vt X509
648structure.
649.Pp
650The
651.Sy X509_REQ
652and
653.Sy X509_REQ_NEW
654functions process a PKCS#10 certificate request using an
655.Vt X509_REQ
656structure.
657The
658.Sy X509_REQ
659write functions use CERTIFICATE REQUEST in the header whereas the
660.Sy X509_REQ_NEW
661functions use NEW CERTIFICATE REQUEST (as required by some CAs).
662The
663.Sy X509_REQ
664read functions will handle either form so there are no
665.Sy X509_REQ_NEW
666read functions.
667.Pp
668The
669.Sy X509_CRL
670functions process an X509 CRL using an
671.Vt X509_CRL
672structure.
673.Pp
674The
675.Sy PKCS7
676functions process a PKCS#7 ContentInfo using a
677.Vt PKCS7
678structure.
679.Pp
680The
681.Sy NETSCAPE_CERT_SEQUENCE
682functions process a Netscape Certificate Sequence using a
683.Vt NETSCAPE_CERT_SEQUENCE
684structure.
685.Pp
686The old
687.Sy PrivateKey
688write routines are retained for compatibility.
689New applications should write private keys using the
690.Fn PEM_write_bio_PKCS8PrivateKey
691or
692.Fn PEM_write_PKCS8PrivateKey
693routines because they are more secure (they use an iteration count of
6942048 whereas the traditional routines use a count of 1) unless
695compatibility with older versions of OpenSSL is important.
696.Pp
697The
698.Sy PrivateKey
699read routines can be used in all applications because they handle all
700formats transparently.
701.Ss PEM function arguments
702The PEM functions have many common arguments.
703.Pp
704The
705.Fa bp
706parameter specifies the
707.Vt BIO
708to read from or write to.
709.Pp
710The
711.Fa fp
712parameter specifies the
713.Vt FILE
714pointer to read from or write to.
715.Pp
716The PEM read functions all take a pointer to pointer argument
717.Fa x
718and return a pointer of the same type.
719If
720.Fa x
721is
722.Dv NULL ,
723then the parameter is ignored.
724If
725.Fa x
726is not
727.Dv NULL
728but
729.Pf * Fa x
730is
731.Dv NULL ,
732then the structure returned will be written to
733.Pf * Fa x .
734If neither
735.Fa x
736nor
737.Pf * Fa x
738are
739.Dv NULL ,
740then an attempt is made to reuse the structure at
741.Pf * Fa x ,
742but see the
743.Sx BUGS
744and
745.Sx EXAMPLES
746sections.
747Irrespective of the value of
748.Fa x ,
749a pointer to the structure is always returned, or
750.Dv NULL
751if an error occurred.
752.Pp
753The PEM functions which write private keys take an
754.Fa enc
755parameter which specifies the encryption algorithm to use.
756Encryption is done at the PEM level.
757If this parameter is set to
758.Dv NULL ,
759then the private key is written in unencrypted form.
760.Pp
761The
762.Fa cb
763argument is the callback to use when querying for the passphrase used
764for encrypted PEM structures (normally only private keys).
765.Pp
766For the PEM write routines, if the
767.Fa kstr
768parameter is not
769.Dv NULL ,
770then
771.Fa klen
772bytes at
773.Fa kstr
774are used as the passphrase and
775.Fa cb
776is ignored.
777.Pp
778If the
779.Fa cb
780parameters is set to
781.Dv NULL
782and the
783.Fa u
784parameter is not
785.Dv NULL ,
786then the
787.Fa u
788parameter is interpreted as a null terminated string to use as the
789passphrase.
790If both
791.Fa cb
792and
793.Fa u
794are
795.Dv NULL ,
796then the default callback routine is used which will typically
797prompt for the passphrase on the current terminal with echoing
798turned off.
799.Pp
800The default passphrase callback is sometimes inappropriate (for example
801in a GUI application) so an alternative can be supplied.
802The callback routine has the following form:
803.Bd -filled -offset inset
804.Ft int
805.Fo cb
806.Fa "char *buf"
807.Fa "int size"
808.Fa "int rwflag"
809.Fa "void *u"
810.Fc
811.Ed
812.Pp
813.Fa buf
814is the buffer to write the passphrase to.
815.Fa size
816is the maximum length of the passphrase, i.e. the size of
817.Fa buf .
818.Fa rwflag
819is a flag which is set to 0 when reading and 1 when writing.
820A typical routine will ask the user to verify the passphrase (for
821example by prompting for it twice) if
822.Fa rwflag
823is 1.
824The
825.Fa u
826parameter has the same value as the
827.Fa u
828parameter passed to the PEM routine.
829It allows arbitrary data to be passed to the callback by the application
830(for example a window handle in a GUI application).
831The callback must return the number of characters in the passphrase
832or 0 if an error occurred.
833.Ss PEM encryption format
834This old
835.Sy PrivateKey
836routines use a non standard technique for encryption.
837.Pp
838The private key (or other data) takes the following form:
839.Bd -literal -offset indent
840-----BEGIN RSA PRIVATE KEY-----
841Proc-Type: 4,ENCRYPTED
842DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
843
844\&...base64 encoded data...
845-----END RSA PRIVATE KEY-----
846.Ed
847.Pp
848The line beginning with
849.Dq DEK-Info
850contains two comma separated pieces of information:
851the encryption algorithm name as used by
852.Xr EVP_get_cipherbyname 3
853and an 8 byte salt encoded as a set of hexadecimal digits.
854.Pp
855After this is the base64 encoded encrypted data.
856.Pp
857The encryption key is determined using
858.Xr EVP_BytesToKey 3 ,
859using the salt and an iteration count of 1.
860The IV used is the value of the salt and *not* the IV returned by
861.Xr EVP_BytesToKey 3 .
862.Sh RETURN VALUES
863The read routines return either a pointer to the structure read or
864.Dv NULL
865if an error occurred.
866.Pp
867The write routines return 1 for success or 0 for failure.
868.Sh EXAMPLES
869Although the PEM routines take several arguments, in almost all
870applications most of them are set to 0 or
871.Dv NULL .
872.Pp
873Read a certificate in PEM format from a
874.Vt BIO :
875.Bd -literal
876X509 *x;
877x = PEM_read_bio_X509(bp, NULL, 0, NULL);
878if (x == NULL) {
879 /* Error */
880}
881.Ed
882.Pp
883Alternative method:
884.Bd -literal
885X509 *x = NULL;
886if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
887 /* Error */
888}
889.Ed
890.Pp
891Write a certificate to a
892.Vt BIO :
893.Bd -literal
894if (!PEM_write_bio_X509(bp, x)) {
895 /* Error */
896}
897.Ed
898.Pp
899Write an unencrypted private key to a
900.Vt FILE :
901.Bd -literal
902if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
903 /* Error */
904}
905.Ed
906.Pp
907Write a private key (using traditional format) to a
908.Vt BIO
909using triple DES encryption, the pass phrase is prompted for:
910.Bd -literal
911if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
912 NULL, 0, 0, NULL)) {
913 /* Error */
914}
915.Ed
916.Pp
917Write a private key (using PKCS#8 format) to a
918.Vt BIO
919using triple DES encryption, using the pass phrase "hello":
920.Bd -literal
921if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
922 NULL, 0, 0, "hello")) {
923 /* Error */
924}
925.Ed
926.Pp
927Read a private key from a
928.Vt BIO
929using the pass phrase "hello":
930.Bd -literal
931key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
932if (key == NULL) {
933 /* Error */
934}
935.Ed
936.Pp
937Read a private key from a
938.Vt BIO
939using a pass phrase callback:
940.Bd -literal
941key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
942if (key == NULL) {
943 /* Error */
944}
945.Ed
946.Pp
947Skeleton pass phrase callback:
948.Bd -literal
949int
950pass_cb(char *buf, int size, int rwflag, void *u)
951{
952 int len;
953 char *tmp;
954
955 /* We'd probably do something else if 'rwflag' is 1 */
956 printf("Enter pass phrase for \e"%s\e"\en", u);
957
958 /* get pass phrase, length 'len' into 'tmp' */
959 tmp = "hello";
960 len = strlen(tmp);
961
962 if (len == 0)
963 return 0;
964 /* if too long, truncate */
965 if (len > size)
966 len = size;
967 memcpy(buf, tmp, len);
968 return len;
969}
970.Ed
971.Sh CAVEATS
972A frequent cause of problems is attempting to use the PEM routines like
973this:
974.Bd -literal
975X509 *x;
976PEM_read_bio_X509(bp, &x, 0, NULL);
977.Ed
978.Pp
979This is a bug because an attempt will be made to reuse the data at
980.Fa x
981which is an uninitialised pointer.
982.Sh BUGS
983The PEM read routines in some versions of OpenSSL will not correctly
984reuse an existing structure.
985Therefore
986.Pp
987.Dl PEM_read_bio_X509(bp, &x, 0, NULL);
988.Pp
989where
990.Fa x
991already contains a valid certificate may not work, whereas
992.Bd -literal -offset indent
993X509_free(x);
994x = PEM_read_bio_X509(bp, NULL, 0, NULL);
995.Ed
996.Pp
997is guaranteed to work.
diff --git a/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3
new file mode 100644
index 0000000000..12d556558d
--- /dev/null
+++ b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3
@@ -0,0 +1,40 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PEM_WRITE_BIO_PKCS7_STREAM 3
3.Os
4.Sh NAME
5.Nm PEM_write_bio_PKCS7_stream
6.Nd output PKCS7 structure in PEM format
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.In openssl/pem.h
10.Ft int
11.Fo PEM_write_bio_PKCS7_stream
12.Fa "BIO *out"
13.Fa "PKCS7 *p7"
14.Fa "BIO *data"
15.Fa "int flags"
16.Fc
17.Sh DESCRIPTION
18.Fn PEM_write_bio_PKCS7_stream
19outputs a PKCS7 structure in PEM format.
20.Pp
21It is otherwise identical to the function
22.Xr SMIME_write_PKCS7 3 .
23.Pp
24This function is effectively a version of the
25.Xr PEM_write_bio_PKCS7 3
26supporting streaming.
27.Sh RETURN VALUES
28.Fn PEM_write_bio_PKCS7_stream
29returns 1 for success or 0 for failure.
30.Sh SEE ALSO
31.Xr ERR_get_error 3 ,
32.Xr i2d_PKCS7_bio_stream 3 ,
33.Xr PKCS7_decrypt 3 ,
34.Xr PKCS7_encrypt 3 ,
35.Xr PKCS7_sign 3 ,
36.Xr PKCS7_verify 3 ,
37.Xr SMIME_write_PKCS7 3
38.Sh HISTORY
39.Fn PEM_write_bio_PKCS7_stream
40was added to OpenSSL 1.0.0.
diff --git a/src/lib/libcrypto/man/PKCS12_create.3 b/src/lib/libcrypto/man/PKCS12_create.3
new file mode 100644
index 0000000000..0a7f0c2ab5
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS12_create.3
@@ -0,0 +1,122 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS12_CREATE 3
3.Os
4.Sh NAME
5.Nm PKCS12_create
6.Nd create a PKCS#12 structure
7.Sh SYNOPSIS
8.In openssl/pkcs12.h
9.Ft PKCS12 *
10.Fo PKCS12_create
11.Fa "char *pass"
12.Fa "char *name"
13.Fa "EVP_PKEY *pkey"
14.Fa "X509 *cert"
15.Fa "STACK_OF(X509) *ca"
16.Fa "int nid_key"
17.Fa "int nid_cert"
18.Fa "int iter"
19.Fa "int mac_iter"
20.Fa "int keytype"
21.Fc
22.Sh DESCRIPTION
23.Fn PKCS12_create
24creates a PKCS#12 structure.
25.Pp
26.Fa pass
27is the passphrase to use.
28.Fa name
29is the
30.Sy friendlyName
31to use for the supplied certificate and key.
32.Fa pkey
33is the private key to include in the structure and
34.Fa cert
35its corresponding certificates.
36.Fa ca
37is an optional set of certificates to also include in the structure.
38.Fa pkey ,
39.Fa cert ,
40or both can be
41.Dv NULL
42to indicate that no key or certificate is required.
43.Pp
44.Fa nid_key
45and
46.Fa nid_cert
47are the encryption algorithms that should be used for the key and
48certificate, respectively.
49If either
50.Fa nid_key
51or
52.Fa nid_cert
53is set to -1, no encryption will be used.
54.Pp
55.Fa iter
56is the encryption algorithm iteration count to use and
57.Fa mac_iter
58is the MAC iteration count to use.
59If
60.Fa mac_iter
61is set to -1, the MAC will be omitted entirely.
62.Pp
63.Fa keytype
64is the type of key.
65.Pp
66The parameters
67.Fa nid_key ,
68.Fa nid_cert ,
69.Fa iter ,
70.Fa mac_iter ,
71and
72.Fa keytype
73can all be set to zero and sensible defaults will be used.
74.Pp
75These defaults are: 40 bit RC2 encryption for certificates, triple DES
76encryption for private keys, a key iteration count of
77PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1.
78.Pp
79The default MAC iteration count is 1 in order to retain compatibility
80with old software which did not interpret MAC iteration counts.
81If such compatibility is not required then
82.Fa mac_iter
83should be set to PKCS12_DEFAULT_ITER.
84.Pp
85.Fa keytype
86adds a flag to the store private key.
87This is a non standard extension that is only currently interpreted by
88MSIE.
89If set to zero the flag is omitted, if set to
90.Dv KEY_SIG
91the key can be used for signing only, and if set to
92.Dv KEY_EX
93it can be used for signing and encryption.
94This option was useful for old export grade software which could use
95signing only keys of arbitrary size but had restrictions on the
96permissible sizes of keys which could be used for encryption.
97.Pp
98If a certificate contains an
99.Sy alias
100or
101.Sy keyid
102then this will be used for the corresponding
103.Sy friendlyName
104or
105.Sy localKeyID
106in the PKCS12 structure.
107.Sh SEE ALSO
108.Xr d2i_PKCS12 3
109.Sh HISTORY
110PKCS12_create was added in OpenSSL 0.9.3.
111.Pp
112Before OpenSSL 0.9.8, neither
113.Fa pkey
114nor
115.Fa cert
116were allowed to be
117.Dv NULL ,
118and a value of -1 was not allowed for
119.Fa nid_key ,
120.Fa nid_cert ,
121and
122.Fa mac_iter .
diff --git a/src/lib/libcrypto/man/PKCS12_parse.3 b/src/lib/libcrypto/man/PKCS12_parse.3
new file mode 100644
index 0000000000..6930bdf339
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS12_parse.3
@@ -0,0 +1,90 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS12_PARSE 3
3.Os
4.Sh NAME
5.Nm PKCS12_parse
6.Nd parse a PKCS#12 structure
7.Sh SYNOPSIS
8.In openssl/pkcs12.h
9.Ft int
10.Fo PKCS12_parse
11.Fa "PKCS12 *p12"
12.Fa "const char *pass"
13.Fa "EVP_PKEY **pkey"
14.Fa "X509 **cert"
15.Fa "STACK_OF(X509) **ca"
16.Fc
17.Sh DESCRIPTION
18.Fn PKCS12_parse
19parses a PKCS12 structure.
20.Pp
21.Fa p12
22is the
23.Vt PKCS12
24structure to parse.
25.Fa pass
26is the passphrase to use.
27If successful, the private key will be written to
28.Pf * Fa pkey ,
29the corresponding certificate to
30.Pf * Fa cert ,
31and any additional certificates to
32.Pf * Fa ca .
33.Pp
34The parameters
35.Fa pkey
36and
37.Fa cert
38cannot be
39.Dv NULL .
40.Fa ca
41can be
42.Dv NULL ,
43in which case additional certificates will be discarded.
44.Pf * Fa ca
45can also be a valid STACK in which case additional certificates are
46appended to
47.Pf * Fa ca .
48If
49.Pf * Fa ca
50is
51.Dv NULL ,
52a new STACK will be allocated.
53.Pp
54The
55.Sy friendlyName
56and
57.Sy localKeyID
58attributes (if present) of each certificate will be stored in the
59.Fa alias
60and
61.Fa keyid
62attributes of the
63.Vt X509
64structure.
65.Sh RETURN VALUES
66.Fn PKCS12_parse
67returns 1 for success and 0 if an error occurred.
68.Pp
69The error can be obtained from
70.Xr ERR_get_error 3 .
71.Sh SEE ALSO
72.Xr d2i_PKCS12 3
73.Sh HISTORY
74PKCS12_parse was added in OpenSSL 0.9.3.
75.Sh BUGS
76Only a single private key and corresponding certificate is returned by
77this function.
78More complex PKCS#12 files with multiple private keys will only return
79the first match.
80.Pp
81Only
82.Sy friendlyName
83and
84.Sy localKeyID
85attributes are currently stored in certificates.
86Other attributes are discarded.
87.Pp
88Attributes currently cannot be stored in the private key
89.Vt EVP_PKEY
90structure.
diff --git a/src/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3 b/src/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3
new file mode 100644
index 0000000000..333e45250e
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3
@@ -0,0 +1,106 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS5_PBKDF2_HMAC 3
3.Os
4.Sh NAME
5.Nm PKCS5_PBKDF2_HMAC ,
6.Nm PKCS5_PBKDF2_HMAC_SHA1
7.Nd password based derivation routines with salt and iteration count
8.Sh SYNOPSIS
9.In openssl/evp.h
10.Ft int
11.Fo PKCS5_PBKDF2_HMAC
12.Fa "const char *pass"
13.Fa "int passlen"
14.Fa "const unsigned char *salt"
15.Fa "int saltlen"
16.Fa "int iter"
17.Fa "const EVP_MD *digest"
18.Fa "int keylen"
19.Fa "unsigned char *out"
20.Fc
21.Ft int
22.Fo PKCS5_PBKDF2_HMAC_SHA1
23.Fa "const char *pass"
24.Fa "int passlen"
25.Fa "const unsigned char *salt"
26.Fa "int saltlen"
27.Fa "int iter"
28.Fa "int keylen"
29.Fa "unsigned char *out"
30.Fc
31.Sh DESCRIPTION
32.Fn PKCS5_PBKDF2_HMAC
33derives a key from a password using a salt and iteration count as
34specified in RFC 2898.
35.Pp
36.Fa pass
37is the password used in the derivation of length
38.Fa passlen .
39.Fa pass
40is an optional parameter and can be
41.Dv NULL .
42If
43.Fa passlen
44is -1, then the function will calculate the length of
45.Fa pass
46using
47.Xr strlen 3 .
48.Pp
49.Fa salt
50is the salt used in the derivation of length
51.Fa saltlen .
52If the
53.Fa salt
54is
55.Dv NULL ,
56then
57.Fa saltlen
58must be 0.
59The function will not attempt to calculate the length of the
60.Fa salt
61because it is not assumed to be NUL terminated.
62.Pp
63.Fa iter
64is the iteration count and its value should be greater than or equal to 1.
65RFC 2898 suggests an iteration count of at least 1000.
66Any
67.Fa iter
68less than 1 is treated as a single iteration.
69.Pp
70.Fa digest
71is the message digest function used in the derivation.
72Values include any of the EVP_* message digests.
73.Fn PKCS5_PBKDF2_HMAC_SHA1
74calls
75.Fn PKCS5_PBKDF2_HMAC
76with
77.Xr EVP_sha1 3 .
78.Pp
79The derived key will be written to
80.Fa out .
81The size of the
82.Fa out
83buffer is specified via
84.Fa keylen .
85.Pp
86A typical application of this function is to derive keying material for
87an encryption algorithm from a password in the
88.Fa pass ,
89a salt in
90.Fa salt ,
91and an iteration count.
92.Pp
93Increasing the
94.Fa iter
95parameter slows down the algorithm which makes it harder for an attacker
96to perform a brute force attack using a large number of candidate
97passwords.
98.Sh RETURN VALUES
99.Fn PKCS5_PBKDF2_HMAC
100and
101.Fn PBKCS5_PBKDF2_HMAC_SHA1
102return 1 on success or 0 on error.
103.Sh SEE ALSO
104.Xr evp 3 ,
105.Xr EVP_BytesToKey 3 ,
106.Xr rand 3
diff --git a/src/lib/libcrypto/man/PKCS7_decrypt.3 b/src/lib/libcrypto/man/PKCS7_decrypt.3
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_decrypt.3
diff --git a/src/lib/libcrypto/man/PKCS7_encrypt.3 b/src/lib/libcrypto/man/PKCS7_encrypt.3
new file mode 100644
index 0000000000..860a9181b8
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_encrypt.3
@@ -0,0 +1,113 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS7_ENCRYPT 3
3.Os
4.Sh NAME
5.Nm PKCS7_encrypt
6.Nd create a PKCS#7 envelopedData structure
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft PKCS7 *
10.Fo PKCS7_encrypt
11.Fa "STACK_OF(X509) *certs"
12.Fa "BIO *in"
13.Fa "const EVP_CIPHER *cipher"
14.Fa "int flags"
15.Fc
16.Sh DESCRIPTION
17.Fn PKCS7_encrypt
18creates and returns a PKCS#7 envelopedData structure.
19.Fa certs
20is a list of recipient certificates.
21.Fa in
22is the content to be encrypted.
23.Fa cipher
24is the symmetric cipher to use.
25.Fa flags
26is an optional set of flags.
27.Pp
28Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
29certificates supplied to this function must all contain RSA public keys,
30though they do not have to be signed using the RSA algorithm.
31.Pp
32The algorithm passed in the
33.Fa cipher
34parameter must support ASN1 encoding of its parameters.
35.Pp
36Many browsers implement a "sign and encrypt" option which is simply an
37S/MIME envelopedData containing an S/MIME signed message.
38This can be readily produced by storing the S/MIME signed message in a
39memory
40.Vt BIO
41and passing it to
42.Fn PKCS7_encrypt .
43.Pp
44The following flags can be passed in the
45.Fa flags
46parameter.
47.Pp
48If the
49.Dv PKCS7_TEXT
50flag is set, MIME headers for type
51.Sy text/plain
52are prepended to the data.
53.Pp
54Normally the supplied content is translated into MIME canonical format
55(as required by the S/MIME specifications).
56If
57.Dv PKCS7_BINARY
58is set, no translation occurs.
59This option should be used if the supplied data is in binary format;
60otherwise, the translation will corrupt it.
61If
62.Dv PKCS7_BINARY
63is set, then
64.Dv PKCS7_TEXT
65is ignored.
66.Pp
67If the
68.Dv PKCS7_STREAM
69flag is set, a partial
70.Vt PKCS7
71structure is output suitable for streaming I/O: no data is read from
72.Fa in .
73.Pp
74If the flag
75.Dv PKCS7_STREAM
76is set, the returned
77.Vt PKCS7
78structure is
79.Sy not
80complete and outputting its contents via a function that does not
81properly finalize the
82.Vt PKCS7
83structure will give unpredictable results.
84.Pp
85Several functions including
86.Xr SMIME_write_PKCS7 3 ,
87.Xr i2d_PKCS7_bio_stream 3 ,
88and
89.Xr PEM_write_bio_PKCS7_stream 3
90finalize the structure.
91Alternatively finalization can be performed by obtaining the streaming
92ASN1
93.Vt BIO
94directly using
95.Xr BIO_new_PKCS7 3 .
96.Sh RETURN VALUES
97.Fn PKCS7_encrypt
98returns either a
99.Vt PKCS7
100structure or
101.Dv NULL
102if an error occurred.
103The error can be obtained from
104.Xr ERR_get_error 3 .
105.Sh SEE ALSO
106.Xr ERR_get_error 3 ,
107.Xr PKCS7_decrypt 3
108.Sh HISTORY
109.Xr PKCS7_decrypt 3
110was added to OpenSSL 0.9.5.
111The
112.Dv PKCS7_STREAM
113flag was first supported in OpenSSL 1.0.0.
diff --git a/src/lib/libcrypto/man/PKCS7_sign.3 b/src/lib/libcrypto/man/PKCS7_sign.3
new file mode 100644
index 0000000000..894472402d
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_sign.3
@@ -0,0 +1,190 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS7_SIGN 3
3.Os
4.Sh NAME
5.Nm PKCS7_sign
6.Nd create a PKCS#7 signedData structure
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft PKCS7 *
10.Fo PKCS7_sign
11.Fa "X509 *signcert"
12.Fa "EVP_PKEY *pkey"
13.Fa "STACK_OF(X509) *certs"
14.Fa "BIO *data"
15.Fa "int flags"
16.Fc
17.Sh DESCRIPTION
18.Fn PKCS7_sign
19creates and returns a PKCS#7 signedData structure.
20.Fa signcert
21is the certificate to sign with,
22.Fa pkey
23is the corresponding private key.
24.Fa certs
25is an optional additional set of certificates to include in the PKCS#7
26structure (for example any intermediate CAs in the chain).
27.Pp
28The data to be signed is read from
29.Vt BIO
30.Fa data .
31.Pp
32.Fa flags
33is an optional set of flags.
34.Pp
35Any of the following flags (OR'ed together) can be passed in the
36.Fa flags
37parameter.
38.Pp
39Many S/MIME clients expect the signed content to include valid MIME
40headers.
41If the
42.Dv PKCS7_TEXT
43flag is set, MIME headers for type
44.Sy text/plain
45are prepended to the data.
46.Pp
47If
48.Dv PKCS7_NOCERTS
49is set, the signer's certificate will not be included in the PKCS7
50structure, the signer's certificate must still be supplied in the
51.Fa signcert
52parameter though.
53This can reduce the size of the signature if the signers certificate can
54be obtained by other means: for example a previously signed message.
55.Pp
56The data being signed is included in the
57.Vt PKCS7
58structure, unless
59.Dv PKCS7_DETACHED
60is set in which case it is omitted.
61This is used for PKCS7 detached signatures which are used in S/MIME
62plaintext signed messages for example.
63.Pp
64Normally the supplied content is translated into MIME canonical format
65(as required by the S/MIME specifications).
66If
67.Dv PKCS7_BINARY
68is set, no translation occurs.
69This option should be used if the supplied data is in binary format;
70otherwise, the translation will corrupt it.
71.Pp
72The signedData structure includes several PKCS#7 authenticatedAttributes
73including the signing time, the PKCS#7 content type and the supported
74list of ciphers in an SMIMECapabilities attribute.
75If
76.Dv PKCS7_NOATTR
77is set, then no authenticatedAttributes will be used.
78If
79.Dv PKCS7_NOSMIMECAP
80is set, then just the SMIMECapabilities are omitted.
81.Pp
82If present, the SMIMECapabilities attribute indicates support for the
83following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40
84bit RC2.
85If any of these algorithms is disabled then it will not be included.
86.Pp
87If the flags
88.Dv PKCS7_STREAM
89is set, then the returned
90.Vt PKCS7
91structure is just initialized ready to perform the signing operation.
92The signing is however
93.Sy not
94performed and the data to be signed is not read from the
95.Fa data
96parameter.
97Signing is deferred until after the data has been written.
98In this way data can be signed in a single pass.
99.Pp
100If the
101.Dv PKCS7_PARTIAL
102flag is set, a partial
103.Vt PKCS7
104structure is output to which additional signers and capabilities can be
105added before finalization.
106.Pp
107If the flag
108.Dv PKCS7_STREAM
109is set, the returned
110.Vt PKCS7
111structure is
112.Sy not
113complete and outputting its contents via a function that does not
114properly finalize the
115.Vt PKCS7
116structure will give unpredictable results.
117.Pp
118Several functions including
119.Xr SMIME_write_PKCS7 3 ,
120.Xr i2d_PKCS7_bio_stream 3 ,
121.Xr PEM_write_bio_PKCS7_stream 3
122finalize the structure.
123Alternatively finalization can be performed by obtaining the streaming
124ASN1
125.Vt BIO
126directly using
127.Xr BIO_new_PKCS7 3 .
128.Pp
129If a signer is specified, it will use the default digest for the
130signing algorithm.
131This is
132.Sy SHA1
133for both RSA and DSA keys.
134.Pp
135In OpenSSL 1.0.0, the
136.Fa certs ,
137.Fa signcert ,
138and
139.Fa pkey
140parameters can all be
141.Dv NULL
142if the
143.Dv PKCS7_PARTIAL
144flag is set.
145One or more signers can be added using the function
146.Xr PKCS7_sign_add_signer 3.
147.Xr PKCS7_final 3
148must also be called to finalize the structure if streaming is not
149enabled.
150Alternative signing digests can also be specified using this method.
151.Pp
152In OpenSSL 1.0.0, if
153.Fa signcert
154and
155.Fa pkey
156are
157.Dv NULL ,
158then a certificates only PKCS#7 structure is output.
159.Pp
160In versions of OpenSSL before 1.0.0 the
161.Fa signcert
162and
163.Fa pkey
164parameters must
165.Sy NOT
166be
167.Dv NULL .
168.Sh RETURN VALUES
169.Fn PKCS7_sign
170returns either a valid
171.Vt PKCS7
172structure or
173.Dv NULL
174if an error occurred.
175The error can be obtained from
176.Fn ERR_get_error 3 .
177.Sh SEE ALSO
178.Xr ERR_get_error 3 ,
179.Xr PKCS7_verify 3
180.Sh HISTORY
181.Fn PKCS7_sign
182was added to OpenSSL 0.9.5.
183.Pp
184The
185.Dv PKCS7_PARTIAL
186and
187.Dv PKCS7_STREAM
188flags were added in OpenSSL 1.0.0.
189.Sh BUGS
190Some advanced attributes such as counter signatures are not supported.
diff --git a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
new file mode 100644
index 0000000000..b20b6b91e6
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
@@ -0,0 +1,128 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS7_SIGN_ADD_SIGNER 3
3.Os
4.Sh NAME
5.Nm PKCS7_sign_add_signer
6.Nd add a signer PKCS7 signed data structure
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft PKCS7_SIGNER_INFO *
10.Fo PKCS7_sign_add_signer
11.Fa "PKCS7 *p7"
12.Fa "X509 *signcert"
13.Fa "EVP_PKEY *pkey"
14.Fa "const EVP_MD *md"
15.Fa "int flags"
16.Fc
17.Sh DESCRIPTION
18.Fn PKCS7_sign_add_signer
19adds a signer with certificate
20.Fa signcert
21and private key
22.Fa pkey
23using message digest
24.Fa md
25to a
26.Vt PKCS7
27signed data structure
28.Fa p7 .
29.Pp
30The
31.Vt PKCS7
32structure should be obtained from an initial call to
33.Xr PKCS7_sign 3
34with the flag
35.Dv PKCS7_PARTIAL
36set, or in the case or re-signing, a valid
37.Vt PKCS7
38signed data structure.
39.Pp
40If the
41.Fa md
42parameter is
43.Dv NULL ,
44then the default digest for the public key algorithm will be used.
45.Pp
46Unless the
47.Dv PKCS7_REUSE_DIGEST
48flag is set, the returned
49.Dv PKCS7
50structure is not complete and must be
51finalized either by streaming (if applicable) or by a call to
52.Xr PKCS7_final 3 .
53.Pp
54The main purpose of this function is to provide finer control over a
55PKCS#7 signed data structure where the simpler
56.Xr PKCS7_sign 3
57function defaults are not appropriate, for example if multiple
58signers or non default digest algorithms are needed.
59.Pp
60Any of the following flags (OR'ed together) can be passed in the
61.Fa flags
62parameter.
63.Pp
64If
65.Dv PKCS7_REUSE_DIGEST
66is set, then an attempt is made to copy the content digest value from the
67.Vt PKCS7
68structure: to add a signer to an existing structure.
69An error occurs if a matching digest value cannot be found to copy.
70The returned
71.Vt PKCS7
72structure will be valid and finalized when this flag is set.
73.Pp
74If
75.Dv PKCS7_PARTIAL
76is set in addition to
77.Dv PKCS7_REUSE_DIGEST ,
78then the
79.Dv PKCS7_SIGNER_INO
80structure will not be finalized, so additional attributes can be added.
81In this case an explicit call to
82.Xr PKCS7_SIGNER_INFO_sign 3
83is needed to finalize it.
84.Pp
85If
86.Dv PKCS7_NOCERTS
87is set, the signer's certificate will not be included in the
88.Vt PKCS7
89structure, the signer's certificate must still be supplied in the
90.Fa signcert
91parameter though.
92This can reduce the size of the signature if the signers certificate can
93be obtained by other means: for example a previously signed message.
94.Pp
95The signedData structure includes several PKCS#7 authenticatedAttributes
96including the signing time, the PKCS#7 content type and the supported
97list of ciphers in an SMIMECapabilities attribute.
98If
99.Dv PKCS7_NOATTR
100is set, then no authenticatedAttributes will be used.
101If
102.Dv PKCS7_NOSMIMECAP
103is set, then just the SMIMECapabilities are omitted.
104.Pp
105If present, the SMIMECapabilities attribute indicates support for the
106following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40
107bit RC2.
108If any of these algorithms is disabled, then it will not be included.
109.Pp
110.Fn PKCS7_sign_add_signer
111returns an internal pointer to the
112.Vt PKCS7_SIGNER_INFO
113structure just added, this can be used to set additional attributes
114before it is finalized.
115.Sh RETURN VALUES
116.Fn PKCS7_sign_add_signer
117returns an internal pointer to the
118.Vt PKCS7_SIGNER_INFO
119structure just added or
120.Dv NULL
121if an error occurs.
122.Sh SEE ALSO
123.Xr ERR_get_error 3 ,
124.Xr PKCS7_final 3 ,
125.Xr PKCS7_sign 3
126.Sh HISTORY
127.Xr PKCS7_sign_add_signer 3
128was added to OpenSSL 1.0.0.
diff --git a/src/lib/libcrypto/man/PKCS7_verify.3 b/src/lib/libcrypto/man/PKCS7_verify.3
new file mode 100644
index 0000000000..3cc6cbac66
--- /dev/null
+++ b/src/lib/libcrypto/man/PKCS7_verify.3
@@ -0,0 +1,193 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt PKCS7_VERIFY 3
3.Os
4.Sh NAME
5.Nm PKCS7_verify ,
6.Nm PKCS7_get0_signers
7.Nd verify a PKCS#7 signedData structure
8.Sh SYNOPSIS
9.In openssl/pkcs7.h
10.Ft int
11.Fo PKCS7_verify
12.Fa "PKCS7 *p7"
13.Fa "STACK_OF(X509) *certs"
14.Fa "X509_STORE *store"
15.Fa "BIO *indata"
16.Fa "BIO *out"
17.Fa "int flags"
18.Fc
19.Ft STACK_OF(X509) *
20.Fo PKCS7_get0_signers
21.Fa "PKCS7 *p7"
22.Fa "STACK_OF(X509) *certs"
23.Fa "int flags"
24.Fc
25.Sh DESCRIPTION
26.Fn PKCS7_verify
27verifies a PKCS#7 signedData structure.
28.Fa p7
29is the
30.Vt PKCS7
31structure to verify.
32.Fa certs
33is a set of certificates in which to search for the signer's
34certificate.
35.Fa store
36is a trusted certificate store (used for chain verification).
37.Fa indata
38is the signed data if the content is not present in
39.Fa p7 ,
40that is if it is detached.
41The content is written to
42.Fa out
43if it is not
44.Dv NULL .
45.Pp
46.Fa flags
47is an optional set of flags, which can be used to modify the verify
48operation.
49.Pp
50.Fn PKCS7_get0_signers
51retrieves the signer's certificates from
52.Fa p7 .
53It does
54.Sy not
55check their validity or whether any signatures are valid.
56The
57.Fa certs
58and
59.Fa flags
60parameters have the same meanings as in
61.Fn PKCS7_verify .
62.Pp
63Normally the verify process proceeds as follows.
64.Pp
65Initially some sanity checks are performed on
66.Fa p7 .
67The type of
68.Fa p7
69must be signedData.
70There must be at least one signature on the data and if the content
71is detached,
72.Fa indata
73cannot be
74.Dv NULL .
75.Pp
76An attempt is made to locate all the signer's certificates, first
77looking in the
78.Fa certs
79parameter (if it is not
80.Dv NULL )
81and then looking in any certificates contained in the
82.Fa p7
83structure itself.
84If any signer's certificates cannot be located the operation fails.
85.Pp
86Each signer's certificate is chain verified using the
87.Sy smimesign
88purpose and the supplied trusted certificate store.
89Any internal certificates in the message are used as untrusted CAs.
90If any chain verify fails an error code is returned.
91.Pp
92Finally, the signed content is read (and written to
93.Fa out
94is it is not
95.Dv NULL )
96and the signature's checked.
97.Pp
98If all signature's verify correctly then the function is successful.
99.Pp
100Any of the following flags (OR'ed together) can be passed in the
101.Fa flags
102parameter to change the default verify behaviour.
103Only the flag
104.Dv PKCS7_NOINTERN
105is meaningful to
106.Fn PKCS7_get0_signers .
107.Pp
108If
109.Dv PKCS7_NOINTERN
110is set, the certificates in the message itself are not searched when
111locating the signer's certificate.
112This means that all the signer's certificates must be in the
113.Fa certs
114parameter.
115.Pp
116If the
117.Dv PKCS7_TEXT
118flag is set, MIME headers for type
119.Sy text/plain
120are deleted from the content.
121If the content is not of type
122.Sy text/plain ,
123then an error is returned.
124.Pp
125If
126.Dv PKCS7_NOVERIFY
127is set, the signer's certificates are not chain verified.
128.Pp
129If
130.Dv PKCS7_NOCHAIN
131is set, then the certificates contained in the message are not used as
132untrusted CAs.
133This means that the whole verify chain (apart from the signer's
134certificate) must be contained in the trusted store.
135.Pp
136If
137.Dv PKCS7_NOSIGS
138is set, then the signatures on the data are not checked.
139.Pp
140One application of
141.Dv PKCS7_NOINTERN
142is to only accept messages signed by a small number of certificates.
143The acceptable certificates would be passed in the
144.Fa certs
145parameter.
146In this case, if the signer is not one of the certificates supplied in
147.Fa certs ,
148then the verify will fail because the signer cannot be found.
149.Pp
150Care should be taken when modifying the default verify behaviour, for
151example setting
152.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS
153will totally disable all verification and any signed message will be
154considered valid.
155This combination is however useful if one merely wishes to write the
156content to
157.Fa out
158and its validity is not considered important.
159.Pp
160Chain verification should arguably be performed using the signing time
161rather than the current time.
162However since the signing time is supplied by the signer, it cannot be
163trusted without additional evidence (such as a trusted timestamp).
164.Sh RETURN VALUES
165.Fn PKCS7_verify
166returns 1 for a successful verification and 0 or a negative value if
167an error occurs.
168.Pp
169.Fn PKCS7_get0_signers
170returns all signers or
171.Dv NULL
172if an error occurred.
173.Pp
174The error can be obtained from
175.Xr ERR_get_error 3 .
176.Sh SEE ALSO
177.Xr ERR_get_error 3 ,
178.Xr PKCS7_sign 3
179.Sh HISTORY
180.Fn PKCS7_verify
181was added to OpenSSL 0.9.5 .
182.Sh BUGS
183The trusted certificate store is not searched for the signer's
184certificate.
185This is primarily due to the inadequacies of the current
186.Vt X509_STORE
187functionality.
188.Pp
189The lack of single pass processing and the need to hold all data
190in memory as mentioned in
191.Xr PKCS7_sign 3
192also applies to
193.Fn PKCS7_verify .
diff --git a/src/lib/libcrypto/man/SMIME_read_PKCS7.3 b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
new file mode 100644
index 0000000000..2e7fcb514c
--- /dev/null
+++ b/src/lib/libcrypto/man/SMIME_read_PKCS7.3
@@ -0,0 +1,101 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt SMIME_READ_PKCS7 3
3.Os
4.Sh NAME
5.Nm SMIME_read_PKCS7
6.Nd parse S/MIME message
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft PKCS7 *
10.Fo SMIME_read_PKCS7
11.Fa "BIO *in"
12.Fa "BIO **bcont"
13.Fc
14.Sh DESCRIPTION
15.Fn SMIME_read_PKCS7
16parses a message in S/MIME format.
17.Pp
18.Fa in
19is a
20.Vt BIO
21to read the message from.
22.Pp
23If cleartext signing is used, then the content is saved in a memory
24.Vt BIO
25which is written to
26.Pf * Fa bcont ,
27otherwise
28.Pf * Fa bcont
29is set to
30.Dv NULL .
31.Pp
32The parsed PKCS#7 structure is returned, or
33.Dv NULL
34if an error occurred.
35.Pp
36If
37.Pf * Fa bcont
38is not
39.Dv NULL ,
40then the message is clear text signed.
41.Pf * Fa bcont
42can then be passed to
43.Xr PKCS7_verify 3
44with the
45.Dv PKCS7_DETACHED
46flag set.
47.Pp
48Otherwise the type of the returned structure can be determined using
49.Xr PKCS7_type 3 .
50.Pp
51To support future functionality, if
52.Fa bcont
53is not
54.Dv NULL ,
55.Pf * Fa bcont
56should be initialized to
57.Dv NULL .
58For example:
59.Bd -literal -offset indent
60BIO *cont = NULL;
61PKCS7 *p7;
62
63p7 = SMIME_read_PKCS7(in, &cont);
64.Ed
65.Sh RETURN VALUES
66.Fn SMIME_read_PKCS7
67returns a valid
68.Vt PKCS7
69structure or
70.Dv NULL
71if an error occurred.
72The error can be obtained from
73.Xr ERR_get_error 3 .
74.Sh SEE ALSO
75.Xr ERR_get_error 3 ,
76.Xr PKCS7_decrypt 3 ,
77.Xr PKCS7_encrypt 3 ,
78.Xr PKCS7_sign 3 ,
79.Xr PKCS7_type 3 ,
80.Xr PKCS7_verify 3 ,
81.Xr SMIME_read_PKCS7 3
82.Sh HISTORY
83.Fn SMIME_read_PKCS7
84was added to OpenSSL 0.9.5.
85.Sh BUGS
86The MIME parser used by
87.Fn SMIME_read_PKCS7
88is somewhat primitive.
89While it will handle most S/MIME messages, more complex compound
90formats may not work.
91.Pp
92The parser assumes that the
93.Vt PKCS7
94structure is always base64 encoded, and it will not handle the case
95where it is in binary format or uses quoted printable format.
96.Pp
97The use of a memory
98.Vt BIO
99to hold the signed content limits the size of the message which can
100be processed due to memory restraints: a streaming single pass
101option should be available.
diff --git a/src/lib/libcrypto/man/SMIME_write_PKCS7.3 b/src/lib/libcrypto/man/SMIME_write_PKCS7.3
new file mode 100644
index 0000000000..f4f465e2e4
--- /dev/null
+++ b/src/lib/libcrypto/man/SMIME_write_PKCS7.3
@@ -0,0 +1,93 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt SMIME_WRITE_PKCS7 3
3.Os
4.Sh NAME
5.Nm SMIME_write_PKCS7
6.Nd convert PKCS#7 structure to S/MIME format
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft int
10.Fo SMIME_write_PKCS7
11.Fa "BIO *out"
12.Fa "PKCS7 *p7"
13.Fa "BIO *data"
14.Fa "int flags"
15.Fc
16.Sh DESCRIPTION
17.Fn SMIME_write_PKCS7
18adds the appropriate MIME headers to a PKCS#7 structure to produce an
19S/MIME message.
20.Pp
21.Fa out
22is the
23.Vt BIO
24to write the data to.
25.Fa p7
26is the appropriate
27.Vt PKCS7
28structure.
29If streaming is enabled, then the content must be supplied in the
30.Fa data
31argument.
32.Fa flags
33is an optional set of flags.
34.Pp
35The following flags can be passed in the
36.Fa flags
37parameter.
38.Pp
39If
40.Dv PKCS7_DETACHED
41is set, then cleartext signing will be used.
42This option only makes sense for signedData where
43.Dv PKCS7_DETACHED
44is also set when
45.Xr PKCS7_sign 3
46is also called.
47.Pp
48If the
49.Dv PKCS7_TEXT
50flag is set, MIME headers for type
51.Sy text/plain
52are added to the content.
53This only makes sense if
54.Dv PKCS7_DETACHED
55is also set.
56.Pp
57If the
58.Dv PKCS7_STREAM
59flag is set, streaming is performed.
60This flag should only be set if
61.Dv PKCS7_STREAM
62was also set in the previous call to
63.Xr PKCS7_sign 3
64or
65.Xr PKCS7_encrypt 3 .
66.Pp
67If cleartext signing is being used and
68.Dv PKCS7_STREAM
69is not set, then the data must be read twice: once to compute the
70signature in
71.Xr PKCS7_sign 3
72and once to output the S/MIME message.
73.Pp
74If streaming is performed, the content is output in BER format using
75indefinite length constructed encoding except in the case of signed
76data with detached content where the content is absent and DER
77format is used.
78.Sh RETURN VALUES
79.Fn SMIME_write_PKCS7
80returns 1 for success or 0 for failure.
81.Sh SEE ALSO
82.Xr ERR_get_error 3 ,
83.Xr PKCS7_decrypt 3 ,
84.Xr PKCS7_encrypt 3 ,
85.Xr PKCS7_sign 3 ,
86.Xr PKCS7_verify 3
87.Sh HISTORY
88.Fn SMIME_write_PKCS7
89was added to OpenSSL 0.9.5.
90.Sh BUGS
91.Fn SMIME_write_PKCS7
92always base64 encodes PKCS#7 structures.
93There should be an option to disable this.
diff --git a/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 b/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3
new file mode 100644
index 0000000000..755bf3eb86
--- /dev/null
+++ b/src/lib/libcrypto/man/i2d_PKCS7_bio_stream.3
@@ -0,0 +1,44 @@
1.Dd $Mdocdate: November 3 2016 $
2.Dt I2D_PKCS7_BIO_STREAM 3
3.Os
4.Sh NAME
5.Nm i2d_PKCS7_bio_stream
6.Nd output PKCS7 structure in BER format
7.Sh SYNOPSIS
8.In openssl/pkcs7.h
9.Ft int
10.Fo i2d_PKCS7_bio_stream
11.Fa "BIO *out"
12.Fa "PKCS7 *p7"
13.Fa "BIO *data"
14.Fa "int flags"
15.Fc
16.Sh DESCRIPTION
17.Fn i2d_PKCS7_bio_stream
18outputs a
19.Vt PKCS7
20structure in BER format.
21.Pp
22It is otherwise identical to the function
23.Xr SMIME_write_PKCS7 3 .
24.Pp
25This function is effectively a version of
26.Xr d2i_PKCS7_bio 3
27supporting streaming.
28.Sh RETURN VALUES
29.Fn i2d_PKCS7_bio_stream
30returns 1 for success or 0 for failure.
31.Sh SEE ALSO
32.Xr ERR_get_error 3 ,
33.Xr PEM_write_bio_PKCS7_stream 3 ,
34.Xr PKCS7_decrypt 3 ,
35.Xr PKCS7_encrypt 3 ,
36.Xr PKCS7_sign 3 ,
37.Xr PKCS7_verify 3 ,
38.Xr SMIME_write_PKCS7 3
39.Sh HISTORY
40.Fn i2d_PKCS7_bio_stream
41was added to OpenSSL 1.0.0.
42.Sh BUGS
43The prefix "i2d" is arguably wrong because the function outputs BER
44format.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-21 19:47:58 +0000