1 files changed, 190 insertions, 0 deletions

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 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt PKCS7_SIGN 3
+.Os
+.Sh NAME
+.Nm PKCS7_sign
+.Nd create a PKCS#7 signedData structure
+.Sh SYNOPSIS
+.In openssl/pkcs7.h
+.Ft PKCS7 *
+.Fo PKCS7_sign
+.Fa "X509 *signcert"
+.Fa "EVP_PKEY *pkey"
+.Fa "STACK_OF(X509) *certs"
+.Fa "BIO *data"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn PKCS7_sign
+creates and returns a PKCS#7 signedData structure.
+.Fa signcert
+is the certificate to sign with,
+.Fa pkey
+is the corresponding private key.
+.Fa certs
+is an optional additional set of certificates to include in the PKCS#7
+structure (for example any intermediate CAs in the chain).
+.Pp
+The data to be signed is read from
+.Vt BIO
+.Fa data .
+.Pp
+.Fa flags
+is an optional set of flags.
+.Pp
+Any of the following flags (OR'ed together) can be passed in the
+.Fa flags
+parameter.
+.Pp
+Many S/MIME clients expect the signed content to include valid MIME
+headers.
+If the
+.Dv PKCS7_TEXT
+flag is set, MIME headers for type
+.Sy text/plain
+are prepended to the data.
+.Pp
+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
+.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 data being signed is included in the
+.Vt PKCS7
+structure, unless
+.Dv PKCS7_DETACHED
+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
+Normally the supplied content is translated into MIME canonical format
+(as required by the S/MIME specifications).
+If
+.Dv PKCS7_BINARY
+is set, no translation occurs.
+This option should be used if the supplied data is in binary format;
+otherwise, the translation will corrupt it.
+.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
+If the flags
+.Dv PKCS7_STREAM
+is set, then the returned
+.Vt PKCS7
+structure is just initialized ready to perform the signing operation.
+The signing is however
+.Sy not
+performed and the data to be signed is not read from the
+.Fa data
+parameter.
+Signing is deferred until after the data has been written.
+In this way data can be signed in a single pass.
+.Pp
+If the
+.Dv PKCS7_PARTIAL
+flag is set, a partial
+.Vt PKCS7
+structure is output to which additional signers and capabilities can be
+added before finalization.
+.Pp
+If the flag
+.Dv PKCS7_STREAM
+is set, the returned
+.Vt PKCS7
+structure is
+.Sy not
+complete and outputting its contents via a function that does not
+properly finalize the
+.Vt PKCS7
+structure will give unpredictable results.
+.Pp
+Several functions including
+.Xr SMIME_write_PKCS7 3 ,
+.Xr i2d_PKCS7_bio_stream 3 ,
+.Xr PEM_write_bio_PKCS7_stream 3
+finalize the structure.
+Alternatively finalization can be performed by obtaining the streaming
+ASN1
+.Vt BIO
+directly using
+.Xr BIO_new_PKCS7 3 .
+.Pp
+If a signer is specified, it will use the default digest for the
+signing algorithm.
+This is
+.Sy SHA1
+for both RSA and DSA keys.
+.Pp
+In OpenSSL 1.0.0, the
+.Fa certs ,
+.Fa signcert ,
+and
+.Fa pkey
+parameters can all be
+.Dv NULL
+if the
+.Dv PKCS7_PARTIAL
+flag is set.
+One or more signers can be added using the function
+.Xr PKCS7_sign_add_signer 3.
+.Xr PKCS7_final 3
+must also be called to finalize the structure if streaming is not
+enabled.
+Alternative signing digests can also be specified using this method.
+.Pp
+In OpenSSL 1.0.0, if
+.Fa signcert
+and
+.Fa pkey
+are
+.Dv NULL ,
+then a certificates only PKCS#7 structure is output.
+.Pp
+In versions of OpenSSL before 1.0.0 the
+.Fa signcert
+and
+.Fa pkey
+parameters must
+.Sy NOT
+be
+.Dv NULL .
+.Sh RETURN VALUES
+.Fn PKCS7_sign
+returns either a valid
+.Vt PKCS7
+structure or
+.Dv NULL
+if an error occurred.
+The error can be obtained from
+.Fn ERR_get_error 3 .
+.Sh SEE ALSO
+.Xr ERR_get_error 3 ,
+.Xr PKCS7_verify 3
+.Sh HISTORY
+.Fn PKCS7_sign
+was added to OpenSSL 0.9.5.
+.Pp
+The
+.Dv PKCS7_PARTIAL
+and
+.Dv PKCS7_STREAM
+flags were added in OpenSSL 1.0.0.
+.Sh BUGS
+Some advanced attributes such as counter signatures are not supported.