Update from 1.0.0-stable

[oweals/openssl.git] / doc / crypto / PKCS7_sign.pod

diff --git a/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod
index 95c4609d3c7f859a78b6ab13209d0306a6feb465..ffd0c734b096ffb309ffc116de4dad3cda40ec76 100644 (file)
--- a/doc/crypto/PKCS7_sign.pod
+++ b/doc/crypto/PKCS7_sign.pod
@@ -47,6 +47,42 @@ an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedA
 will be used. If B<PKCS7_NOSMIMECAP> is set then just the SMIMECapabilities are
 omitted.
 
+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.
+
+If the flags B<PKCS7_PARTSIGN> is set then the returned B<PKCS7> structure
+is just initialized ready to perform the signing operation. The signing
+is however B<not> performed and the data to be signed is not read from
+the B<data> parameter. Signing is deferred until after the data has been
+written. In this way data can be signed in a single pass. Currently the
+flag B<PKCS7_DETACHED> B<must> also be set.
+
+=head1 NOTES
+
+Currently the flag B<PKCS7_PARTSIGN> is only supported for detached
+data. If this flag is set the returned B<PKCS7> structure is B<not>
+complete and outputting its contents via a function that does not
+properly finalize the B<PKCS7> structure will give unpredictable 
+results.
+
+At present only the SMIME_write_PKCS7() function properly finalizes the
+structure.
+
+=head1 BUGS
+
+PKCS7_sign() is somewhat limited. It does not support multiple signers, some
+advanced attributes such as counter signatures are not supported.
+
+The SHA1 digest algorithm is currently always used.
+
+When the signed data is not detached it will be stored in memory within the
+B<PKCS7> structure. This effectively limits the size of messages which can be
+signed due to memory restraints. There should be a way to sign data without
+having to hold it all in memory, this would however require fairly major
+revisions of the OpenSSL ASN1 code.
+
+
 =head1 RETURN VALUES
 
 PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred.
@@ -58,6 +94,8 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
 
 =head1 HISTORY
 
-TBA
+PKCS7_sign() was added to OpenSSL 0.9.5
+
+The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8
 
 =cut