From 7202341c67bf9540414b1bb3d732e66d2a7489cf Mon Sep 17 00:00:00 2001
From: jmc <>
Date: Thu, 24 Nov 2016 19:45:16 +0000
Subject: various cleanup; leaving dangling PKCS7* Xr for now...

---
 src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3    | 48 +++++++++++-----------
 src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 |  6 +--
 src/lib/libcrypto/man/PKCS12_create.3              | 12 +++---
 src/lib/libcrypto/man/PKCS12_parse.3               |  6 +--
 src/lib/libcrypto/man/PKCS7_decrypt.3              |  6 +--
 src/lib/libcrypto/man/PKCS7_encrypt.3              | 12 +++---
 src/lib/libcrypto/man/PKCS7_sign.3                 | 25 +++++------
 src/lib/libcrypto/man/PKCS7_sign_add_signer.3      | 16 ++++----
 src/lib/libcrypto/man/PKCS7_verify.3               |  6 +--
 9 files changed, 68 insertions(+), 69 deletions(-)

(limited to 'src/lib')

diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index 8532ef1b27..1ffafd69ed 100644
--- a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -1,10 +1,9 @@
-.\"	$OpenBSD: PEM_read_bio_PrivateKey.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PEM_read_bio_PrivateKey.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
-.Nm PEM ,
 .Nm PEM_read_bio_PrivateKey ,
 .Nm PEM_read_PrivateKey ,
 .Nm PEM_write_bio_PrivateKey ,
@@ -516,7 +515,7 @@
 .Fc
 .Sh DESCRIPTION
 The PEM functions read or write structures in PEM format.
-In this sense PEM format is simply base64 encoded data surrounded by
+In this sense PEM format is simply base64-encoded data surrounded by
 header lines.
 .Pp
 For more details about the meaning of arguments see the
@@ -542,7 +541,7 @@ structure.
 The write routines use "traditional" private key format and can handle
 both RSA and DSA private keys.
 The read functions can additionally transparently handle PKCS#8 format
-encrypted and unencrypted keys, too.
+encrypted and unencrypted keys too.
 .Pp
 .Fn PEM_write_bio_PKCS8PrivateKey
 and
@@ -570,8 +569,7 @@ also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo.
 However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead.
 The algorithm to use is specified in the
 .Fa nid
-parameter and should be the NID of the corresponding OBJECT IDENTIFIER
-(see NOTES section).
+parameter and should be the NID of the corresponding OBJECT IDENTIFIER.
 .Pp
 The
 .Sy PUBKEY
@@ -754,7 +752,7 @@ if an error occurred.
 .Pp
 The PEM functions which write private keys take an
 .Fa enc
-parameter which specifies the encryption algorithm to use.
+parameter, which specifies the encryption algorithm to use.
 Encryption is done at the PEM level.
 If this parameter is set to
 .Dv NULL ,
@@ -779,7 +777,7 @@ is ignored.
 .Pp
 If the
 .Fa cb
-parameters is set to
+parameter is set to
 .Dv NULL
 and the
 .Fa u
@@ -795,7 +793,7 @@ and
 .Fa u
 are
 .Dv NULL ,
-then the default callback routine is used which will typically
+then the default callback routine is used, which will typically
 prompt for the passphrase on the current terminal with echoing
 turned off.
 .Pp
@@ -835,7 +833,7 @@ or 0 if an error occurred.
 .Ss PEM encryption format
 This old
 .Sy PrivateKey
-routines use a non standard technique for encryption.
+routines use a non-standard technique for encryption.
 .Pp
 The private key (or other data) takes the following form:
 .Bd -literal -offset indent
@@ -852,9 +850,9 @@ The line beginning with
 contains two comma separated pieces of information:
 the encryption algorithm name as used by
 .Xr EVP_get_cipherbyname 3
-and an 8 byte salt encoded as a set of hexadecimal digits.
+and an 8-byte salt encoded as a set of hexadecimal digits.
 .Pp
-After this is the base64 encoded encrypted data.
+After this is the base64-encoded encrypted data.
 .Pp
 The encryption key is determined using
 .Xr EVP_BytesToKey 3 ,
@@ -874,7 +872,7 @@ applications most of them are set to 0 or
 .Pp
 Read a certificate in PEM format from a
 .Vt BIO :
