diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2008-04-10 11:55:57 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2008-04-10 11:55:57 +0000 |
commit | 287df2fe49f83b5bd6f0c324ba5232076d95916f (patch) | |
tree | 59b55739fdfb1546f9deb57e05e9e3d6d22a0851 | |
parent | e0fbd0730995c8594ddf7408695f3a77263b64cd (diff) |
Add docs for CMS_final() and BIO_new_CMS().
-rw-r--r-- | doc/crypto/BIO_new_CMS.pod | 64 | ||||
-rw-r--r-- | doc/crypto/CMS_final.pod | 41 |
2 files changed, 105 insertions, 0 deletions
diff --git a/doc/crypto/BIO_new_CMS.pod b/doc/crypto/BIO_new_CMS.pod new file mode 100644 index 0000000000..f73ab4c05a --- /dev/null +++ b/doc/crypto/BIO_new_CMS.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +BIO_new_CMS - CMS streaming filter BIO + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output +of the filter is written to B<out>. Any data written to the returned BIO +is automatically translated to a BER format CMS structure. + +=head1 NOTES + +The BIO returned by this functions behaves like a standard filter BIO. It +supports non blocking I/O. Content is processes and streamed on the fly and not +all held in memory at once: so it is possible to encode very large structures. +After all content has been written through the BIO BIO_flush() must be called +to finalise the structure. + +The B<CMS_STREAM> flag must be included in the corresponding B<flags> +parameter of the B<cms> creation function. + +After use BIOs should be removed from the filter using BIO_pop() until +the output BIO B<out> is reached. + +Any content written through the filter is uses "as-is" and no canonical +translation is performed. + +It is possible to chain multiple BIOs to for example create a triple wrapped +signed, enveloped signed structure. In this case it is the applications +responsibility to set the inner content type of any outer CMS_ContentInfo +structures. + +Large numbers of small writes through the chain should be avoided as this will +produce an output consisting of lots of OCTET STRING structures. Prepending +a BIO_f_buffer() buffering BIO will prevent this. + +=head1 BUGS + +There is currently no corresponding inverse BIO: i.e. one which can decode +a CMS structure on the fly. + +=head1 RETURN VALUES + +BIO_new_CMS() returns a BIO chain when successful 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_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +BIO_new_CMS() was added to OpenSSL 0.9.9 + +=cut diff --git a/doc/crypto/CMS_final.pod b/doc/crypto/CMS_final.pod new file mode 100644 index 0000000000..e4bcdfca81 --- /dev/null +++ b/doc/crypto/CMS_final.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +CMS_final - finalise a CMS_ContentInfo structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); + +=head1 DESCRIPTION + +CMS_final() finalises the structure B<cms>. It's purpose is to perform any +operations necessary on B<cms> (digest computation for example) and set the +appropriate fields. The parameter B<data> contains the content to be +processed. The B<dcont> parameter contains a BIO to write content to after +processing: this is only used with detached data and will usually be set to +NULL. + +=head1 NOTES + +This function will normally be called when the B<CMS_PARTIAL> flag is used. It +should only be used when streaming is not performed because the streaming +I/O functions perform finalisation operations internally. + +=head1 RETURN VALUES + +CMS_final() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, +L<CMS_encrypt(3)|CMS_encrypt(3)> + +=head1 HISTORY + +CMS_final() was added to OpenSSL 0.9.8 + +=cut |