From 4cadedef57d790c699bc672cd39a41861590fabc Mon Sep 17 00:00:00 2001
From: "Dr. Stephen Henson" <steve@openssl.org>
Date: Sat, 15 Feb 2003 01:09:55 +0000
Subject: [PATCH] Update docs.

---
 doc/crypto/PKCS7_sign.pod        | 24 ++++++++++++++++++++----
 doc/crypto/SMIME_write_PKCS7.pod | 14 ++++++++------
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod
index fc7e649b34..ffd0c734b0 100644
--- a/doc/crypto/PKCS7_sign.pod
+++ b/doc/crypto/PKCS7_sign.pod
@@ -51,6 +51,24 @@ 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
@@ -64,10 +82,6 @@ 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.
 
-Clear text signing does not store the content in memory but the way PKCS7_sign()
-operates means that two passes of the data must typically be made: one to compute
-the signatures and a second to output the data along with the signature. There
-should be a way to process the data with only a single pass.
 
 =head1 RETURN VALUES
 
@@ -82,4 +96,6 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
 
 PKCS7_sign() was added to OpenSSL 0.9.5
 
+The B<PKCS7_PARTSIGN> flag was added in OpenSSL 0.9.8
+
 =cut
diff --git a/doc/crypto/SMIME_write_PKCS7.pod b/doc/crypto/SMIME_write_PKCS7.pod
index 2cfad2e049..61945b3887 100644
--- a/doc/crypto/SMIME_write_PKCS7.pod
+++ b/doc/crypto/SMIME_write_PKCS7.pod
@@ -30,18 +30,20 @@ If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain>
 are added to the content, this only makes sense if B<PKCS7_DETACHED>
 is also set.
 
-If cleartext signing is being used then the data must be read twice:
-once to compute the signature in PKCS7_sign() and once to output the
-S/MIME message.
+If the B<PKCS7_PARTSIGN> flag is set the signed data is finalized
+and output along with the content. This flag should only be set
+if B<PKCS7_DETACHED> is also set and the previous call to PKCS7_sign()
+also set these flags.
+
+If cleartext signing is being used and B<PKCS7_PARTSIGN> not set then
+the data must be read twice: once to compute the signature in PKCS7_sign()
+and once to output the S/MIME message.
 
 =head1 BUGS
 
 SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
 should be an option to disable this.
 
-There should really be a way to produce cleartext signing using only
-a single pass of the data.
-
 =head1 RETURN VALUES
 
 SMIME_write_PKCS7() returns 1 for success or 0 for failure.
-- 
2.25.1