convert PEM and PKCS manuals from pod to mdoc

1 files changed, 128 insertions, 0 deletions

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 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt PKCS7_SIGN_ADD_SIGNER 3
+.Os
+.Sh NAME
+.Nm PKCS7_sign_add_signer
+.Nd add a signer PKCS7 signed data structure
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft PKCS7_SIGNER_INFO *
+.Fo PKCS7_sign_add_signer
+.Fa "PKCS7 *p7"
+.Fa "X509 *signcert"
+.Fa "EVP_PKEY *pkey"
+.Fa "const EVP_MD *md"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_sign_add_signer
+adds a signer with certificate
+.Fa signcert
+and private key
+.Fa pkey
+using message digest
+.Fa md
+to a
+.Vt PKCS7
+signed data structure
+.Fa p7 .
+.Pp
+The
+.Vt PKCS7
+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
+.Vt PKCS7
+signed data structure.
+.Pp
+If the
+.Fa md
+parameter is
+.Dv NULL ,
+then the default digest for the public key algorithm will be used.
+.Pp
+Unless the
+.Dv PKCS7_REUSE_DIGEST
+flag is set, the returned
+.Dv PKCS7
+structure is not complete and must be
+finalized either by streaming (if applicable) or by a call to
+.Xr PKCS7_final 3 .
+.Pp
+The main purpose of this function is to provide finer control over a
+PKCS#7 signed data structure where the simpler
+.Xr PKCS7_sign 3
+function defaults are not appropriate, for example if multiple
+signers or non default digest algorithms are needed.
+.Pp
+Any of the following flags (OR'ed together) can be passed in the
+.Fa flags
+parameter.
+.Pp
+If
+.Dv PKCS7_REUSE_DIGEST
+is set, then an attempt is made to copy the content digest value from the
+.Vt PKCS7
+structure: to add a signer to an existing structure.
+An error occurs if a matching digest value cannot be found to copy.
+The returned
+.Vt PKCS7
+structure will be valid and finalized when this flag is set.
+.Pp
+If
+.Dv PKCS7_PARTIAL
+is set in addition to
+.Dv PKCS7_REUSE_DIGEST ,
+then the
+.Dv PKCS7_SIGNER_INO
+structure will not be finalized, so additional attributes can be added.
+In this case an explicit call to
+.Xr PKCS7_SIGNER_INFO_sign 3
+is needed to finalize it.
+.Pp
+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
+.Fa signcert
+parameter though.
+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
+The signedData structure includes several PKCS#7 authenticatedAttributes
+including the signing time, the PKCS#7 content type and the supported
+list of ciphers in an SMIMECapabilities attribute.
+If
+.Dv PKCS7_NOATTR
+is set, then no authenticatedAttributes will be used.
+If
+.Dv PKCS7_NOSMIMECAP
+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.
+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
+before it is finalized.
+.Sh RETURN VALUES
+.Fn PKCS7_sign_add_signer
+returns an internal pointer to the
+.Vt PKCS7_SIGNER_INFO
+structure just added or
+.Dv NULL
+if an error occurs.
+.Sh SEE ALSO
+.Xr ERR_get_error 3 ,
+.Xr PKCS7_final 3 ,
+.Xr PKCS7_sign 3
+.Sh HISTORY
+.Xr PKCS7_sign_add_signer 3
+was added to OpenSSL 1.0.0.