From 0241f6701aac0e95428b9f0899b07ba086aa7e71 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 11 Nov 2015 18:36:48 +0000 Subject: Convert and enable CMS manuals. Already some time ago, bcook@ said these can be installed. --- src/lib/libcrypto/man/CMS_add0_cert.3 | 127 +++++++++++ src/lib/libcrypto/man/CMS_add1_recipient_cert.3 | 115 ++++++++++ src/lib/libcrypto/man/CMS_add1_signer.3 | 161 +++++++++++++ src/lib/libcrypto/man/CMS_compress.3 | 110 +++++++++ src/lib/libcrypto/man/CMS_decrypt.3 | 127 +++++++++++ src/lib/libcrypto/man/CMS_encrypt.3 | 152 +++++++++++++ src/lib/libcrypto/man/CMS_final.3 | 48 ++++ src/lib/libcrypto/man/CMS_get0_RecipientInfos.3 | 251 +++++++++++++++++++++ src/lib/libcrypto/man/CMS_get0_SignerInfos.3 | 119 ++++++++++ src/lib/libcrypto/man/CMS_get0_type.3 | 95 ++++++++ src/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 | 143 ++++++++++++ src/lib/libcrypto/man/CMS_sign.3 | 199 ++++++++++++++++ src/lib/libcrypto/man/CMS_sign_receipt.3 | 61 +++++ src/lib/libcrypto/man/CMS_uncompress.3 | 70 ++++++ src/lib/libcrypto/man/CMS_verify.3 | 188 +++++++++++++++ src/lib/libcrypto/man/CMS_verify_receipt.3 | 55 +++++ src/lib/libcrypto/man/Makefile | 38 ++-- src/lib/libssl/src/doc/crypto/CMS_add0_cert.pod | 67 ------ .../src/doc/crypto/CMS_add1_recipient_cert.pod | 63 ------ src/lib/libssl/src/doc/crypto/CMS_compress.pod | 73 ------ src/lib/libssl/src/doc/crypto/CMS_decrypt.pod | 79 ------- src/lib/libssl/src/doc/crypto/CMS_encrypt.pod | 93 -------- src/lib/libssl/src/doc/crypto/CMS_final.pod | 41 ---- .../src/doc/crypto/CMS_get0_RecipientInfos.pod | 111 --------- .../libssl/src/doc/crypto/CMS_get0_SignerInfos.pod | 76 ------- src/lib/libssl/src/doc/crypto/CMS_get0_type.pod | 64 ------ .../src/doc/crypto/CMS_get1_ReceiptRequest.pod | 70 ------ src/lib/libssl/src/doc/crypto/CMS_sign.pod | 122 ---------- .../libssl/src/doc/crypto/CMS_sign_add1_signer.pod | 103 --------- src/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod | 45 ---- src/lib/libssl/src/doc/crypto/CMS_uncompress.pod | 54 ----- src/lib/libssl/src/doc/crypto/CMS_verify.pod | 126 ----------- .../libssl/src/doc/crypto/CMS_verify_receipt.pod | 47 ---- 33 files changed, 2040 insertions(+), 1253 deletions(-) create mode 100644 src/lib/libcrypto/man/CMS_add0_cert.3 create mode 100644 src/lib/libcrypto/man/CMS_add1_recipient_cert.3 create mode 100644 src/lib/libcrypto/man/CMS_add1_signer.3 create mode 100644 src/lib/libcrypto/man/CMS_compress.3 create mode 100644 src/lib/libcrypto/man/CMS_decrypt.3 create mode 100644 src/lib/libcrypto/man/CMS_encrypt.3 create mode 100644 src/lib/libcrypto/man/CMS_final.3 create mode 100644 src/lib/libcrypto/man/CMS_get0_RecipientInfos.3 create mode 100644 src/lib/libcrypto/man/CMS_get0_SignerInfos.3 create mode 100644 src/lib/libcrypto/man/CMS_get0_type.3 create mode 100644 src/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 create mode 100644 src/lib/libcrypto/man/CMS_sign.3 create mode 100644 src/lib/libcrypto/man/CMS_sign_receipt.3 create mode 100644 src/lib/libcrypto/man/CMS_uncompress.3 create mode 100644 src/lib/libcrypto/man/CMS_verify.3 create mode 100644 src/lib/libcrypto/man/CMS_verify_receipt.3 delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_add0_cert.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_compress.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_decrypt.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_encrypt.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_final.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_get0_type.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_sign.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_uncompress.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_verify.pod delete mode 100644 src/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/CMS_add0_cert.3 b/src/lib/libcrypto/man/CMS_add0_cert.3 new file mode 100644 index 0000000000..b02eb06673 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_add0_cert.3 @@ -0,0 +1,127 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_ADD0_CERT 3 +.Os +.Sh NAME +.Nm CMS_add0_cert , +.Nm CMS_add1_cert , +.Nm CMS_get1_certs , +.Nm CMS_add0_crl , +.Nm CMS_add1_crl , +.Nm CMS_get1_crls +.Nd CMS certificate and CRL utility functions +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_add0_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo CMS_add1_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *cert" +.Fc +.Ft STACK_OF(X509) * +.Fo CMS_get1_certs +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_add0_crl +.Fa "CMS_ContentInfo *cms" +.Fa "X509_CRL *crl" +.Fc +.Ft int +.Fo CMS_add1_crl +.Fa "CMS_ContentInfo *cms" +.Fa "X509_CRL *crl" +.Fc +.Ft STACK_OF(X509_CRL) * +.Fo CMS_get1_crls +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_add0_cert +and +.Fn CMS_add1_cert +add certificate +.Fa cert +to +.Fa cms . +.Fa cms +must be of type signed data or enveloped data. +.Pp +.Fn CMS_get1_certs +returns all certificates in +.Fa cms . +.Pp +.Fn CMS_add0_crl +and +.Fn CMS_add1_crl +add CRL +.Fa crl +to +.Fa cms . +.Fn CMS_get1_crls +returns any CRLs in +.Fa cms . +.Sh NOTES +The +.Vt CMS_ContentInfo +structure +.Fa cms +must be of type signed data or enveloped data or an error will be +returned. +.Pp +For signed data, certificates and CRLs are added to the +.Fa certificates +and +.Fa crls +fields of the SignedData structure. +For enveloped data, they are added to +.Fa OriginatorInfo . +.Pp +As the +.Sq 0 +implies, +.Fn CMS_add0_cert +adds +.Fa cert +internally to +.Fa cms +and it must not be freed up after the call, as opposed to +.Fn CMS_add1_cert +where +.Fa cert +must be freed up. +.Pp +The same certificate or CRL must not be added to the same cms structure +more than once. +.Sh RETURN VALUES +.Fn CMS_add0_cert , +.Fn CMS_add1_cert , +.Fn CMS_add0_crl , +and +.Fn CMS_add1_crl +return 1 for success and 0 for failure. +.Pp +.Fn CMS_get1_certs +and +.Fn CMS_get1_crls +return the STACK of certificates or CRLs or +.Dv NULL +if there are none or an error occurs. +The only error which will occur in practice is if the +.Fa cms +type is invalid. +.Sh SEE ALSO +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_add0_cert , +.Fn CMS_add1_cert , +.Fn CMS_get1_certs , +.Fn CMS_add0_crl +and +.Fn CMS_get1_crls +were all first added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_add1_recipient_cert.3 b/src/lib/libcrypto/man/CMS_add1_recipient_cert.3 new file mode 100644 index 0000000000..4e848446a6 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_add1_recipient_cert.3 @@ -0,0 +1,115 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_ADD1_RECIPIENT_CERT 3 +.Os +.Sh NAME +.Nm CMS_add1_recipient_cert , +.Nm CMS_add0_recipient_key +.Nd add recipients to a CMS enveloped data structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_RecipientInfo * +.Fo CMS_add1_recipient_cert +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *recip" +.Fa "unsigned int flags" +.Fc +.Ft CMS_RecipientInfo * +.Fo CMS_add0_recipient_key +.Fa "CMS_ContentInfo *cms" +.Fa "int nid" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fa "unsigned char *id" +.Fa "size_t idlen" +.Fa "ASN1_GENERALIZEDTIME *date" +.Fa "ASN1_OBJECT *otherTypeId" +.Fa "ASN1_TYPE *otherType" +.Fc +.Sh DESCRIPTION +.Fn CMS_add1_recipient_cert +adds recipient +.Fa recip +to the +.Vt CMS_ContentInfo +enveloped data structure +.Fa cms +as a KeyTransRecipientInfo structure. +.Pp +.Fn CMS_add0_recipient_key +adds the symmetric key +.Fa key +of length +.Fa keylen +using the wrapping algorithm +.Fa nid , +identifier +.Fa id +of length +.Fa idlen +and optional values +.Fa date , +.Fa otherTypeId , +and +.Fa otherType +to the +.Vt CMS_ContentInfo +enveloped data structure +.Fa cms +as a KEKRecipientInfo structure. +.Pp +The +.Vt CMS_ContentInfo +structure should be obtained from an initial call to +.Xr CMS_encrypt 3 +with the flag +.Dv CMS_PARTIAL +set. +.Sh NOTES +The main purpose of this function is to provide finer control over a CMS +enveloped data structure where the simpler +.Xr CMS_encrypt 3 +function defaults are not appropriate. +For example if one or more KEKRecipientInfo structures need to be added. +New attributes can also be added using the returned +.Vt CMS_RecipientInfo +structure and the CMS attribute utility functions. +.Pp +OpenSSL will by default identify recipient certificates using issuer +name and serial number. +If +.Dv CMS_USE_KEYID +is set, it will use the subject key identifier value instead. +An error occurs if all recipient certificates do not have a subject key +identifier extension. +.Pp +Currently only AES based key wrapping algorithms are supported for +.Fa nid , +specifically: +.Dv NID_id_aes128_wrap , +.Dv NID_id_aes192_wrap , +and +.Dv NID_id_aes256_wrap . +If +.Fa nid +is set to +.Dv NID_undef , +then an AES wrap algorithm will be used consistent with +.Fa keylen . +.Sh RETURN VALUES +.Fn CMS_add1_recipient_cert +and +.Fn CMS_add0_recipient_key +return an internal pointer to the +.Vt CMS_RecipientInfo +structure just added or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr CMS_decrypt 3 , +.Xr CMS_final 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_add1_recipient_cert +and +.Fn CMS_add0_recipient_key +were added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_add1_signer.3 b/src/lib/libcrypto/man/CMS_add1_signer.3 new file mode 100644 index 0000000000..403ec5b8e3 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_add1_signer.3 @@ -0,0 +1,161 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_SIGN_ADD1_SIGNER 3 +.Os +.Sh NAME +.Nm CMS_add1_signer , +.Nm CMS_SignerInfo_sign +.Nd add a signer to a CMS_ContentInfo signed data structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_SignerInfo * +.Fo CMS_add1_signer +.Fa "CMS_ContentInfo *cms" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fo CMS_SignerInfo_sign +.Fa "CMS_SignerInfo *si" +.Fc +.Sh DESCRIPTION +.Fn CMS_add1_signer +adds a signer with certificate +.Fa signcert +and private key +.Fa pkey +using message digest +.Fa md +to the +.Vt CMS_ContentInfo +SignedData structure +.Fa cms . +.Pp +The +.Vt CMS_ContentInfo +structure should be obtained from an initial call to +.Xr CMS_sign 3 +with the flag +.Dv CMS_PARTIAL +set or in the case or re-signing a valid +.Vt CMS_ContentInfo +SignedData structure. +.Pp +If the +.Fa md +parameter is +.Dv NULL , +then the default digest for the public key algorithm will be used. +.Pp +Unless the +.Dv CMS_REUSE_DIGEST +flag is set, the returned +.Vt CMS_ContentInfo +structure is not complete and must be finalized either by streaming +(if applicable) or a call to +.Xr CMS_final 3 . +.Pp +The +.Fn CMS_SignerInfo_sign +function will explicitly sign a +.Vt CMS_SignerInfo +structure, its main use is when +.Dv CMS_REUSE_DIGEST +and +.Dv CMS_PARTIAL +flags are both set. +.Sh NOTES +The main purpose of +.Fn CMS_add1_signer +is to provide finer control over a CMS signed data structure where the +simpler +.Xr CMS_sign 3 +function defaults are not appropriate. +For example if multiple signers or non default digest algorithms are +needed. +New attributes can also be added using the returned +.Vt CMS_SignerInfo +structure and the CMS attribute utility functions or the CMS signed +receipt request functions. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +If +.Dv CMS_REUSE_DIGEST +is set, then an attempt is made to copy the content digest value from the +.Dv CMS_ContentInfo +structure: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. +The returned +.Dv CMS_ContentInfo +structure will be valid and finalized when this flag is set. +.Pp +If +.Dv CMS_PARTIAL +is set in addition to +.Dv CMS_REUSE_DIGEST +then the +.Vt CMS_SignerInfo +structure will not be finalized so additional attributes can be added. +In this case an explicit call to +.Fn CMS_SignerInfo_sign +is needed to finalize it. +.Pp +If +.Dv CMS_NOCERTS +is set, the signer's certificate will not be included in the +.Vt CMS_ContentInfo +structure, the signer's certificate must still be supplied in the +.Fa 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. +.Pp +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 +.Dv CMS_NOATTR +is set, then no signedAttributes will be used. +If +.Dv CMS_NOSMIMECAP +is set, then just the SMIMECapabilities are omitted. +.Pp +OpenSSL will by default identify signing certificates using issuer name +and serial number. +If +.Dv CMS_USE_KEYID +is set, it will use the subject key identifier value instead. +An error occurs if the signing certificate does not have a subject key +identifier extension. +.Pp +If present, the SMIMECapabilities attribute indicates support for the +following algorithms in preference order: 256 bit AES, Gost R3411-94, +Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit +RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be +included: for example the GOST algorithms will not be included if +the GOST ENGINE is not loaded. +.Pp +.Fn CMS_add1_signer +returns an internal pointer to the +.Dv CMS_SignerInfo +structure just added. +This can be used to set additional attributes before it is finalized. +.Sh RETURN VALUES +.Fn CMS_add1_signer +returns an internal pointer to the +.Vt CMS_SignerInfo +structure just added or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr CMS_final 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_add1_signer +was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_compress.3 b/src/lib/libcrypto/man/CMS_compress.3 new file mode 100644 index 0000000000..1330464441 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_compress.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_COMPRESS 3 +.Os +.Sh NAME +.Nm CMS_compress +.Nd create a CMS CompressedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_compress +.Fa "BIO *in" +.Fa "int comp_nid" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_compress +creates and returns a CMS CompressedData structure. +.Fa comp_nid +is the compression algorithm to use or +.Dv NID_undef +to use the default algorithm (zlib compression). +.Fa in +is the content to be compressed. +.Fa flags +is an optional set of flags. +.Sh NOTES +The only currently supported compression algorithm is zlib using the NID +.Dv NID_zlib_compression . +.Pp +If zlib support is not compiled into OpenSSL then +.Fn CMS_compress +will return an error. +.Pp +If the +.Dv CMS_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications); if +.Dv 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 +.Dv CMS_BINARY +is set then +.Dv CMS_TEXT +is ignored. +.Pp +If the +.Dv CMS_STREAM +flag is set a partial +.Vt CMS_ContentInfo +structure is returned suitable for streaming I/O: no data is read from +the +.Vt BIO +.Fa in . +.Pp +The compressed data is included in the +.Vt CMS_ContentInfo +structure, unless +.Dv CMS_DETACHED +is set, in which case it is omitted. +This is rarely used in practice and is not supported by +.Xr SMIME_write_CMS 3 . +.Sh NOTES +If the flag +.Dv CMS_STREAM +is set, the returned +.Vt CMS_ContentInfo +structure is +.Em not +complete and outputting its contents via a function that does not +properly finalize the +.Vt CMS_ContentInfo +structure will give unpredictable results. +.Pp +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr PEM_write_bio_CMS_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +.Pp +Additional compression parameters such as the zlib compression level +cannot currently be set. +.Sh RETURN VALUES +.Fn CMS_compress +returns either a +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_uncompress 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_compress +was added to OpenSSL 0.9.8. +The +.Dv CMS_STREAM +flag was first supported in OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/CMS_decrypt.3 b/src/lib/libcrypto/man/CMS_decrypt.3 new file mode 100644 index 0000000000..3a34f10783 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_decrypt.3 @@ -0,0 +1,127 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_DECRYPT 3 +.Os +.Sh NAME +.Nm CMS_decrypt +.Nd decrypt content from a CMS envelopedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_decrypt +.Fa "CMS_ContentInfo *cms" +.Fa "EVP_PKEY *pkey" +.Fa "X509 *cert" +.Fa "BIO *dcont" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_decrypt +extracts and decrypts the content from a CMS EnvelopedData structure. +.Fa pkey +is the private key of the recipient, +.Fa cert +is the recipient's certificate, +.Fa out +is a +.Vt BIO +to write the content to and +.Fa flags +is an optional set of flags. +.Pp +The +.Fa dcont +parameter is used in the rare case where the encrypted content is +detached. +It will normally be set to +.Dv NULL . +.Sh NOTES +.Xr OpenSSL_add_all_algorithms 3 +(or equivalent) should be called before using this function or errors +about unknown algorithms will occur. +.Pp +Although the recipients certificate is not needed to decrypt the data it +is needed to locate the appropriate (of possible several) recipients in +the CMS structure. +.Pp +If +.Fa cert +is set to +.Dv NULL , +all possible recipients are tried. +This case however is problematic. +To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA +padding) all recipients are tried whether they succeed or not. +If no recipient succeeds then a random symmetric key is used to decrypt +the content: this will typically output garbage and may (but is not +guaranteed to) ultimately return a padding error only. +If +.Fn CMS_decrypt +just returned an error when all recipient encrypted keys failed to +decrypt an attacker could use this in a timing attack. +If the special flag +.Dv CMS_DEBUG_DECRYPT +is set then the above behaviour is modified and an error +.Em is +returned if no recipient encrypted key can be decrypted +.Em without +generating a random content encryption key. +Applications should use this flag with +.Sy extreme caution +especially in automated gateways as it can leave them open to attack. +.Pp +It is possible to determine the correct recipient key by other means +(for example looking them up in a database) and setting them in the CMS +structure in advance using the CMS utility functions such as +.Xr CMS_set1_pkey 3 . +In this case both +.Fa cert +and +.Fa pkey +should be set to +.Dv NULL . +.Pp +To process KEKRecipientInfo types +.Xr CMS_set1_key 3 +or +.Xr CMS_RecipientInfo_set0_key 3 +and +.Xr CMS_ReceipientInfo_decrypt 3 +should be called before +.Fn CMS_decrypt +and +.Fa cert +and +.Fa pkey +set to +.Dv NULL . +.Pp +The following flags can be passed in the +.Fa flags +parameter: +.Pp +If the +.Dv CMS_TEXT +flag is set MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain +then an error is returned. +.Sh RETURN VALUES +.Fn CMS_decrypt +returns either 1 for success or 0 for failure. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh BUGS +The lack of single pass processing and the need to hold all data in +memory as mentioned in +.Xr CMS_verify 3 +also applies to +.Fn CMS_decrypt . +.Sh SEE ALSO +.Xr CMS_encrypt 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_decrypt +was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_encrypt.3 b/src/lib/libcrypto/man/CMS_encrypt.3 new file mode 100644 index 0000000000..5d7b0bf470 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_encrypt.3 @@ -0,0 +1,152 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_ENCRYPT 3 +.Os +.Sh NAME +.Nm CMS_encrypt +.Nd create a CMS envelopedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_encrypt +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *in" +.Fa "const EVP_CIPHER *cipher" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_encrypt +creates and returns a CMS EnvelopedData structure. +.Fa certs +is a list of recipient certificates. +.Fa in +is the content to be encrypted. +.Fa cipher +is the symmetric cipher to use. +.Fa flags +is an optional set of flags. +.Sh NOTES +Only certificates carrying RSA keys are supported 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. +.Pp +The algorithm passed in the +.Fa cipher +parameter must support ASN1 encoding of its parameters. +.Pp +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 +.Fn CMS_encrypt . +.Pp +The following flags can be passed in the +.Fa flags +parameter: +.Pp +If the +.Dv CMS_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications); if +.Dv 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 +.Dv CMS_BINARY +is set then +.Dv CMS_TEXT +is ignored. +.Pp +OpenSSL will by default identify recipient certificates using issuer +name and serial number. +If +.Dv CMS_USE_KEYID +is set, it will use the subject key identifier value instead. +An error occurs if all recipient certificates do not have a subject key +identifier extension. +.Pp +If the +.Dv CMS_STREAM +flag is set, a partial +.Vt CMS_ContentInfo +structure is returned suitable for streaming I/O: no data is read from the +.Vt BIO +.Fa in . +.Pp +If the +.Dv CMS_PARTIAL +flag is set, a partial +.Vt CMS_ContentInfo +structure is returned to which additional recipients and attributes can +be added before finalization. +.Pp +The data being encrypted is included in the +.Vt CMS_ContentInfo +structure, unless +.Dv CMS_DETACHED +is set, in which case it is omitted. +This is rarely used in practice and is not supported by +.Xr SMIME_write_CMS 3 . +.Pp +If the flag +.Dv CMS_STREAM +is set, the returned +.Vt CMS_ContentInfo +structure is +.Em not +complete and outputting its contents via a function that does not +properly finalize the +.Vt CMS_ContentInfo +structure will give unpredictable results. +.Pp +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr PEM_write_bio_CMS_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +.Pp +The recipients specified in +.Fa certs +use a CMS KeyTransRecipientInfo info structure. +KEKRecipientInfo is also supported using the flag +.Dv CMS_PARTIAL +and +.Xr CMS_add0_recipient_key 3 . +.Pp +The parameter +.Fa certs +may be +.Dv NULL +if +.Dv CMS_PARTIAL +is set and recipients are added later using +.Xr CMS_add1_recipient_cert 3 +or +.Xr CMS_add0_recipient_key 3 . +.Sh RETURN VALUES +.Fn CMS_encrypt +returns either a +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_decrypt 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_encrypt +was added to OpenSSL 0.9.8. +The +.Dv CMS_STREAM +flag was first supported in OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/CMS_final.3 b/src/lib/libcrypto/man/CMS_final.3 new file mode 100644 index 0000000000..4e7912a4e0 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_final.3 @@ -0,0 +1,48 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_FINAL 3 +.Os +.Sh NAME +.Nm CMS_final +.Nd finalise a CMS_ContentInfo structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_final +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *data" +.Fa "BIO *dcont" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_final +finalises the structure +.Fa cms . +Its purpose is to perform any operations necessary on +.Fa cms +(digest computation for example) and set the appropriate fields. +The parameter +.Fa data +contains the content to be processed. +The +.Fa dcont +parameter contains a +.Vt BIO +to write content to after processing: this is +only used with detached data and will usually be set to +.Dv NULL . +.Sh NOTES +This function will normally be called when the +.Dv 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. +.Sh RETURN VALUES +.Fn CMS_final +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr CMS_encrypt 3 , +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_final +was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_get0_RecipientInfos.3 b/src/lib/libcrypto/man/CMS_get0_RecipientInfos.3 new file mode 100644 index 0000000000..4db69b57b8 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_get0_RecipientInfos.3 @@ -0,0 +1,251 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_GET0_RECIPIENTINFOS 3 +.Os +.Sh NAME +.Nm CMS_get0_RecipientInfos , +.Nm CMS_RecipientInfo_type , +.Nm CMS_RecipientInfo_ktri_get0_signer_id , +.Nm CMS_RecipientInfo_ktri_cert_cmp , +.Nm CMS_RecipientInfo_set0_pkey , +.Nm CMS_RecipientInfo_kekri_get0_id , +.Nm CMS_RecipientInfo_kekri_id_cmp , +.Nm CMS_RecipientInfo_set0_key , +.Nm CMS_RecipientInfo_decrypt , +.Nm CMS_RecipientInfo_encrypt +.Nd CMS envelopedData RecipientInfo routines +.Sh SYNOPSIS +.In openssl/cms.h +.Ft STACK_OF(CMS_RecipientInfo) * +.Fo CMS_get0_RecipientInfos +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_RecipientInfo_type +.Fa "CMS_RecipientInfo *ri" +.Fc +.Ft int +.Fo CMS_RecipientInfo_ktri_get0_signer_id +.Fa "CMS_RecipientInfo *ri" +.Fa "ASN1_OCTET_STRING **keyid" +.Fa "X509_NAME **issuer" +.Fa "ASN1_INTEGER **sno" +.Fc +.Ft int +.Fo CMS_RecipientInfo_ktri_cert_cmp +.Fa "CMS_RecipientInfo *ri" +.Fa "X509 *cert" +.Fc +.Ft int +.Fo CMS_RecipientInfo_set0_pkey +.Fa "CMS_RecipientInfo *ri" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo CMS_RecipientInfo_kekri_get0_id +.Fa "CMS_RecipientInfo *ri" +.Fa "X509_ALGOR **palg" +.Fa "ASN1_OCTET_STRING **pid" +.Fa "ASN1_GENERALIZEDTIME **pdate" +.Fa "ASN1_OBJECT **potherid" +.Fa "ASN1_TYPE **pothertype" +.Fc +.Ft int +.Fo CMS_RecipientInfo_kekri_id_cmp +.Fa "CMS_RecipientInfo *ri" +.Fa "const unsigned char *id" +.Fa "size_t idlen" +.Fc +.Ft int +.Fo CMS_RecipientInfo_set0_key +.Fa "CMS_RecipientInfo *ri" +.Fa "unsigned char *key" +.Fa "size_t keylen" +.Fc +.Ft int +.Fo CMS_RecipientInfo_decrypt +.Fa "CMS_ContentInfo *cms" +.Fa "CMS_RecipientInfo *ri" +.Fc +.Sh DESCRIPTION +The function +.Fn CMS_get0_RecipientInfos +returns all the +.Vt CMS_RecipientInfo +structures associated with a CMS EnvelopedData structure. +.Pp +.Fn CMS_RecipientInfo_type +returns the type of the +.Vt CMS_RecipientInfo +structure +.Fa ri . +It will currently return +.Dv CMS_RECIPINFO_TRANS , +.Dv CMS_RECIPINFO_AGREE , +.Dv CMS_RECIPINFO_KEK , +.Dv CMS_RECIPINFO_PASS , +or +.Dv CMS_RECIPINFO_OTHER . +.Pp +.Fn CMS_RecipientInfo_ktri_get0_signer_id +retrieves the certificate recipient identifier associated with a +specific +.Vt CMS_RecipientInfo +structure +.Fa ri , +which must be of type +.Dv CMS_RECIPINFO_TRANS . +Either the keyidentifier will be set in +.Fa keyid +or +.Em both +issuer name and serial number in +.Fa issuer +and +.Fa sno . +.Pp +.Fn CMS_RecipientInfo_ktri_cert_cmp +compares the certificate +.Fa cert +against the +.Vt CMS_RecipientInfo +structure +.Fa ri , +which must be of type +.Dv CMS_RECIPINFO_TRANS . +It returns zero if the +comparison is successful and non zero if not. +.Pp +.Fn CMS_RecipientInfo_set0_pkey +associates the private key +.Fa pkey +with the +.Vt CMS_RecipientInfo +structure +.Fa ri , +which must be of type +.Dv CMS_RECIPINFO_TRANS . +.Pp +.Fn CMS_RecipientInfo_kekri_get0_id +retrieves the key information from the +.Vt CMS_RecipientInfo +structure +.Fa ri +which must be of type +.Dv CMS_RECIPINFO_KEK . +Any of the remaining parameters can be +.Dv NULL +if the application is not interested in the value of a field. +Where a field is optional and absent, +.Dv NULL +will be written to the corresponding parameter. +The +.Sy keyEncryptionAlgorithm +field is written to +.Fa palg , +the +.Sy keyIdentifier +field is written to +.Fa pid , +the +.Sy date +field if present is written to +.Fa pdate , +if the +.Sy other +field is present the components +.Sy keyAttrId +and +.Sy keyAttr +are written to the parameters +.Fa potherid +and +.Fa pothertype . +.Pp +.Fn CMS_RecipientInfo_kekri_id_cmp +compares the ID in the +.Fa id +and +.Fa idlen +parameters against the +.Sy keyIdentifier +.Vt CMS_RecipientInfo +structure +.Fa ri , +which must be of type +.Dv CMS_RECIPINFO_KEK . +It returns zero if the comparison is successful and non zero if not. +.Pp +.Fn CMS_RecipientInfo_set0_key +associates the symmetric key +.Fa key +of length +.Fa keylen +with the +.Vt CMS_RecipientInfo +structure +.Fa ri , +which must be of type +.Dv CMS_RECIPINFO_KEK . +.Pp +.Fn CMS_RecipientInfo_decrypt +attempts to decrypt the +.Vt CMS_RecipientInfo +structure +.Fa ri +in structure +.Fa cms . +A key must have been associated with the structure first. +.Sh NOTES +The main purpose of these functions is to enable an application to +lookup recipient keys using any appropriate technique when the simpler +method of +.Xr CMS_decrypt 3 +is not appropriate. +.Pp +In typical usage, an application will retrieve all +.Vt CMS_RecipientInfo +structures using +.Fn CMS_get0_RecipientInfos +and check the type of each using +.Fn CMS_RecipientInfo_type . +Depending on the type, the +.Vt CMS_RecipientInfo +structure can be ignored or its key identifier data retrieved using +an appropriate function. +Then if the corresponding secret or private key can be obtained by any +appropriate means it can then associated with the structure and +.Xr CMS_RecpientInfo_decrypt 3 +called. +If successful, +.Xr CMS_decrypt 3 +can be called with a +.Dv NULL +key to decrypt the enveloped content. +.Sh RETURN VALUES +.Fn CMS_get0_RecipientInfos +returns all +.Vt CMS_RecipientInfo +structures, or +.Dv NULL +if an error occurs. +.Pp +.Fn CMS_RecipientInfo_ktri_get0_signer_id , +.Fn CMS_RecipientInfo_set0_pkey , +.Fn CMS_RecipientInfo_kekri_get0_id , +.Fn CMS_RecipientInfo_set0_key , +and +.Fn CMS_RecipientInfo_decrypt +return 1 for success or 0 if an error occurs. +.Pp +.Fn CMS_RecipientInfo_ktri_cert_cmp +and +.Fn CMS_RecipientInfo_kekri_id_cmp +return 0 for a successful comparison and non zero otherwise. +.Pp +Any error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_decrypt 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +These functions were first was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_get0_SignerInfos.3 b/src/lib/libcrypto/man/CMS_get0_SignerInfos.3 new file mode 100644 index 0000000000..99aab48193 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_get0_SignerInfos.3 @@ -0,0 +1,119 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_GET0_SIGNERINFOS 3 +.Os +.Sh NAME +.Nm CMS_get0_SignerInfos , +.Nm CMS_SignerInfo_get0_signer_id , +.Nm CMS_SignerInfo_cert_cmp , +.Nm CMS_set1_signer_certs +.Nd CMS signedData signer functions +.Sh SYNOPSIS +.In openssl/cms.h +.Ft STACK_OF(CMS_SignerInfo) * +.Fo CMS_get0_SignerInfos +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_SignerInfo_get0_signer_id +.Fa "CMS_SignerInfo *si" +.Fa "ASN1_OCTET_STRING **keyid" +.Fa "X509_NAME **issuer" +.Fa "ASN1_INTEGER **sno" +.Fc +.Ft int +.Fo CMS_SignerInfo_cert_cmp +.Fa "CMS_SignerInfo *si" +.Fa "X509 *cert" +.Fc +.Ft void +.Fo CMS_SignerInfo_set1_signer_cert +.Fa "CMS_SignerInfo *si" +.Fa "X509 *signer" +.Fc +.Sh DESCRIPTION +The function +.Fn CMS_get0_SignerInfos +returns all the +.Vt CMS_SignerInfo +structures associated with a CMS signedData structure. +.Pp +.Fn CMS_SignerInfo_get0_signer_id +retrieves the certificate signer identifier associated with a specific +.Vt CMS_SignerInfo +structure +.Fa si . +Either the keyidentifier will be set in +.Fa keyid +or +.Em both +issuer name and serial number in +.Fa issuer +and +.Fa sno . +.Pp +.Fn CMS_SignerInfo_cert_cmp +compares the certificate +.Fa cert +against the signer identifier +.Fa si . +It returns zero if the comparison is successful and non zero if not. +.Pp +.Fn CMS_SignerInfo_set1_signer_cert +sets the signers certificate of +.Fa si +to +.Fa signer . +.Sh NOTES +The main purpose of these functions is to enable an application to +lookup signers certificates using any appropriate technique when the +simpler method of +.Xr CMS_verify 3 +is not appropriate. +.Pp +In typical usage and application will retrieve all +.Vt CMS_SignerInfo +structures using +.Fn CMS_get0_SignerInfo +and retrieve the identifier information using CMS. +It will then obtain the signer certificate by some unspecified means +(or return and error if it cannot be found) and set it using +.Fn CMS_SignerInfo_set1_signer_cert . +.Pp +Once all signer certificates have been set, +.Xr CMS_verify 3 +can be used. +.Pp +Although +.Fn CMS_get0_SignerInfos +can return +.Dv NULL +if an error occur +.Em or +if there are no signers, this is not a problem in practice because the +only error which can occur is if the +.Fa cms +structure is not of type signedData due to application error. +.Sh RETURN VALUES +.Fn CMS_get0_SignerInfos +returns all +.Vt CMS_SignerInfo +structures, or +.Dv NULL +if there are no signers or an error occurs. +.Pp +.Fn CMS_SignerInfo_get0_signer_id +returns 1 for success and 0 for failure. +.Pp +.Fn CMS_SignerInfo_cert_cmp +returns 0 for a successful comparison and non zero otherwise. +.Pp +.Fn CMS_SignerInfo_set1_signer_cert +does not return a value. +.Pp +Any error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_verify 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +These functions were first was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_get0_type.3 b/src/lib/libcrypto/man/CMS_get0_type.3 new file mode 100644 index 0000000000..e77dd655e6 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_get0_type.3 @@ -0,0 +1,95 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_GET0_TYPE 3 +.Os +.Sh NAME +.Nm CMS_get0_type , +.Nm CMS_set1_eContentType , +.Nm CMS_get0_eContentType +.Nd get and set CMS content types +.Sh SYNOPSIS +.In openssl/cms.h +.Ft const ASN1_OBJECT * +.Fo CMS_get0_type +.Fa "CMS_ContentInfo *cms" +.Fc +.Ft int +.Fo CMS_set1_eContentType +.Fa "CMS_ContentInfo *cms" +.Fa "const ASN1_OBJECT *oid" +.Fc +.Ft const ASN1_OBJECT * +.Fo CMS_get0_eContentType +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_get0_type +returns the content type of a +.Vt CMS_ContentInfo +structure as an +.Vt ASN1_OBJECT +pointer. +An application can then decide how to process the +.Vt CMS_ContentInfo +structure based on this value. +.Pp +.Fn CMS_set1_eContentType +sets the embedded content type of a +.Vt CMS_ContentInfo +structure. +It should be called with CMS functions with the +.Dv CMS_PARTIAL +flag and +.Em before +the structure is finalised, otherwise the results are undefined. +.Pp +.Fn CMS_get0_eContentType +returns a pointer to the embedded content type. +.Sh NOTES +As the +.Sq 0 +implies, +.Fn CMS_get0_type +and +.Fn CMS_get0_eContentType +return internal pointers which should +.Em not +be freed up. +.Fn CMS_set1_eContentType +copies the supplied OID and it +.Em should +be freed up after use. +.Pp +The +.Vt ASN1_OBJECT +values returned can be converted to an integer NID value using +.Xr OBJ_obj2nid 3 . +For the currently supported content types the following values are +returned: +.Bd -unfilled -offset indent +.Dv NID_pkcs7_data +.Dv NID_pkcs7_signed +.Dv NID_pkcs7_digest +.Dv NID_id_smime_ct_compressedData +.Dv NID_pkcs7_encrypted +.Dv NID_pkcs7_enveloped +.Ed +.Sh RETURN VALUES +.Fn CMS_get0_type +and +.Fn CMS_get0_eContentType +return an +.Vt ASN1_OBJECT +structure. +.Pp +.Fn CMS_set1_eContentType +returns 1 for success or 0 if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_get0_type , +.Fn CMS_set1_eContentType , +and +.Fn CMS_get0_eContentType +were all first added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 b/src/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 new file mode 100644 index 0000000000..ab19f87fab --- /dev/null +++ b/src/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 @@ -0,0 +1,143 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_GET1_RECEIPTREQUEST 3 +.Os +.Sh NAME +.Nm CMS_ReceiptRequest_create0 , +.Nm CMS_add1_ReceiptRequest , +.Nm CMS_get1_ReceiptRequest , +.Nm CMS_ReceiptRequest_get0_values +.Nd CMS signed receipt request functions +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_ReceiptRequest * +.Fo CMS_ReceiptRequest_create0 +.Fa "unsigned char *id" +.Fa "int idlen" +.Fa "int allorfirst" +.Fa "STACK_OF(GENERAL_NAMES) *receiptList" +.Fa "STACK_OF(GENERAL_NAMES) *receiptsTo" +.Fc +.Ft int +.Fo CMS_add1_ReceiptRequest +.Fa "CMS_SignerInfo *si" +.Fa "CMS_ReceiptRequest *rr" +.Fc +.Ft int +.Fo CMS_get1_ReceiptRequest +.Fa "CMS_SignerInfo *si" +.Fa "CMS_ReceiptRequest **prr" +.Fc +.Ft void +.Fo CMS_ReceiptRequest_get0_values +.Fa "CMS_ReceiptRequest *rr" +.Fa "ASN1_STRING **pcid" +.Fa "int *pallorfirst" +.Fa "STACK_OF(GENERAL_NAMES) **plist" +.Fa "STACK_OF(GENERAL_NAMES) **prto" +.Fc +.Sh DESCRIPTION +.Fn CMS_ReceiptRequest_create0 +creates a signed receipt request structure. +The +.Sy signedContentIdentifier +field is set using +.Fa id +and +.Fa idlen , +or it is set to 32 bytes of pseudo random data if +.Fa id +is +.Dv NULL . +If +.Fa receiptList +is +.Dv NULL , +the +.Sy allOrFirstTier +option in +.Sy receiptsFrom +is used and set to the value of the +.Fa allorfirst +parameter. +If +.Fa receiptList +is not +.Dv NULL , +the +.Sy receiptList +option in +.Sy receiptsFrom +is used. +The +.Fa receiptsTo +parameter specifies the +.Sy receiptsTo +field value. +.Pp +The +.Fn CMS_add1_ReceiptRequest +function adds a signed receipt request +.Fa rr +to the +.Vt CMS_SignerInfo +structure +.Fa si . +.Pp +.Fn CMS_get1_ReceiptRequest +looks for a signed receipt request in +.Fa si . +If any is found, it is decoded and written to +.Fa prr . +.Pp +.Fn CMS_ReceiptRequest_get0_values +retrieves the values of a receipt request. +The signedContentIdentifier is copied to +.Fa pcid . +If the +.Sy allOrFirstTier +option of +.Sy receiptsFrom +is used, its value is copied to +.Fa pallorfirst ; +otherwise the +.Sy receiptList +field is copied to +.Fa plist . +The +.Sy receiptsTo +parameter is copied to +.Fa prto . +.Sh NOTES +For more details of the meaning of the fields see RFC2634. +.Pp +The contents of a signed receipt should only be considered meaningful if +the corresponding +.Vt CMS_ContentInfo +structure can be successfully verified using +.Xr CMS_verify 3 . +.Sh RETURN VALUES +.Fn CMS_ReceiptRequest_create0 +returns a signed receipt request structure or +.Dv NULL +if an error occurred. +.Pp +.Fn CMS_add1_ReceiptRequest +returns 1 for success or 0 is an error occurred. +.Pp +.Fn CMS_get1_ReceiptRequest +returns 1 is a signed receipt request is found and decoded. +It returns 0 if a signed receipt request is not present and -1 if it is +present but malformed. +.Sh SEE ALSO +.Xr CMS_sign 3 , +.Xr CMS_sign_receipt 3 , +.Xr CMS_verify 3 , +.Xr CMS_verify_receipt 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_ReceiptRequest_create0 , +.Fn CMS_add1_ReceiptRequest , +.Fn CMS_get1_ReceiptRequest , +and +.Fn CMS_ReceiptRequest_get0_values +were added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_sign.3 b/src/lib/libcrypto/man/CMS_sign.3 new file mode 100644 index 0000000000..af75a20d6b --- /dev/null +++ b/src/lib/libcrypto/man/CMS_sign.3 @@ -0,0 +1,199 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_SIGN 3 +.Os +.Sh NAME +.Nm CMS_sign +.Nd create a CMS SignedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_sign +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *data" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_sign +creates and returns a CMS SignedData structure. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa 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 these parameters can be +.Dv NULL , +see +.Sx NOTES +below. +.Pp +The data to be signed is read from +.Fa data . +.Pp +.Fa flags +is an optional set of flags. +.Sh NOTES +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +Many S/MIME clients expect the signed content to include valid MIME +headers. +If the +.Dv CMS_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +If +.Dv CMS_NOCERTS +is set, the signer's certificate will not be included in the +.Vt CMS_ContentInfo +structure, the signer's certificate must still be supplied in the +.Fa 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. +.Pp +The data being signed is included in the +.Vt CMS_ContentInfo +structure, unless +.Dv CMS_DETACHED +is set, in which case it is omitted. +This is used for +.Vt CMS_ContentInfo +detached signatures which are used in S/MIME plaintext signed +messages for example. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications); if +.Dv 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. +.Pp +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 +.Dv CMS_NOATTR +is set, then no signedAttributes will be used. +If +.Dv CMS_NOSMIMECAP +is set, then just the SMIMECapabilities are omitted. +.Pp +If present, the SMIMECapabilities attribute indicates support for the +following algorithms in preference order: 256 bit AES, Gost R3411-94, +Gost 28147-89, 192 bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit +RC2, DES and 40 bit RC2. +If any of these algorithms is not available, then it will not be +included: for example the GOST algorithms will not be included if +the GOST ENGINE is not loaded. +.Pp +OpenSSL will by default identify signing certificates using issuer name +and serial number. +If +.Dv CMS_USE_KEYID +is set, it will use the subject key identifier value instead. +An error occurs if the signing certificate does not have a subject key +identifier extension. +.Pp +If the flag +.Dv CMS_STREAM +is set, then the returned +.Vt CMS_ContentInfo +structure is just initialized ready to perform the signing operation. +The signing is however +.Em not +performed and the data to be signed is not read from the +.Fa data +parameter. +Signing is deferred until after the data has been written. +In this way, data can be signed in a single pass. +.Pp +If the +.Dv CMS_PARTIAL +flag is set, a partial +.Vt CMS_ContentInfo +structure is output to which additional signers and capabilities can be +added before finalization. +.Pp +If the flag +.Dv CMS_STREAM +is set, the returned +.Vt CMS_ContentInfo +structure is +.Em not +complete and outputting its contents via a function that does not +properly finalize the +.Vt CMS_ContentInfo +structure will give unpredictable results. +.Pp +Several functions including +.Xr SMIME_write_CMS 3 , +.Xr i2d_CMS_bio_stream 3 , +.Xr PEM_write_bio_CMS_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_CMS 3 . +.Pp +If a signer is specified, it will use the default digest for the signing +algorithm. +This is SHA1 for both RSA and DSA keys. +.Pp +If +.Fa signcert +and +.Fa pkey +are +.Dv NULL , +then a certificates only CMS structure is output. +.Pp +The function +.Fn CMS_sign +is a basic CMS signing function whose output will be suitable for many +purposes. +For finer control of the output format the +.Fa certs , +.Fa signcert +and +.Fa pkey +parameters can all be +.Dv NULL +and the +.Dv CMS_PARTIAL +flag set. +Then one or more signers can be added using the function +.Xr CMS_sign_add1_signer 3 , +non default digests can be used and custom attributes added. +.Xr CMS_final 3 +must then be called to finalize the structure if streaming is not +enabled. +.Sh RETURN VALUES +.Fn CMS_sign +returns either a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_verify 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_sign +was added to OpenSSL 0.9.8. +.Pp +The +.Dv CMS_STREAM +flag is only supported for detached data in OpenSSL 0.9.8. +It is supported for embedded data in OpenSSL 1.0.0 and later. +.Sh BUGS +Some attributes such as counter signatures are not supported. diff --git a/src/lib/libcrypto/man/CMS_sign_receipt.3 b/src/lib/libcrypto/man/CMS_sign_receipt.3 new file mode 100644 index 0000000000..de7a8c0e10 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_sign_receipt.3 @@ -0,0 +1,61 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_SIGN_RECEIPT 3 +.Os +.Sh NAME +.Nm CMS_sign_receipt +.Nd create a CMS signed receipt +.Sh SYNOPSIS +.In openssl/cms.h +.Ft CMS_ContentInfo * +.Fo CMS_sign_receipt +.Fa "CMS_SignerInfo *si" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_sign_receipt +creates and returns a CMS signed receipt structure. +.Fa si +is the +.Vt CMS_SignerInfo +structure containing the signed receipt request. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa certs +is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). +.Pp +.Fa flags +is an optional set of flags. +.Sh NOTES +This functions behaves in a similar way to +.Xr CMS_sign 3 +except the flag values +.Dv CMS_DETACHED , +.Dv CMS_BINARY , +.Dv CMS_NOATTR , +.Dv CMS_TEXT , +and +.Dv CMS_STREAM +are not supported, since they do not make sense in the context of +signed receipts. +.Sh RETURN VALUES +.Fn CMS_sign_receipt +returns either a valid +.Vt CMS_ContentInfo +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_sign 3 , +.Xr CMS_verify_receipt 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_sign_receipt +was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/CMS_uncompress.3 b/src/lib/libcrypto/man/CMS_uncompress.3 new file mode 100644 index 0000000000..c651f24de2 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_uncompress.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_UNCOMPRESS 3 +.Os +.Sh NAME +.Nm CMS_uncompress +.Nd uncompress a CMS CompressedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_uncompress +.Fa "CMS_ContentInfo *cms" +.Fa "BIO *dcont" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_uncompress +extracts and uncompresses the content from a CMS CompressedData +structure +.Fa cms . +.Fa data +is a +.Vt BIO +to write the content to and +.Fa flags +is an optional set of flags. +.Pp +The +.Fa dcont +parameter is used in the rare case where the compressed content is +detached. +It will normally be set to +.Dv NULL . +.Sh NOTES +The only currently supported compression algorithm is zlib: if the +structure indicates the use of any other algorithm, an error is returned. +.Pp +If zlib support is not compiled into OpenSSL, then +.Fn CMS_uncompress +will always return an error. +.Pp +The following flags can be passed in the +.Fa flags +parameter: +.Pp +If the +.Dv CMS_TEXT +flag is set, MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain , +then an error is returned. +.Sh RETURN VALUES +.Fn CMS_uncompress +returns either 1 for success or 0 for failure. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_compress 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_uncompress +was added to OpenSSL 0.9.8. +.Sh BUGS +The lack of single pass processing and the need to hold all data in +memory as mentioned in +.Xr CMS_verify 3 +also applies to +.Xr CMS_decompress 3 . diff --git a/src/lib/libcrypto/man/CMS_verify.3 b/src/lib/libcrypto/man/CMS_verify.3 new file mode 100644 index 0000000000..0ab1baf6b3 --- /dev/null +++ b/src/lib/libcrypto/man/CMS_verify.3 @@ -0,0 +1,188 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_VERIFY 3 +.Os +.Sh NAME +.Nm CMS_verify , +.Nm CMS_get0_signers +.Nd verify a CMS SignedData structure +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_verify +.Fa "CMS_ContentInfo *cms" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "BIO *indata" +.Fa "BIO *out" +.Fa "unsigned int flags" +.Fc +.Ft STACK_OF(X509) * +.Fo CMS_get0_signers +.Fa "CMS_ContentInfo *cms" +.Fc +.Sh DESCRIPTION +.Fn CMS_verify +verifies a CMS SignedData structure. +.Fa cms +is the +.Vt CMS_ContentInfo +structure to verify. +.Fa certs +is a set of certificates in which to search for the signing +certificate(s). +.Fa store +is a trusted certificate store used for chain verification. +.Fa indata +is the detached content if the content is not present in +.Fa cms . +The content is written to +.Fa out +if it is not +.Dv NULL . +.Pp +.Fa flags +is an optional set of flags, which can be used to modify the verify +operation. +.Pp +.Fn CMS_get0_signers +retrieves the signing certificate(s) from +.Fa cms , +it must be called after a successful +.Fn CMS_verify +operation. +.Sh VERIFY PROCESS +Normally the verify process proceeds as follows. +.Pp +Initially some sanity checks are performed on +.Fa cms . +The type of +.Fa cms +must be SignedData. +There must be at least one signature on the data and if the content is +detached +.Fa indata +cannot be +.Dv NULL . +.Pp +An attempt is made to locate all the signing certificate(s), first +looking in the +.Fa certs +parameter (if it is not +.Dv NULL ) +and then looking in any certificates contained in the +.Fa cms +structure itself. +If no signing certificate can be located, the operation fails. +.Pp +Each signing certificate is chain verified using the +.Sy smimesign +purpose and the supplied trusted certificate store. +Any internal certificates in the message are used as untrusted CAs. +If CRL checking is enabled in +.Fa store , +any internal CRLs are used in addition to attempting to look them up in +.Fa store . +If any chain verify fails, an error code is returned. +.Pp +Finally the signed content is read (and written to +.Fa out +is it is not +.Dv NULL ) +and the signature is checked. +.Pp +If all signatures verify correctly, then the function is successful. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter to change the default verify behaviour. +.Pp +If +.Dv CMS_NOINTERN +is set, the certificates in the message itself are not searched when +locating the signing certificate(s). +This means that all the signing certificates must be in the +.Fa certs +parameter. +.Pp +If +.Dv CMS_NOCRL +is set, and CRL checking is enabled in +.Fa store , +then any CRLs in the message itself are ignored. +.Pp +If the +.Dv CMS_TEXT +flag is set, MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain , +then an error is returned. +.Pp +If +.Dv CMS_NO_SIGNER_CERT_VERIFY +is set, the signing certificates are not verified. +.Pp +If +.Dv CMS_NO_ATTR_VERIFY +is set, the signed attributes signature is not verified. +.Pp +If +.Dv CMS_NO_CONTENT_VERIFY +is set, then the content digest is not checked. +.Sh NOTES +One application of +.Dv CMS_NOINTERN +is to only accept messages signed by a small number of certificates. +The acceptable certificates would be passed in the +.Fa certs +parameter. +In this case, if the signer is not one of the certificates supplied in +.Fa certs , +then the verify will fail because the signer cannot be found. +.Pp +In some cases the standard techniques for looking up and validating +certificates are not appropriate: for example an application may wish to +lookup certificates in a database or perform customised verification. +This can be achieved by setting and verifying the signers certificates +manually using the signed data utility functions. +.Pp +Care should be taken when modifying the default verify behaviour, for +example setting +.Dv CMS_NO_CONTENT_VERIFY +will totally disable all content verification and any modified content +will be considered valid. +This combination is however useful if one merely wishes to write the +content to +.Fa out +and its validity is not considered important. +.Pp +Chain verification should arguably be performed using the signing time +rather than the current time. +However since the signing time is supplied by the signer it cannot be +trusted without additional evidence (such as a trusted timestamp). +.Sh RETURN VALUES +.Fn CMS_verify +returns 1 for a successful verification and zero if an error occurred. +.Pp +.Fn CMS_get0_signers +returns all signers or +.Dv NULL +if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_sign 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_verify +was added to OpenSSL 0.9.8. +.Sh BUGS +The trusted certificate store is not searched for the signing +certificate, this is primarily due to the inadequacies of the current +.Vt X509_STORE +functionality. +.Pp +The lack of single pass processing means that the signed content must +all be held in memory if it is not detached. diff --git a/src/lib/libcrypto/man/CMS_verify_receipt.3 b/src/lib/libcrypto/man/CMS_verify_receipt.3 new file mode 100644 index 0000000000..0977f267bc --- /dev/null +++ b/src/lib/libcrypto/man/CMS_verify_receipt.3 @@ -0,0 +1,55 @@ +.Dd $Mdocdate: November 11 2015 $ +.Dt CMS_VERIFY_RECEIPT 3 +.Os +.Sh NAME +.Nm CMS_verify_receipt +.Nd verify a CMS signed receipt +.Sh SYNOPSIS +.In openssl/cms.h +.Ft int +.Fo CMS_verify_receipt +.Fa "CMS_ContentInfo *rcms" +.Fa "CMS_ContentInfo *ocms" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn CMS_verify_receipt +verifies a CMS signed receipt. +.Fa rcms +is the signed receipt to verify. +.Fa ocms +is the original SignedData structure containing the receipt request. +.Fa certs +is a set of certificates in which to search for the signing certificate. +.Fa store +is a trusted certificate store (used for chain verification). +.Pp +.Fa flags +is an optional set of flags, which can be used to modify the verify +operation. +.Sh NOTES +This functions behaves in a similar way to +.Xr CMS_verify 3 +except the flag values +.Dv CMS_DETACHED , +.Dv CMS_BINARY , +.Dv CMS_TEXT , +and +.Dv CMS_STREAM +are not supported since they do not make sense in the context of signed +receipts. +.Sh RETURN VALUES +.Fn CMS_verify_receipt +returns 1 for a successful verification and zero if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CMS_sign_receipt 3 , +.Xr CMS_verify 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn CMS_verify_receipt +was added to OpenSSL 0.9.8. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index d896f436bc..2c5ffbb8e4 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.25 2015/10/14 07:41:28 reyk Exp $ +# $OpenBSD: Makefile,v 1.26 2015/11/11 18:36:48 schwarze Exp $ .include # for NOMAN @@ -21,6 +21,7 @@ MAN= \ BIO_f_null.3 \ BIO_find_type.3 \ BIO_new.3 \ + BIO_new_CMS.3 \ BIO_push.3 \ BIO_read.3 \ BIO_s_accept.3 \ @@ -52,6 +53,22 @@ MAN= \ BN_swap.3 \ BN_zero.3 \ BUF_MEM_new.3 \ + CMS_add0_cert.3 \ + CMS_add1_recipient_cert.3 \ + CMS_add1_signer.3 \ + CMS_compress.3 \ + CMS_decrypt.3 \ + CMS_encrypt.3 \ + CMS_final.3 \ + CMS_get0_RecipientInfos.3 \ + CMS_get0_SignerInfos.3 \ + CMS_get0_type.3 \ + CMS_get1_ReceiptRequest.3 \ + CMS_sign.3 \ + CMS_sign_receipt.3 \ + CMS_uncompress.3 \ + CMS_verify.3 \ + CMS_verify_receipt.3 \ EVP_AEAD_CTX_init.3 \ GENMAN= \ @@ -200,24 +217,7 @@ GENMAN= \ MAN+= ${GENMAN} -#MAN+= BIO_new_CMS.3 \ -# CMS_add0_cert.3 \ -# CMS_add1_recipient_cert.3 \ -# CMS_compress.3 \ -# CMS_decrypt.3 \ -# CMS_encrypt.3 \ -# CMS_final.3 \ -# CMS_get0_RecipientInfos.3 \ -# CMS_get0_SignerInfos.3 \ -# CMS_get0_type.3 \ -# CMS_get1_ReceiptRequest.3 \ -# CMS_sign.3 \ -# CMS_sign_add1_signer.3 \ -# CMS_sign_receipt.3 \ -# CMS_uncompress.3 \ -# CMS_verify.3 \ -# CMS_verify_receipt.3 \ -# PEM_write_bio_CMS_stream.3 \ +#MAM+= PEM_write_bio_CMS_stream.3 \ # SMIME_read_CMS.3 \ # SMIME_write_CMS.3 \ # i2d_CMS_bio_stream.3 \ diff --git a/src/lib/libssl/src/doc/crypto/CMS_add0_cert.pod b/src/lib/libssl/src/doc/crypto/CMS_add0_cert.pod deleted file mode 100644 index b289237ec2..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_add0_cert.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, -CMS_get1_crls - CMS certificate and CRL utility functions - -=head1 SYNOPSIS - - #include - - int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); - int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); - STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); - - int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); - int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); - STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); - - -=head1 DESCRIPTION - -CMS_add0_cert() and CMS_add1_cert() add certificate B to B. -must be of type signed data or enveloped data. - -CMS_get1_certs() returns all certificates in B. - -CMS_add0_crl() and CMS_add1_crl() add CRL B to B. CMS_get1_crls() -returns any CRLs in B. - -=head1 NOTES - -The CMS_ContentInfo structure B must be of type signed data or enveloped -data or an error will be returned. - -For signed data certificates and CRLs are added to the B and -B fields of SignedData structure. For enveloped data they are added to -B. - -As the B<0> implies CMS_add0_cert() adds B internally to B and it -must not be freed up after the call as opposed to CMS_add1_cert() where B -must be freed up. - -The same certificate or CRL must not be added to the same cms structure more -than once. - -=head1 RETURN VALUES - -CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return -1 for success and 0 for failure. - -CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs -or NULL if there are none or an error occurs. The only error which will occur -in practice is if the B type is invalid. - -=head1 SEE ALSO - -L, -L, -L - -=head1 HISTORY - -CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl() -and CMS_get1_crls() were all first added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod b/src/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod deleted file mode 100644 index 8a39391aa4..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS -enveloped data structure - -=head1 SYNOPSIS - - #include - - CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags); - - CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType); - -=head1 DESCRIPTION - -CMS_add1_recipient_cert() adds recipient B to CMS_ContentInfo enveloped -data structure B as a KeyTransRecipientInfo structure. - -CMS_add0_recipient_key() adds symmetric key B of length B using -wrapping algorithm B, identifier B of length B and optional -values B, B and B to CMS_ContentInfo enveloped -data structure B as a KEKRecipientInfo structure. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_encrypt() with the flag B set. - -=head1 NOTES - -The main purpose of this function is to provide finer control over a CMS -enveloped data structure where the simpler CMS_encrypt() function defaults are -not appropriate. For example if one or more KEKRecipientInfo structures -need to be added. New attributes can also be added using the returned -CMS_RecipientInfo structure and the CMS attribute utility functions. - -OpenSSL will by default identify recipient certificates using issuer name -and serial number. If B is set it will use the subject key -identifier value instead. An error occurs if all recipient certificates do not -have a subject key identifier extension. - -Currently only AES based key wrapping algorithms are supported for B, -specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. -If B is set to B then an AES wrap algorithm will be used -consistent with B. - -=head1 RETURN VALUES - -CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal -pointer to the CMS_RecipientInfo structure just added or NULL if an error -occurs. - -=head1 SEE ALSO - -L, L, -L, - -=head1 HISTORY - -CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL -0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_compress.pod b/src/lib/libssl/src/doc/crypto/CMS_compress.pod deleted file mode 100644 index 0a0715271d..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_compress.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -CMS_compress - create a CMS CompressedData structure - -=head1 SYNOPSIS - - #include - - CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); - -=head1 DESCRIPTION - -CMS_compress() creates and returns a CMS CompressedData structure. B -is the compression algorithm to use or B to use the default -algorithm (zlib compression). B is the content to be compressed. -B 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 then CMS_compress() will return -an error. - -If the B flag is set MIME headers for type B are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B 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 is set then -B is ignored. - -If the B flag is set a partial B structure is -returned suitable for streaming I/O: no data is read from the BIO B. - -The compressed data is included in the CMS_ContentInfo structure, unless -B 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 is set the returned B structure is -B complete and outputting its contents via a function that does not -properly finalize the B 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 directly using -BIO_new_CMS(). - -Additional compression parameters such as the zlib compression level cannot -currently be set. - -=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, L - -=head1 HISTORY - -CMS_compress() was added to OpenSSL 0.9.8 -The B flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_decrypt.pod b/src/lib/libssl/src/doc/crypto/CMS_decrypt.pod deleted file mode 100644 index 3b44cec603..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_decrypt.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -CMS_decrypt - decrypt content from a CMS envelopedData structure - -=head1 SYNOPSIS - - #include - - int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); - -=head1 DESCRIPTION - -CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData -structure. B is the private key of the recipient, B is the -recipient's certificate, B is a BIO to write the content to and -B is an optional set of flags. - -The B parameter is used in the rare case where the encrypted content -is detached. It will normally be set to NULL. - -=head1 NOTES - -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - -Although the recipients certificate is not needed to decrypt the data it is -needed to locate the appropriate (of possible several) recipients in the CMS -structure. - -If B is set to NULL all possible recipients are tried. This case however -is problematic. To thwart the MMA attack (Bleichenbacher's attack on -PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or -not. If no recipient succeeds then a random symmetric key is used to decrypt -the content: this will typically output garbage and may (but is not guaranteed -to) ultimately return a padding error only. If CMS_decrypt() just returned an -error when all recipient encrypted keys failed to decrypt an attacker could -use this in a timing attack. If the special flag B is set -then the above behaviour is modified and an error B returned if no -recipient encrypted key can be decrypted B generating a random -content encryption key. Applications should use this flag with -B especially in automated gateways as it can leave them -open to attack. - -It is possible to determine the correct recipient key by other means (for -example looking them up in a database) and setting them in the CMS structure -in advance using the CMS utility functions such as CMS_set1_pkey(). In this -case both B and B should be set to NULL. - -To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() -and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and -B and B set to NULL. - -The following flags can be passed in the B parameter. - -If the B flag is set MIME headers for type B are deleted -from the content. If the content is not of type B then an error is -returned. - -=head1 RETURN VALUES - -CMS_decrypt() returns either 1 for success or 0 for failure. -The error can be obtained from ERR_get_error(3) - -=head1 BUGS - -The lack of single pass processing and the need to hold all data in memory as -mentioned in CMS_verify() also applies to CMS_decrypt(). - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_encrypt.pod b/src/lib/libssl/src/doc/crypto/CMS_encrypt.pod deleted file mode 100644 index f697e87e2b..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_encrypt.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -CMS_encrypt - create a CMS envelopedData structure - -=head1 SYNOPSIS - - #include - - CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); - -=head1 DESCRIPTION - -CMS_encrypt() creates and returns a CMS EnvelopedData structure. B -is a list of recipient certificates. B is the content to be encrypted. -B is the symmetric cipher to use. B is an optional set of flags. - -=head1 NOTES - -Only certificates carrying RSA keys are supported 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. - -The algorithm passed in the B parameter must support ASN1 encoding of -its parameters. - -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 -CMS_encrypt(). - -The following flags can be passed in the B parameter. - -If the B flag is set MIME headers for type B are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B 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 is set then -B is ignored. - -OpenSSL will by default identify recipient certificates using issuer name -and serial number. If B is set it will use the subject key -identifier value instead. An error occurs if all recipient certificates do not -have a subject key identifier extension. - -If the B flag is set a partial B structure is -returned suitable for streaming I/O: no data is read from the BIO B. - -If the B flag is set a partial B structure is -returned to which additional recipients and attributes can be added before -finalization. - -The data being encrypted is included in the CMS_ContentInfo structure, unless -B 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 is set the returned B structure is -B complete and outputting its contents via a function that does not -properly finalize the B 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 directly using -BIO_new_CMS(). - -The recipients specified in B use a CMS KeyTransRecipientInfo info -structure. KEKRecipientInfo is also supported using the flag B -and CMS_add0_recipient_key(). - -The parameter B may be NULL if B is set and recipients -added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). - -=head1 RETURN VALUES - -CMS_encrypt() 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, L - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 -The B flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_final.pod b/src/lib/libssl/src/doc/crypto/CMS_final.pod deleted file mode 100644 index c5f1722aaf..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_final.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -CMS_final - finalise a CMS_ContentInfo structure - -=head1 SYNOPSIS - - #include - - int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); - -=head1 DESCRIPTION - -CMS_final() finalises the structure B. It's purpose is to perform any -operations necessary on B (digest computation for example) and set the -appropriate fields. The parameter B contains the content to be -processed. The B 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 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, L, -L - -=head1 HISTORY - -CMS_final() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod b/src/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod deleted file mode 100644 index da3914c0c0..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod +++ /dev/null @@ -1,111 +0,0 @@ -=pod - -=head1 NAME - -CMS_get0_RecipientInfos, CMS_RecipientInfo_type, -CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, -CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, -CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, -CMS_RecipientInfo_decrypt, -CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines - -=head1 SYNOPSIS - - #include - - STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); - int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); - - int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); - int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); - int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); - - int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype); - int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen); - int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen); - - int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); - -=head1 DESCRIPTION - -The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo -structures associated with a CMS EnvelopedData structure. - -CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B. -It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, -CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. - -CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient -identifier associated with a specific CMS_RecipientInfo structure B, which -must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in -B or B issuer name and serial number in B and B. - -CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B against the -CMS_RecipientInfo structure B, which must be of type CMS_RECIPINFO_TRANS. -It returns zero if the comparison is successful and non zero if not. - -CMS_RecipientInfo_set0_pkey() associates the private key B with -the CMS_RecipientInfo structure B, which must be of type -CMS_RECIPINFO_TRANS. - -CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the -CMS_RecipientInfo structure B which must be of type CMS_RECIPINFO_KEK. Any -of the remaining parameters can be NULL if the application is not interested in -the value of a field. Where a field is optional and absent NULL will be written -to the corresponding parameter. The keyEncryptionAlgorithm field is written to -B, the B field is written to B, the B field if -present is written to B, if the B field is present the components -B and B are written to parameters B and -B. - -CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B and B -parameters against the B CMS_RecipientInfo structure B, -which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is -successful and non zero if not. - -CMS_RecipientInfo_set0_key() associates the symmetric key B of length -B with the CMS_RecipientInfo structure B, which must be of type -CMS_RECIPINFO_KEK. - -CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure -B in structure B. A key must have been associated with the structure -first. - -=head1 NOTES - -The main purpose of these functions is to enable an application to lookup -recipient keys using any appropriate technique when the simpler method -of CMS_decrypt() is not appropriate. - -In typical usage and application will retrieve all CMS_RecipientInfo structures -using CMS_get0_RecipientInfos() and check the type of each using -CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure -can be ignored or its key identifier data retrieved using an appropriate -function. Then if the corresponding secret or private key can be obtained by -any appropriate means it can then associated with the structure and -CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called -with a NULL key to decrypt the enveloped content. - -=head1 RETURN VALUES - -CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if -an error occurs. - -CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), -CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and -CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. - -CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 -for a successful comparison and non zero otherwise. - -Any error can be obtained from L. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod b/src/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod deleted file mode 100644 index 557cda6c3e..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, -CMS_set1_signer_certs - CMS signedData signer functions. - -=head1 SYNOPSIS - - #include - - STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); - - int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); - int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); - void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); - -=head1 DESCRIPTION - -The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures -associated with a CMS signedData structure. - -CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier -associated with a specific CMS_SignerInfo structure B. Either the -keyidentifier will be set in B or B issuer name and serial number -in B and B. - -CMS_SignerInfo_cert_cmp() compares the certificate B against the signer -identifier B. It returns zero if the comparison is successful and non zero -if not. - -CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B to -B. - -=head1 NOTES - -The main purpose of these functions is to enable an application to lookup -signers certificates using any appropriate technique when the simpler method -of CMS_verify() is not appropriate. - -In typical usage and application will retrieve all CMS_SignerInfo structures -using CMS_get0_SignerInfo() and retrieve the identifier information using -CMS. It will then obtain the signer certificate by some unspecified means -(or return and error if it cannot be found) and set it using -CMS_SignerInfo_set1_signer_cert(). - -Once all signer certificates have been set CMS_verify() can be used. - -Although CMS_get0_SignerInfos() can return NULL is an error occur B if -there are no signers this is not a problem in practice because the only -error which can occur is if the B structure is not of type signedData -due to application error. - -=head1 RETURN VALUES - -CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there -are no signers or an error occurs. - -CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure. - -CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non -zero otherwise. - -CMS_SignerInfo_set1_signer_cert() does not return a value. - -Any error can be obtained from L - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_get0_type.pod b/src/lib/libssl/src/doc/crypto/CMS_get0_type.pod deleted file mode 100644 index bc2690ee1a..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_get0_type.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS -content types - -=head1 SYNOPSIS - - #include - - const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms); - int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); - const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); - -=head1 DESCRIPTION - -CMS_get0_type() returns the content type of a CMS_ContentInfo structure as -and ASN1_OBJECT pointer. An application can then decide how to process the -CMS_ContentInfo structure based on this value. - -CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo -structure. It should be called with CMS functions with the B -flag and B the structure is finalised, otherwise the results are -undefined. - -ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded -content type. - -=head1 NOTES - -As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal -pointers which should B be freed up. CMS_set1_eContentType() copies the -supplied OID and it B be freed up after use. - -The B values returned can be converted to an integer B value -using OBJ_obj2nid(). For the currently supported content types the following -values are returned: - - NID_pkcs7_data - NID_pkcs7_signed - NID_pkcs7_digest - NID_id_smime_ct_compressedData: - NID_pkcs7_encrypted - NID_pkcs7_enveloped - - -=head1 RETURN VALUES - -CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure. - -CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The -error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L - -=head1 HISTORY - -CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all -first added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod b/src/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod deleted file mode 100644 index a7babb1a6e..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, -CMS_ReceiptRequest_get0_values - CMS signed receipt request functions. - -=head1 SYNOPSIS - - #include - - CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); - int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); - int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); - void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); - -=head1 DESCRIPTION - -CMS_ReceiptRequest_create0() creates a signed receipt request structure. The -B field is set using B and B, or it is set -to 32 bytes of pseudo random data if B is NULL. If B is NULL -the allOrFirstTier option in B is used and set to the value of -the B parameter. If B is not NULL the B -option in B is used. The B parameter specifies the -B field value. - -The CMS_add1_ReceiptRequest() function adds a signed receipt request B -to SignerInfo structure B. - -int CMS_get1_ReceiptRequest() looks for a signed receipt request in B, if -any is found it is decoded and written to B. - -CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. -The signedContentIdentifier is copied to B. If the B -option of B is used its value is copied to B -otherwise the B field is copied to B. The B -parameter is copied to B. - -=head1 NOTES - -For more details of the meaning of the fields see RFC2634. - -The contents of a signed receipt should only be considered meaningful if the -corresponding CMS_ContentInfo structure can be successfully verified using -CMS_verify(). - -=head1 RETURN VALUES - -CMS_ReceiptRequest_create0() returns a signed receipt request structure or -NULL if an error occurred. - -CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. - -CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and -decoded. It returns 0 if a signed receipt request is not present and -1 if -it is present but malformed. - -=head1 SEE ALSO - -L, L, -L, L -L - -=head1 HISTORY - -CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), -CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to -OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_sign.pod b/src/lib/libssl/src/doc/crypto/CMS_sign.pod deleted file mode 100644 index cc6d17faf6..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_sign.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -CMS_sign - create a CMS SignedData structure - -=head1 SYNOPSIS - - #include - - CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags); - -=head1 DESCRIPTION - -CMS_sign() creates and returns a CMS SignedData structure. B is -the certificate to sign with, B is the corresponding private key. -B 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 -these parameters can be B, see B below. - -The data to be signed is read from BIO B. - -B is an optional set of flags. - -=head1 NOTES - -Any of the following flags (ored together) can be passed in the B -parameter. - -Many S/MIME clients expect the signed content to include valid MIME headers. If -the B flag is set MIME headers for type B are prepended -to the data. - -If B is set the signer's certificate will not be included in the -CMS_ContentInfo structure, the signer's certificate must still be supplied in -the B 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 CMS_ContentInfo structure, unless -B is set in which case it is omitted. This is used for -CMS_ContentInfo 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 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 -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B is set then no signedAttributes -will be used. If B is set then just the SMIMECapabilities are -omitted. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 -bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. -If any of these algorithms is not available then it will not be included: for -example the GOST algorithms will not be included if the GOST ENGINE is not -loaded. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B is set it will use the subject key -identifier value instead. An error occurs if the signing certificate does not -have a subject key identifier extension. - -If the flags B is set then the returned B -structure is just initialized ready to perform the signing operation. The -signing is however B performed and the data to be signed is not read from -the B parameter. Signing is deferred until after the data has been -written. In this way data can be signed in a single pass. - -If the B flag is set a partial B structure is -output to which additional signers and capabilities can be added before -finalization. - -If the flag B is set the returned B structure is -B complete and outputting its contents via a function that does not -properly finalize the B 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 directly using -BIO_new_CMS(). - -If a signer is specified it will use the default digest for the signing -algorithm. This is B for both RSA and DSA keys. - -If B and B are NULL then a certificates only CMS structure is -output. - -The function CMS_sign() is a basic CMS signing function whose output will be -suitable for many purposes. For finer control of the output format the -B, B and B parameters can all be B and the -B flag set. Then one or more signers can be added using the -function CMS_sign_add1_signer(), non default digests can be used and custom -attributes added. B must then be called to finalize the -structure if streaming is not enabled. - -=head1 BUGS - -Some attributes such as counter signatures are not supported. - -=head1 RETURN VALUES - -CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error -occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -CMS_sign() was added to OpenSSL 0.9.8 - -The B flag is only supported for detached data in OpenSSL 0.9.8, -it is supported for embedded data in OpenSSL 1.0.0 and later. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod b/src/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod deleted file mode 100644 index ed4d9a9234..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo -signed data structure. - -=head1 SYNOPSIS - - #include - - CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); - - int CMS_SignerInfo_sign(CMS_SignerInfo *si); - - -=head1 DESCRIPTION - -CMS_sign_add1_signer() adds a signer with certificate B and private -key B using message digest B to CMS_ContentInfo SignedData -structure B. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_sign() with the flag B set or in the case or re-signing a -valid CMS_ContentInfo SignedData structure. - -If the B parameter is B then the default digest for the public -key algorithm will be used. - -Unless the B flag is set the returned CMS_ContentInfo -structure is not complete and must be finalized either by streaming (if -applicable) or a call to CMS_final(). - -The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo -structure, its main use is when B and B flags -are both set. - -=head1 NOTES - -The main purpose of CMS_sign_add1_signer() is to provide finer control -over a CMS signed data structure where the simpler CMS_sign() function defaults -are not appropriate. For example if multiple signers or non default digest -algorithms are needed. New attributes can also be added using the returned -CMS_SignerInfo structure and the CMS attribute utility functions or the -CMS signed receipt request functions. - -Any of the following flags (ored together) can be passed in the B -parameter. - -If B is set then an attempt is made to copy the content -digest value from the CMS_ContentInfo structure: to add a signer to an existing -structure. An error occurs if a matching digest value cannot be found to copy. -The returned CMS_ContentInfo structure will be valid and finalized when this -flag is set. - -If B is set in addition to B then the -CMS_SignerInfo structure will not be finalized so additional attributes -can be added. In this case an explicit call to CMS_SignerInfo_sign() is -needed to finalize it. - -If B is set the signer's certificate will not be included in the -CMS_ContentInfo structure, the signer's certificate must still be supplied in -the B 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 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 is set then no signedAttributes -will be used. If B is set then just the SMIMECapabilities are -omitted. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B is set it will use the subject key -identifier value instead. An error occurs if the signing certificate does not -have a subject key identifier extension. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 -bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. -If any of these algorithms is not available then it will not be included: for -example the GOST algorithms will not be included if the GOST ENGINE is not -loaded. - -CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo -structure just added, this can be used to set additional attributes -before it is finalized. - -=head1 RETURN VALUES - -CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo -structure just added or NULL if an error occurs. - -=head1 SEE ALSO - -L, L, -L, - -=head1 HISTORY - -CMS_sign_add1_signer() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod b/src/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod deleted file mode 100644 index f603ab66f0..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -CMS_sign_receipt - create a CMS signed receipt - -=head1 SYNOPSIS - - #include - - CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags); - -=head1 DESCRIPTION - -CMS_sign_receipt() creates and returns a CMS signed receipt structure. B is -the B structure containing the signed receipt request. -B is the certificate to sign with, B is the corresponding -private key. B is an optional additional set of certificates to include -in the CMS structure (for example any intermediate CAs in the chain). - -B is an optional set of flags. - -=head1 NOTES - -This functions behaves in a similar way to CMS_sign() except the flag values -B, B, B, B and B -are not supported since they do not make sense in the context of signed -receipts. - -=head1 RETURN VALUES - -CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if -an error occurred. The error can be obtained from ERR_get_error(3). - -=head1 SEE ALSO - -L, -L, -L - -=head1 HISTORY - -CMS_sign_receipt() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_uncompress.pod b/src/lib/libssl/src/doc/crypto/CMS_uncompress.pod deleted file mode 100644 index fcbfec128a..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_uncompress.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -CMS_uncompress - uncompress a CMS CompressedData structure - -=head1 SYNOPSIS - - #include - - int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); - -=head1 DESCRIPTION - -CMS_uncompress() extracts and uncompresses the content from a CMS -CompressedData structure B. B is a BIO to write the content to and -B is an optional set of flags. - -The B parameter is used in the rare case where the compressed content -is detached. It will normally be set to NULL. - -=head1 NOTES - -The only currently supported compression algorithm is zlib: if the structure -indicates the use of any other algorithm an error is returned. - -If zlib support is not compiled into OpenSSL then CMS_uncompress() will always -return an error. - -The following flags can be passed in the B parameter. - -If the B flag is set MIME headers for type B are deleted -from the content. If the content is not of type B then an error is -returned. - -=head1 RETURN VALUES - -CMS_uncompress() returns either 1 for success or 0 for failure. The error can -be obtained from ERR_get_error(3) - -=head1 BUGS - -The lack of single pass processing and the need to hold all data in memory as -mentioned in CMS_verify() also applies to CMS_decompress(). - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -CMS_uncompress() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_verify.pod b/src/lib/libssl/src/doc/crypto/CMS_verify.pod deleted file mode 100644 index 69425008aa..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_verify.pod +++ /dev/null @@ -1,126 +0,0 @@ -=pod - -=head1 NAME - -CMS_verify, CMS_get0_signers - verify a CMS SignedData structure - -=head1 SYNOPSIS - - #include - - int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); - - STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); - -=head1 DESCRIPTION - -CMS_verify() verifies a CMS SignedData structure. B is the CMS_ContentInfo -structure to verify. B is a set of certificates in which to search for -the signing certificate(s). B is a trusted certificate store used for -chain verification. B is the detached content if the content is not -present in B. The content is written to B if it is not NULL. - -B is an optional set of flags, which can be used to modify the verify -operation. - -CMS_get0_signers() retrieves the signing certificate(s) from B, it must -be called after a successful CMS_verify() operation. - -=head1 VERIFY PROCESS - -Normally the verify process proceeds as follows. - -Initially some sanity checks are performed on B. The type of B must -be SignedData. There must be at least one signature on the data and if -the content is detached B cannot be B. - -An attempt is made to locate all the signing certificate(s), first looking in -the B parameter (if it is not NULL) and then looking in any -certificates contained in the B structure itself. If any signing -certificate cannot be located the operation fails. - -Each signing certificate is chain verified using the B purpose and -the supplied trusted certificate store. Any internal certificates in the message -are used as untrusted CAs. If CRL checking is enabled in B any internal -CRLs are used in addition to attempting to look them up in B. If any -chain verify fails an error code is returned. - -Finally the signed content is read (and written to B is it is not NULL) -and the signature's checked. - -If all signature's verify correctly then the function is successful. - -Any of the following flags (ored together) can be passed in the B -parameter to change the default verify behaviour. - -If B is set the certificates in the message itself are not -searched when locating the signing certificate(s). This means that all the -signing certificates must be in the B parameter. - -If B is set and CRL checking is enabled in B then any -CRLs in the message itself are ignored. - -If the B flag is set MIME headers for type B are deleted -from the content. If the content is not of type B then an error is -returned. - -If B is set the signing certificates are not -verified. - -If B is set the signed attributes signature is not -verified. - -If B is set then the content digest is not checked. - -=head1 NOTES - -One application of B is to only accept messages signed by -a small number of certificates. The acceptable certificates would be passed -in the B parameter. In this case if the signer is not one of the -certificates supplied in B then the verify will fail because the -signer cannot be found. - -In some cases the standard techniques for looking up and validating -certificates are not appropriate: for example an application may wish to -lookup certificates in a database or perform customised verification. This -can be achieved by setting and verifying the signers certificates manually -using the signed data utility functions. - -Care should be taken when modifying the default verify behaviour, for example -setting B will totally disable all content verification -and any modified content will be considered valid. This combination is however -useful if one merely wishes to write the content to B and its validity -is not considered important. - -Chain verification should arguably be performed using the signing time rather -than the current time. However since the signing time is supplied by the -signer it cannot be trusted without additional evidence (such as a trusted -timestamp). - -=head1 RETURN VALUES - -CMS_verify() returns 1 for a successful verification and zero if an error -occurred. - -CMS_get0_signers() returns all signers or NULL if an error occurred. - -The error can be obtained from L - -=head1 BUGS - -The trusted certificate store is not searched for the signing certificate, -this is primarily due to the inadequacies of the current B -functionality. - -The lack of single pass processing means that the signed content must all -be held in memory if it is not detached. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -CMS_verify() was added to OpenSSL 0.9.8 - -=cut diff --git a/src/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod b/src/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod deleted file mode 100644 index 2beadda129..0000000000 --- a/src/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -CMS_verify_receipt - verify a CMS signed receipt - -=head1 SYNOPSIS - - #include - - int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags); - -=head1 DESCRIPTION - -CMS_verify_receipt() verifies a CMS signed receipt. B is the signed -receipt to verify. B is the original SignedData structure containing the -receipt request. B is a set of certificates in which to search for the -signing certificate. B is a trusted certificate store (used for chain -verification). - -B is an optional set of flags, which can be used to modify the verify -operation. - -=head1 NOTES - -This functions behaves in a similar way to CMS_verify() except the flag values -B, B, B and B are not -supported since they do not make sense in the context of signed receipts. - -=head1 RETURN VALUES - -CMS_verify_receipt() returns 1 for a successful verification and zero if an -error occurred. - -The error can be obtained from L - -=head1 SEE ALSO - -L, -L, -L, - -=head1 HISTORY - -CMS_verify_receipt() was added to OpenSSL 0.9.8 - -=cut -- cgit v1.2.3-55-g6feb