OpenSSL CVS Repository
http://cvs.openssl.org/
____________________________________________________________
________________
Server: cvs.openssl.org Name: Dr.
Stephen Henson
Root: /v/openssl/cvs Email: steve openssl.org
Module: openssl Date:
13-Apr-2007 14:57:50
Branch: HEAD Handle:
2007041313574800
Modified files:
openssl/doc/crypto PKCS7_encrypt.pod
PKCS7_sign.pod
Log:
Update docs.
Summary:
Revision Changes Path
1.4 +35 -22
openssl/doc/crypto/PKCS7_encrypt.pod
1.5 +64 -51
openssl/doc/crypto/PKCS7_sign.pod
____________________________________________________________
________________
patch -p0 <<' .'
Index: openssl/doc/crypto/PKCS7_encrypt.pod
============================================================
================
$ cvs diff -u -r1.3 -r1.4 PKCS7_encrypt.pod
--- openssl/doc/crypto/PKCS7_encrypt.pod 14 May 2006
11:27:59 -0000 1.3
+++ openssl/doc/crypto/PKCS7_encrypt.pod 13 Apr 2007
12:57:48 -0000 1.4
-18,44 +18,56
=head1 NOTES
-Only RSA keys are supported in PKCS#7 and envelopedData
so the recipient certificates
-supplied to this function must all contain RSA public
keys, though they do not have to
-be signed using the RSA algorithm.
+Only RSA keys are supported in PKCS#7 and envelopedData
so the recipient
+certificates supplied to this function must all contain
RSA public keys, though
+they do not have to be signed using the RSA algorithm.
-EVP_des_ede3_cbc() (triple DES) is the algorithm of
choice for S/MIME use because
-most clients will support it.
+EVP_des_ede3_cbc() (triple DES) is the algorithm of
choice for S/MIME use
+because most clients will support it.
-Some old "export grade" clients may only
support weak encryption using 40 or 64 bit
-RC2. These can be used by passing EVP_rc2_40_cbc() and
EVP_rc2_64_cbc() respectively.
+Some old "export grade" clients may only
support weak encryption using 40 or 64
+bit RC2. These can be used by passing EVP_rc2_40_cbc()
and EVP_rc2_64_cbc()
+respectively.
-The algorithm passed in the B<cipher> parameter
must support ASN1 encoding of its
-parameters.
+The algorithm passed in the B<cipher> parameter
must support ASN1 encoding of
+its parameters.
-Many browsers implement a "sign and encrypt"
option which is simply an S/MIME
+Many browsers implement a "sign and encrypt"
option which is simply an S/MIME
envelopedData containing an S/MIME signed message. This
can be readily produced
by storing the S/MIME signed message in a memory BIO and
passing it to
PKCS7_encrypt().
The following flags can be passed in the B<flags>
parameter.
-If the B<PKCS7_TEXT> flag is set MIME headers for
type B<text/plain> are prepended
-to the data.
+If the B<PKCS7_TEXT> flag is set MIME headers for
type B<text/plain> are
+prepended to the data.
-Normally the supplied content is translated into MIME
canonical format (as required
-by the S/MIME specifications) if B<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. If B<PKCS7_BINARY> is set then
B<PKCS7_TEXT> is ignored.
+Normally the supplied content is translated into MIME
canonical format (as
+required by the S/MIME specifications) if
B<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. If
B<PKCS7_BINARY> is set then
+B<PKCS7_TEXT> is ignored.
+
+If the B<PKCS7_STREAM> flag is set a partial
B<PKCS7> structure is output
+suitable for streaming I/O: no data is read from the BIO
B<in>.
+
+=head1 NOTES
+
+If the flag B<PKCS7_STREAM> 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.
+
+Several functions including SMIME_write_PKCS7(),
d2i_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure.
Alternatively finalization
+can be performed by obtaining the streaming ASN1
B<BIO> directly using
+BIO_new_PKCS7().
=head1 RETURN VALUES
-PKCS7_encrypt() returns either a valid PKCS7 structure or
NULL if an error occurred.
+PKCS7_encrypt() returns either a PKCS7 structure or NULL
if an error occurred.
The error can be obtained from ERR_get_error(3).
-=head1 BUGS
-
-The lack of single pass processing and need to hold all
data in memory as
-mentioned in PKCS7_sign() also applies to
PKCS7_verify().
-
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>,
L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>
-63,5 +75,6
=head1 HISTORY
PKCS7_decrypt() was added to OpenSSL 0.9.5
+The B<PKCS7_STREAM> flag was first supported in
OpenSSL 0.9.9.
=cut
.
patch -p0 <<' .'
Index: openssl/doc/crypto/PKCS7_sign.pod
============================================================
================
$ cvs diff -u -r1.4 -r1.5 PKCS7_sign.pod
--- openssl/doc/crypto/PKCS7_sign.pod 14 May 2006 11:27:59
-0000 1.4
+++ openssl/doc/crypto/PKCS7_sign.pod 13 Apr 2007 12:57:48
-0000 1.5
-12,10 +12,10
=head1 DESCRIPTION
-PKCS7_sign() creates and returns a PKCS#7 signedData
structure. B<signcert>
-is the certificate to sign with, B<pkey> is the
corresponsding private key.
-B<certs> is an optional additional set of
certificates to include in the
-PKCS#7 structure (for example any intermediate CAs in the
chain).
+PKCS7_sign() creates and returns a PKCS#7 signedData
structure. B<signcert> is
+the certificate to sign with, B<pkey> is the
corresponsding private key.
+B<certs> is an optional additional set of
certificates to include in the PKCS#7
+structure (for example any intermediate CAs in the
chain).
The data to be signed is read from BIO B<data>.
-23,72 +23,83
=head1 NOTES
-Any of the following flags (ored together) can be passed
in the B<flags> parameter.
+Any of the following flags (ored together) can be passed
in the B<flags>
+parameter.
Many S/MIME clients expect the signed content to include
valid MIME headers. If
the B<PKCS7_TEXT> flag is set MIME headers for type
B<text/plain> are prepended
to the data.
If B<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 B<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.
-
-The data being signed is included in the PKCS7 structure,
unless B<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.
-
-Normally the supplied content is translated into MIME
canonical format (as required
-by the S/MIME specifications) if B<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.
-
-The signedData structure includes several PKCS#7
autenticatedAttributes including
-the signing time, the PKCS#7 content type and the
supported list of ciphers in
-an SMIMECapabilities attribute. If B<PKCS7_NOATTR>
is set then no authenticatedAttributes
-will be used. If B<PKCS7_NOSMIMECAP> is set then
just the SMIMECapabilities are
-omitted.
+PKCS7 structure, the signer's certificate must still be
supplied in the
+B<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.
+
+The data being signed is included in the PKCS7 structure,
unless
+B<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.
+
+Normally the supplied content is translated into MIME
canonical format (as
+required by the S/MIME specifications) if
B<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.
+
+The signedData structure includes several PKCS#7
autenticatedAttributes
+including the signing time, the PKCS#7 content type and
the supported list of
+ciphers in an SMIMECapabilities attribute. If
B<PKCS7_NOATTR> is set then no
+authenticatedAttributes 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.
+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.
+If the flags B<PKCS7_STREAM> 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.
-=head1 NOTES
+If the B<PKCS7_PARTIAL> flag is set a partial
B<PKCS7> structure is output to
+which additional signers and capabilities can be added
before finalization.
-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 NOTES
-=head1 BUGS
+If the flag B<PKCS7_STREAM> 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.
+
+Several functions including SMIME_write_PKCS7(),
d2i_PKCS7_bio_stream(),
+PEM_write_bio_PKCS7_stream() finalize the structure.
Alternatively finalization
+can be performed by obtaining the streaming ASN1
B<BIO> directly using
+BIO_new_PKCS7().
+
+If a signer is specified it will use the default digest
for the signing
+algorithm. This is B<SHA1> for both RSA and DSA
keys.
+
+In OpenSSL 0.9.9 the B<certs>, B<signcert>
and B<pkey> parameters can all be
+B<NULL> if the B<PKCS7_PARTIAL> flag is set.
One or more signers can be added
+using the function B<PKCS7_sign_add_signer()>.
B<PKCS7_final()> must also be
+called to finalize the structure if streaming is not
enabled. Alternative
+signing digests can also be specified using this method.
-PKCS7_sign() is somewhat limited. It does not support
multiple signers, some
-advanced attributes such as counter signatures are not
supported.
+In OpenSSL 0.9.9 if B<signcert> and B<pkey>
are NULL then a certificates only
+PKCS#7 structure is output.
-The SHA1 digest algorithm is currently always used.
+In versions of OpenSSL before 0.9.9 the B<signcert>
and B<pkey> parameters must
+B<NOT> be NULL.
-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 BUGS
+Some advanced attributes such as counter signatures are
not supported.
=head1 RETURN VALUES
-PKCS7_sign() returns either a valid PKCS7 structure or
NULL if an error occurred.
-The error can be obtained from ERR_get_error(3).
+PKCS7_sign() returns either a valid PKCS7 structure or
NULL if an error
+occurred. The error can be obtained from
ERR_get_error(3).
=head1 SEE ALSO
-98,6 +109,8
PKCS7_sign() was added to OpenSSL 0.9.5
-The B<PKCS7_PARTSIGN> flag was added in OpenSSL
0.9.8
+The B<PKCS7_PARTIAL> flag was added in OpenSSL
0.9.9
+
+The B<PKCS7_STREAM> flag was added in OpenSSL
0.9.9
=cut
.
____________________________________________________________
__________
OpenSSL Project http://www.openssl.org
CVS Repository Commit List
openssl-cvsopenssl.org
Automated List Manager
majordomoopenssl.org
|
