diff options
33 files changed, 2040 insertions, 1253 deletions
diff --git a/lib/libcrypto/man/CMS_add0_cert.3 b/lib/libcrypto/man/CMS_add0_cert.3 new file mode 100644 index 00000000000..b02eb066730 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_add1_recipient_cert.3 b/lib/libcrypto/man/CMS_add1_recipient_cert.3 new file mode 100644 index 00000000000..4e848446a66 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_add1_signer.3 b/lib/libcrypto/man/CMS_add1_signer.3 new file mode 100644 index 00000000000..403ec5b8e3b --- /dev/null +++ b/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/lib/libcrypto/man/CMS_compress.3 b/lib/libcrypto/man/CMS_compress.3 new file mode 100644 index 00000000000..1330464441b --- /dev/null +++ b/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/lib/libcrypto/man/CMS_decrypt.3 b/lib/libcrypto/man/CMS_decrypt.3 new file mode 100644 index 00000000000..3a34f10783c --- /dev/null +++ b/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/lib/libcrypto/man/CMS_encrypt.3 b/lib/libcrypto/man/CMS_encrypt.3 new file mode 100644 index 00000000000..5d7b0bf4704 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_final.3 b/lib/libcrypto/man/CMS_final.3 new file mode 100644 index 00000000000..4e7912a4e00 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_get0_RecipientInfos.3 b/lib/libcrypto/man/CMS_get0_RecipientInfos.3 new file mode 100644 index 00000000000..4db69b57b8a --- /dev/null +++ b/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/lib/libcrypto/man/CMS_get0_SignerInfos.3 b/lib/libcrypto/man/CMS_get0_SignerInfos.3 new file mode 100644 index 00000000000..99aab48193f --- /dev/null +++ b/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/lib/libcrypto/man/CMS_get0_type.3 b/lib/libcrypto/man/CMS_get0_type.3 new file mode 100644 index 00000000000..e77dd655e6a --- /dev/null +++ b/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/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 b/lib/libcrypto/man/CMS_get1_ReceiptRequest.3 new file mode 100644 index 00000000000..ab19f87fab1 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_sign.3 b/lib/libcrypto/man/CMS_sign.3 new file mode 100644 index 00000000000..af75a20d6bb --- /dev/null +++ b/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/lib/libcrypto/man/CMS_sign_receipt.3 b/lib/libcrypto/man/CMS_sign_receipt.3 new file mode 100644 index 00000000000..de7a8c0e10e --- /dev/null +++ b/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/lib/libcrypto/man/CMS_uncompress.3 b/lib/libcrypto/man/CMS_uncompress.3 new file mode 100644 index 00000000000..c651f24de2f --- /dev/null +++ b/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/lib/libcrypto/man/CMS_verify.3 b/lib/libcrypto/man/CMS_verify.3 new file mode 100644 index 00000000000..0ab1baf6b35 --- /dev/null +++ b/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/lib/libcrypto/man/CMS_verify_receipt.3 b/lib/libcrypto/man/CMS_verify_receipt.3 new file mode 100644 index 00000000000..0977f267bc2 --- /dev/null +++ b/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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index d896f436bc1..2c5ffbb8e43 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 <bsd.own.mk> # 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/lib/libssl/src/doc/crypto/CMS_add0_cert.pod b/lib/libssl/src/doc/crypto/CMS_add0_cert.pod deleted file mode 100644 index b289237ec2f..00000000000 --- a/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 <openssl/cms.h> - - 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<cert> to B<cms>. -must be of type signed data or enveloped data. - -CMS_get1_certs() returns all certificates in B<cms>. - -CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls() -returns any CRLs in B<cms>. - -=head1 NOTES - -The CMS_ContentInfo structure B<cms> 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<certificates> and -B<crls> fields of SignedData structure. For enveloped data they are added to -B<OriginatorInfo>. - -As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it -must not be freed up after the call as opposed to CMS_add1_cert() where B<cert> -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<cms> type is invalid. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_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/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod b/lib/libssl/src/doc/crypto/CMS_add1_recipient_cert.pod deleted file mode 100644 index 8a39391aa48..00000000000 --- a/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 <openssl/cms.h> - - 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<recip> to CMS_ContentInfo enveloped -data structure B<cms> as a KeyTransRecipientInfo structure. - -CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using -wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional -values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped -data structure B<cms> as a KEKRecipientInfo structure. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_encrypt() with the flag B<CMS_PARTIAL> 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<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. - -Currently only AES based key wrapping algorithms are supported for B<nid>, -specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. -If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used -consistent with B<keylen>. - -=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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<CMS_final(3)|CMS_final(3)>, - -=head1 HISTORY - -CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL -0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_compress.pod b/lib/libssl/src/doc/crypto/CMS_compress.pod deleted file mode 100644 index 0a0715271d3..00000000000 --- a/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 <openssl/cms.h> - - CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); - -=head1 DESCRIPTION - -CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid> -is the compression algorithm to use or B<NID_undef> to use the default -algorithm (zlib compression). B<in> is the content to be compressed. -B<flags> is an optional set of flags. - -=head1 NOTES - -The only currently supported compression algorithm is zlib using the NID -NID_zlib_compression. - -If zlib support is not compiled into OpenSSL then CMS_compress() will return -an error. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B<CMS_BINARY> is set no translation -occurs. This option should be used if the supplied data is in binary format -otherwise the translation will corrupt it. If B<CMS_BINARY> is set then -B<CMS_TEXT> is ignored. - -If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is -returned suitable for streaming I/O: no data is read from the BIO B<in>. - -The compressed data is included in the CMS_ContentInfo structure, unless -B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in -practice and is not supported by SMIME_write_CMS(). - -=head1 NOTES - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)> - -=head1 HISTORY - -CMS_compress() was added to OpenSSL 0.9.8 -The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_decrypt.pod b/lib/libssl/src/doc/crypto/CMS_decrypt.pod deleted file mode 100644 index 3b44cec6039..00000000000 --- a/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 <openssl/cms.h> - - 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<pkey> is the private key of the recipient, B<cert> is the -recipient's certificate, B<out> is a BIO to write the content to and -B<flags> is an optional set of flags. - -The B<dcont> 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<cert> 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<CMS_DEBUG_DECRYPT> is set -then the above behaviour is modified and an error B<is> returned if no -recipient encrypted key can be decrypted B<without> generating a random -content encryption key. Applications should use this flag with -B<extreme caution> 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<cert> and B<pkey> 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<cert> and B<pkey> set to NULL. - -The following flags can be passed in the B<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_encrypt.pod b/lib/libssl/src/doc/crypto/CMS_encrypt.pod deleted file mode 100644 index f697e87e2bc..00000000000 --- a/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 <openssl/cms.h> - - 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<certs> -is a list of recipient certificates. B<in> is the content to be encrypted. -B<cipher> is the symmetric cipher to use. B<flags> 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<cipher> 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<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -Normally the supplied content is translated into MIME canonical format (as -required by the S/MIME specifications) if B<CMS_BINARY> is set no translation -occurs. This option should be used if the supplied data is in binary format -otherwise the translation will corrupt it. If B<CMS_BINARY> is set then -B<CMS_TEXT> is ignored. - -OpenSSL will by default identify recipient certificates using issuer name -and serial number. If B<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. - -If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is -returned suitable for streaming I/O: no data is read from the BIO B<in>. - -If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> 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<CMS_DETACHED> is set in which case it is omitted. This is rarely used in -practice and is not supported by SMIME_write_CMS(). - -=head1 NOTES - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info -structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> -and CMS_add0_recipient_key(). - -The parameter B<certs> may be NULL if B<CMS_PARTIAL> 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 -The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_final.pod b/lib/libssl/src/doc/crypto/CMS_final.pod deleted file mode 100644 index c5f1722aafa..00000000000 --- a/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 <openssl/cms.h> - - int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); - -=head1 DESCRIPTION - -CMS_final() finalises the structure B<cms>. It's purpose is to perform any -operations necessary on B<cms> (digest computation for example) and set the -appropriate fields. The parameter B<data> contains the content to be -processed. The B<dcont> parameter contains a BIO to write content to after -processing: this is only used with detached data and will usually be set to -NULL. - -=head1 NOTES - -This function will normally be called when the B<CMS_PARTIAL> flag is used. It -should only be used when streaming is not performed because the streaming -I/O functions perform finalisation operations internally. - -=head1 RETURN VALUES - -CMS_final() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_final() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod b/lib/libssl/src/doc/crypto/CMS_get0_RecipientInfos.pod deleted file mode 100644 index da3914c0c00..00000000000 --- a/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 <openssl/cms.h> - - 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<ri>. -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<ri>, which -must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in -B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. - -CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the -CMS_RecipientInfo structure B<ri>, 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<pkey> with -the CMS_RecipientInfo structure B<ri>, which must be of type -CMS_RECIPINFO_TRANS. - -CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the -CMS_RecipientInfo structure B<ri> 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<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if -present is written to B<pdate>, if the B<other> field is present the components -B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and -B<pothertype>. - -CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen> -parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>, -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<key> of length -B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type -CMS_RECIPINFO_KEK. - -CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure -B<ri> in structure B<cms>. 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<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod b/lib/libssl/src/doc/crypto/CMS_get0_SignerInfos.pod deleted file mode 100644 index 557cda6c3e1..00000000000 --- a/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 <openssl/cms.h> - - 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<si>. Either the -keyidentifier will be set in B<keyid> or B<both> issuer name and serial number -in B<issuer> and B<sno>. - -CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer -identifier B<si>. It returns zero if the comparison is successful and non zero -if not. - -CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to -B<signer>. - -=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<or> if -there are no signers this is not a problem in practice because the only -error which can occur is if the B<cms> 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<ERR_get_error(3)|ERR_get_error(3)> - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_get0_type.pod b/lib/libssl/src/doc/crypto/CMS_get0_type.pod deleted file mode 100644 index bc2690ee1a9..00000000000 --- a/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 <openssl/cms.h> - - 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<CMS_PARTIAL> -flag and B<before> 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<not> be freed up. CMS_set1_eContentType() copies the -supplied OID and it B<should> be freed up after use. - -The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> 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<ERR_get_error(3)|ERR_get_error(3)> - -=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/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod b/lib/libssl/src/doc/crypto/CMS_get1_ReceiptRequest.pod deleted file mode 100644 index a7babb1a6e0..00000000000 --- a/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 <openssl/cms.h> - - 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<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set -to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL -the allOrFirstTier option in B<receiptsFrom> is used and set to the value of -the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList> -option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the -B<receiptsTo> field value. - -The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr> -to SignerInfo structure B<si>. - -int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if -any is found it is decoded and written to B<prr>. - -CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. -The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier> -option of B<receiptsFrom> is used its value is copied to B<pallorfirst> -otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo> -parameter is copied to B<prto>. - -=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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, L<CMS_verify(3)|CMS_verify(3)> -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)> - -=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/lib/libssl/src/doc/crypto/CMS_sign.pod b/lib/libssl/src/doc/crypto/CMS_sign.pod deleted file mode 100644 index cc6d17faf69..00000000000 --- a/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 <openssl/cms.h> - - 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<signcert> is -the certificate to sign with, B<pkey> is the corresponding private key. -B<certs> is an optional additional set of certificates to include in the CMS -structure (for example any intermediate CAs in the chain). Any or all of -these parameters can be B<NULL>, see B<NOTES> below. - -The data to be signed is read from BIO B<data>. - -B<flags> is an optional set of flags. - -=head1 NOTES - -Any of the following flags (ored together) can be passed in the B<flags> -parameter. - -Many S/MIME clients expect the signed content to include valid MIME headers. If -the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended -to the data. - -If B<CMS_NOCERTS> 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<signcert> parameter though. This can reduce the size of the signature if -the signers certificate can be obtained by other means: for example a -previously signed message. - -The data being signed is included in the CMS_ContentInfo structure, unless -B<CMS_DETACHED> 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<CMS_BINARY> is set no translation -occurs. This option should be used if the supplied data is in binary format -otherwise the translation will corrupt it. - -The SignedData structure includes several CMS signedAttributes including the -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes -will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are -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<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. - -If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo> -structure is just initialized ready to perform the signing operation. The -signing is however B<not> performed and the data to be signed is not read from -the B<data> parameter. Signing is deferred until after the data has been -written. In this way data can be signed in a single pass. - -If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is -output to which additional signers and capabilities can be added before -finalization. - -If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is -B<not> complete and outputting its contents via a function that does not -properly finalize the B<CMS_ContentInfo> structure will give unpredictable -results. - -Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), -PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_CMS(). - -If a signer is specified it will use the default digest for the signing -algorithm. This is B<SHA1> for both RSA and DSA keys. - -If B<signcert> and B<pkey> 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<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the -B<CMS_PARTIAL> 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<CMS_final()> 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> - -=head1 HISTORY - -CMS_sign() was added to OpenSSL 0.9.8 - -The B<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. - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod b/lib/libssl/src/doc/crypto/CMS_sign_add1_signer.pod deleted file mode 100644 index ed4d9a9234b..00000000000 --- a/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 <openssl/cms.h> - - 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<signcert> and private -key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData -structure B<cms>. - -The CMS_ContentInfo structure should be obtained from an initial call to -CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a -valid CMS_ContentInfo SignedData structure. - -If the B<md> parameter is B<NULL> then the default digest for the public -key algorithm will be used. - -Unless the B<CMS_REUSE_DIGEST> 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<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> 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<flags> -parameter. - -If B<CMS_REUSE_DIGEST> 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<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> 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<CMS_NOCERTS> 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<signcert> parameter though. This can reduce the size of the signature if -the signers certificate can be obtained by other means: for example a -previously signed message. - -The SignedData structure includes several CMS signedAttributes including the -signing time, the CMS content type and the supported list of ciphers in an -SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes -will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are -omitted. - -OpenSSL will by default identify signing certificates using issuer name -and serial number. If B<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. - -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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_final(3)|CMS_final(3)>, - -=head1 HISTORY - -CMS_sign_add1_signer() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod b/lib/libssl/src/doc/crypto/CMS_sign_receipt.pod deleted file mode 100644 index f603ab66f01..00000000000 --- a/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 <openssl/cms.h> - - 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<si> is -the B<CMS_SignerInfo> structure containing the signed receipt request. -B<signcert> is the certificate to sign with, B<pkey> is the corresponding -private key. B<certs> is an optional additional set of certificates to include -in the CMS structure (for example any intermediate CAs in the chain). - -B<flags> is an optional set of flags. - -=head1 NOTES - -This functions behaves in a similar way to CMS_sign() except the flag values -B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM> -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<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>, -L<CMS_sign(3)|CMS_sign(3)> - -=head1 HISTORY - -CMS_sign_receipt() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_uncompress.pod b/lib/libssl/src/doc/crypto/CMS_uncompress.pod deleted file mode 100644 index fcbfec128a3..00000000000 --- a/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 <openssl/cms.h> - - 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<cms>. B<data> is a BIO to write the content to and -B<flags> is an optional set of flags. - -The B<dcont> 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<flags> parameter. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> 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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_compress(3)|CMS_compress(3)> - -=head1 HISTORY - -CMS_uncompress() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_verify.pod b/lib/libssl/src/doc/crypto/CMS_verify.pod deleted file mode 100644 index 69425008aaf..00000000000 --- a/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 <openssl/cms.h> - - 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<cms> is the CMS_ContentInfo -structure to verify. B<certs> is a set of certificates in which to search for -the signing certificate(s). B<store> is a trusted certificate store used for -chain verification. B<indata> is the detached content if the content is not -present in B<cms>. The content is written to B<out> if it is not NULL. - -B<flags> 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<cms>, 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<cms>. The type of B<cms> must -be SignedData. There must be at least one signature on the data and if -the content is detached B<indata> cannot be B<NULL>. - -An attempt is made to locate all the signing certificate(s), first looking in -the B<certs> parameter (if it is not NULL) and then looking in any -certificates contained in the B<cms> structure itself. If any signing -certificate cannot be located the operation fails. - -Each signing certificate is chain verified using the B<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 B<store> any internal -CRLs are used in addition to attempting to look them up in B<store>. If any -chain verify fails an error code is returned. - -Finally the signed content is read (and written to B<out> 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<flags> -parameter to change the default verify behaviour. - -If B<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 B<certs> parameter. - -If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any -CRLs in the message itself are ignored. - -If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not -verified. - -If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not -verified. - -If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. - -=head1 NOTES - -One application of B<CMS_NOINTERN> is to only accept messages signed by -a small number of certificates. The acceptable certificates would be passed -in the B<certs> parameter. In this case if the signer is not one of the -certificates supplied in B<certs> 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<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 B<out> 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<ERR_get_error(3)|ERR_get_error(3)> - -=head1 BUGS - -The trusted certificate store is not searched for the signing certificate, -this is primarily due to the inadequacies of the current B<X509_STORE> -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<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> - -=head1 HISTORY - -CMS_verify() was added to OpenSSL 0.9.8 - -=cut diff --git a/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod b/lib/libssl/src/doc/crypto/CMS_verify_receipt.pod deleted file mode 100644 index 2beadda1297..00000000000 --- a/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 <openssl/cms.h> - - 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<rcms> is the signed -receipt to verify. B<ocms> is the original SignedData structure containing the -receipt request. B<certs> is a set of certificates in which to search for the -signing certificate. B<store> is a trusted certificate store (used for chain -verification). - -B<flags> 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<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> 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<ERR_get_error(3)|ERR_get_error(3)> - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, -L<CMS_verify(3)|CMS_verify(3)>, - -=head1 HISTORY - -CMS_verify_receipt() was added to OpenSSL 0.9.8 - -=cut |