From: Dr. Stephen Henson <steve@openssl.org>
Date: Wed, 9 Apr 2008 17:04:36 +0000 (+0000)
Subject: Add CMS_compress() docs.
X-Git-Tag: OpenSSL_0_9_8k^2~459
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=360bb61d860f9ce7e48b2bb85d3ef9f521f95ab9

Add CMS_compress() docs.
---

diff --git a/doc/crypto/CMS_compress.pod b/doc/crypto/CMS_compress.pod
new file mode 100644
index 0000000000..f2550b4947
--- /dev/null
+++ b/doc/crypto/CMS_compress.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+CMS_compress - create a CMS CompressedData structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/cms.h>
+
+ CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags);
+
+=head1 DESCRIPTION
+
+CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid>
+is the compression algorithm to use or B<NID_undef> to use the default
+algorithms (zlib compression). B<in> is the content to be compressed.
+B<flags> is an optional set of flags.
+
+=head1 NOTES
+
+The only currently supported compression algorithm is zlib using the NID
+NID_zlib_compression.
+
+If zlib support is not compiled into OpenSSL this CMS_compress() will return
+an error.
+
+If the B<CMS_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<CMS_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<CMS_BINARY> is set then
+B<CMS_TEXT> is ignored.
+
+If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is
+returned suitable for streaming I/O: no data is read from the BIO B<in>.
+
+The compressed data is included in the CMS_ContentInfo structure, unless
+B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
+practice and is not supported by SMIME_write_CMS().
+
+=head1 NOTES
+
+If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
+B<not> complete and outputting its contents via a function that does not
+properly finalize the B<CMS_ContentInfo> structure will give unpredictable
+results.
+
+Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
+PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
+can be performed by obtaining the streaming ASN1 B<BIO> directly using
+BIO_new_CMS().
+
+=head1 RETURN VALUES
+
+CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error
+occurred. The error can be obtained from ERR_get_error(3).
+
+=head1 SEE ALSO
+
+L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)>
+
+=head1 HISTORY
+
+CMS_compress() was added to OpenSSL 0.9.8
+The B<CMS_STREAM> flag was first supported in OpenSSL 0.9.9.
+
+=cut
diff --git a/doc/crypto/CMS_sign.pod b/doc/crypto/CMS_sign.pod
index 3047b283a4..46b1debde4 100644
--- a/doc/crypto/CMS_sign.pod
+++ b/doc/crypto/CMS_sign.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-CMS_sign - create a CMS signedData structure
+CMS_sign - create a CMS SignedData structure
 
 =head1 SYNOPSIS
 
@@ -12,7 +12,7 @@ CMS_sign - create a CMS signedData structure
 
 =head1 DESCRIPTION
 
-CMS_sign() creates and returns a CMS signedData structure. B<signcert> is
+CMS_sign() creates and returns a CMS 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 CMS
 structure (for example any intermediate CAs in the chain). Any or all of
@@ -47,7 +47,7 @@ required by the S/MIME specifications) if B<CMS_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 CMS signedAttributes including the
+The SignedData structure includes several CMS signedAttributes including the
 signing time, the CMS content type and the supported list of ciphers in an
 SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
 will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
diff --git a/doc/crypto/CMS_verify.pod b/doc/crypto/CMS_verify.pod
index 74c09e25fd..cfe3c326a0 100644
--- a/doc/crypto/CMS_verify.pod
+++ b/doc/crypto/CMS_verify.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-CMS_verify - verify a CMS signedData structure
+CMS_verify - verify a CMS SignedData structure
 
 =head1 SYNOPSIS
 
@@ -14,7 +14,7 @@ CMS_verify - verify a CMS signedData structure
 
 =head1 DESCRIPTION
 
-CMS_verify() verifies a CMS signedData structure. B<cms> is the CMS_ContentInfo
+CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
 structure to verify. B<certs> is a set of certificates in which to search for
 the signer's certificate. B<store> is a trusted certficate store (used for
 chain verification). B<indata> is the signed data if the content is not
@@ -32,7 +32,7 @@ be called after a succeful CMS_verify() operation.
 Normally the verify process proceeds as follows.
 
 Initially some sanity checks are performed on B<cms>. The type of B<cms> must
-be signedData. There must be at least one signature on the data and if
+be SignedData. There must be at least one signature on the data and if
 the content is detached B<indata> cannot be B<NULL>.
 
 An attempt is made to locate all the signer's certificates, first looking in