-.Bd -literal
+.Bd -literal -offset indent
 X509 *x;
 x = PEM_read_bio_X509(bp, NULL, 0, NULL);
 if (x == NULL) {
@@ -883,7 +881,7 @@ if (x == NULL) {
 .Ed
 .Pp
 Alternative method:
-.Bd -literal
+.Bd -literal -offset indent
 X509 *x = NULL;
 if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
 	/* Error */
@@ -892,7 +890,7 @@ if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
 .Pp
 Write a certificate to a
 .Vt BIO :
-.Bd -literal
+.Bd -literal -offset indent
 if (!PEM_write_bio_X509(bp, x)) {
 	/* Error */
 }
@@ -900,7 +898,7 @@ if (!PEM_write_bio_X509(bp, x)) {
 .Pp
 Write an unencrypted private key to a
 .Vt FILE :
-.Bd -literal
+.Bd -literal -offset indent
 if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
 	/* Error */
 }
@@ -908,8 +906,8 @@ if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
 .Pp
 Write a private key (using traditional format) to a
 .Vt BIO
-using triple DES encryption, the pass phrase is prompted for:
-.Bd -literal
+using triple DES encryption; the pass phrase is prompted for:
+.Bd -literal -offset indent
 if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
     NULL, 0, 0, NULL)) {
 	/* Error */
@@ -919,7 +917,7 @@ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
 Write a private key (using PKCS#8 format) to a
 .Vt BIO
 using triple DES encryption, using the pass phrase "hello":
-.Bd -literal
+.Bd -literal -offset indent
 if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
     NULL, 0, 0, "hello")) {
 	/* Error */
@@ -929,7 +927,7 @@ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
 Read a private key from a
 .Vt BIO
 using the pass phrase "hello":
-.Bd -literal
+.Bd -literal -offset indent
 key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
 if (key == NULL) {
 	/* Error */
@@ -939,7 +937,7 @@ if (key == NULL) {
 Read a private key from a
 .Vt BIO
 using a pass phrase callback:
-.Bd -literal
+.Bd -literal -offset indent
 key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
 if (key == NULL) {
 	/* Error */
@@ -947,7 +945,7 @@ if (key == NULL) {
 .Ed
 .Pp
 Skeleton pass phrase callback:
-.Bd -literal
+.Bd -literal -offset indent
 int
 pass_cb(char *buf, int size, int rwflag, void *u)
 {
@@ -973,13 +971,13 @@ pass_cb(char *buf, int size, int rwflag, void *u)
 .Sh CAVEATS
 A frequent cause of problems is attempting to use the PEM routines like
 this:
-.Bd -literal
+.Bd -literal -offset indent
 X509 *x;
 PEM_read_bio_X509(bp, &x, 0, NULL);
 .Ed
 .Pp
 This is a bug because an attempt will be made to reuse the data at
-.Fa x
+.Fa x ,
 which is an uninitialised pointer.
 .Sh BUGS
 The PEM read routines in some versions of OpenSSL will not correctly
diff --git a/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3
index 12d3d781eb..3726a8b8b7 100644
--- a/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3
+++ b/src/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PEM_write_bio_PKCS7_stream.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PEM_WRITE_BIO_PKCS7_STREAM 3
 .Os
 .Sh NAME
@@ -23,7 +23,7 @@ outputs a PKCS7 structure in PEM format.
 It is otherwise identical to the function
 .Xr SMIME_write_PKCS7 3 .
 .Pp
-This function is effectively a version of the
+This function is effectively a version of
 .Xr PEM_write_bio_PKCS7 3
 supporting streaming.
 .Sh RETURN VALUES
diff --git a/src/lib/libcrypto/man/PKCS12_create.3 b/src/lib/libcrypto/man/PKCS12_create.3
index f638fbf82e..adca492d63 100644
--- a/src/lib/libcrypto/man/PKCS12_create.3
+++ b/src/lib/libcrypto/man/PKCS12_create.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS12_create.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS12_create.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS12_CREATE 3
 .Os
 .Sh NAME
@@ -74,7 +74,7 @@ and
 .Fa keytype
 can all be set to zero and sensible defaults will be used.
 .Pp
-These defaults are: 40 bit RC2 encryption for certificates, triple DES
+These defaults are: 40-bit RC2 encryption for certificates, triple DES
 encryption for private keys, a key iteration count of
 PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1.
 .Pp
@@ -86,11 +86,11 @@ should be set to PKCS12_DEFAULT_ITER.
 .Pp
 .Fa keytype
 adds a flag to the store private key.
-This is a non standard extension that is only currently interpreted by
+This is a non-standard extension that is only currently interpreted by
 MSIE.
-If set to zero the flag is omitted, if set to
+If set to zero the flag is omitted; if set to
 .Dv KEY_SIG
-the key can be used for signing only, and if set to
+the key can be used for signing only; and if set to
 .Dv KEY_EX
 it can be used for signing and encryption.
 This option was useful for old export grade software which could use
diff --git a/src/lib/libcrypto/man/PKCS12_parse.3 b/src/lib/libcrypto/man/PKCS12_parse.3
index 69786d49c0..d7bcd63b01 100644
--- a/src/lib/libcrypto/man/PKCS12_parse.3
+++ b/src/lib/libcrypto/man/PKCS12_parse.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS12_parse.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS12_parse.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS12_PARSE 3
 .Os
 .Sh NAME
@@ -44,7 +44,7 @@ can be
 .Dv NULL ,
 in which case additional certificates will be discarded.
 .Pf * Fa ca
-can also be a valid STACK in which case additional certificates are
+can also be a valid STACK, in which case additional certificates are
 appended to
 .Pf * Fa ca .
 If
diff --git a/src/lib/libcrypto/man/PKCS7_decrypt.3 b/src/lib/libcrypto/man/PKCS7_decrypt.3
index fa006af0ad..1abd87df4b 100644
--- a/src/lib/libcrypto/man/PKCS7_decrypt.3
+++ b/src/lib/libcrypto/man/PKCS7_decrypt.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS7_decrypt.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS7_decrypt.3,v 1.4 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS7_DECRYPT 3
 .Os
 .Sh NAME
@@ -35,7 +35,7 @@ is an optional set of flags.
 about unknown algorithms will occur.
 .Pp
 Although the recipient's certificate is not needed to decrypt the data,
-it is needed to locate the appropriate (of possible several) recipients
+it is needed to locate the appropriate recipients
 in the PKCS#7 structure.
 .Pp
 If the
diff --git a/src/lib/libcrypto/man/PKCS7_encrypt.3 b/src/lib/libcrypto/man/PKCS7_encrypt.3
index 1ab99c917c..56c22c85e3 100644
--- a/src/lib/libcrypto/man/PKCS7_encrypt.3
+++ b/src/lib/libcrypto/man/PKCS7_encrypt.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS7_encrypt.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS7_encrypt.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS7_ENCRYPT 3
 .Os
 .Sh NAME
@@ -33,7 +33,7 @@ though they do not have to be signed using the RSA algorithm.
 .Pp
 The algorithm passed in the
 .Fa cipher
-parameter must support ASN1 encoding of its parameters.
+parameter must support ASN.1 encoding of its parameters.
 .Pp
 Many browsers implement a "sign and encrypt" option which is simply an
 S/MIME envelopedData containing an S/MIME signed message.
@@ -84,14 +84,14 @@ properly finalize the
 .Vt PKCS7
 structure will give unpredictable results.
 .Pp
-Several functions including
+Several functions, including
 .Xr SMIME_write_PKCS7 3 ,
 .Xr i2d_PKCS7_bio_stream 3 ,
 and
-.Xr PEM_write_bio_PKCS7_stream 3
+.Xr PEM_write_bio_PKCS7_stream 3 ,
 finalize the structure.
 Alternatively finalization can be performed by obtaining the streaming
-ASN1
+ASN.1
 .Vt BIO
 directly using
 .Xr BIO_new_PKCS7 3 .
diff --git a/src/lib/libcrypto/man/PKCS7_sign.3 b/src/lib/libcrypto/man/PKCS7_sign.3
index 6dfdde2616..3ae651dd82 100644
--- a/src/lib/libcrypto/man/PKCS7_sign.3
+++ b/src/lib/libcrypto/man/PKCS7_sign.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS7_sign.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS7_sign.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS7_SIGN 3
 .Os
 .Sh NAME
@@ -49,17 +49,17 @@ are prepended to the data.
 If
 .Dv PKCS7_NOCERTS
 is set, the signer's certificate will not be included in the PKCS7
-structure, the signer's certificate must still be supplied in the
+structure, though the signer's certificate must still be supplied in the
 .Fa signcert
-parameter though.
-This can reduce the size of the signature if the signers certificate can
+parameter.
+This can reduce the size of the signature if the signer's certificate can
 be obtained by other means: for example a previously signed message.
 .Pp
 The data being signed is included in the
 .Vt PKCS7
 structure, unless
 .Dv PKCS7_DETACHED
-is set in which case it is omitted.
+is set, in which case it is omitted.
 This is used for PKCS7 detached signatures which are used in S/MIME
 plaintext signed messages for example.
 .Pp
@@ -82,8 +82,8 @@ If
 is set, then just the SMIMECapabilities are omitted.
 .Pp
 If present, the SMIMECapabilities attribute indicates support for the
-following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40
-bit RC2.
+following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES
+and 40-bit RC2.
 If any of these algorithms is disabled then it will not be included.
 .Pp
 If the flags
@@ -117,13 +117,14 @@ properly finalize the
 .Vt PKCS7
 structure will give unpredictable results.
 .Pp
-Several functions including
+Several functions, including
 .Xr SMIME_write_PKCS7 3 ,
 .Xr i2d_PKCS7_bio_stream 3 ,
-.Xr PEM_write_bio_PKCS7_stream 3
+and
+.Xr PEM_write_bio_PKCS7_stream 3 ,
 finalize the structure.
 Alternatively finalization can be performed by obtaining the streaming
-ASN1
+ASN.1
 .Vt BIO
 directly using
 .Xr BIO_new_PKCS7 3 .
@@ -157,7 +158,7 @@ and
 .Fa pkey
 are
 .Dv NULL ,
-then a certificates only PKCS#7 structure is output.
+then a certificate-only PKCS#7 structure is output.
 .Pp
 In versions of OpenSSL before 1.0.0 the
 .Fa signcert
diff --git a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
index 9ec6a54818..11000196a1 100644
--- a/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
+++ b/src/lib/libcrypto/man/PKCS7_sign_add_signer.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS7_sign_add_signer.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS7_sign_add_signer.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS7_SIGN_ADD_SIGNER 3
 .Os
 .Sh NAME
@@ -35,7 +35,7 @@ structure should be obtained from an initial call to
 .Xr PKCS7_sign 3
 with the flag
 .Dv PKCS7_PARTIAL
-set, or in the case or re-signing, a valid
+set or, in the case or re-signing, a valid
 .Vt PKCS7
 signed data structure.
 .Pp
@@ -88,9 +88,9 @@ If
 .Dv PKCS7_NOCERTS
 is set, the signer's certificate will not be included in the
 .Vt PKCS7
-structure, the signer's certificate must still be supplied in the
+structure, though the signer's certificate must still be supplied in the
 .Fa signcert
-parameter though.
+parameter.
 This can reduce the size of the signature if the signers certificate can
 be obtained by other means: for example a previously signed message.
 .Pp
@@ -105,14 +105,14 @@ If
 is set, then just the SMIMECapabilities are omitted.
 .Pp
 If present, the SMIMECapabilities attribute indicates support for the
-following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40
-bit RC2.
+following algorithms: triple DES, 128-bit RC2, 64-bit RC2, DES
+and 40-bit RC2.
 If any of these algorithms is disabled, then it will not be included.
 .Pp
 .Fn PKCS7_sign_add_signer
 returns an internal pointer to the
 .Vt PKCS7_SIGNER_INFO
-structure just added, this can be used to set additional attributes
+structure just added, which can be used to set additional attributes
 before it is finalized.
 .Sh RETURN VALUES
 .Fn PKCS7_sign_add_signer
diff --git a/src/lib/libcrypto/man/PKCS7_verify.3 b/src/lib/libcrypto/man/PKCS7_verify.3
index 11439915bd..8d1b9f6a0c 100644
--- a/src/lib/libcrypto/man/PKCS7_verify.3
+++ b/src/lib/libcrypto/man/PKCS7_verify.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: PKCS7_verify.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: PKCS7_verify.3,v 1.3 2016/11/24 19:45:16 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 24 2016 $
 .Dt PKCS7_VERIFY 3
 .Os
 .Sh NAME
@@ -93,7 +93,7 @@ If any chain verify fails an error code is returned.
 .Pp
 Finally, the signed content is read (and written to
 .Fa out
-is it is not
+if it is not
 .Dv NULL )
 and the signature's checked.
 .Pp
-- 
cgit v1.2.3-55-g6feb