| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | CMS_sign, CMS_sign_ex - create a CMS SignedData structure
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | #include <openssl/cms.h>
|
|---|
| 10 |
|
|---|
| 11 | CMS_ContentInfo *CMS_sign_ex(X509 *signcert, EVP_PKEY *pkey,
|
|---|
| 12 | STACK_OF(X509) *certs, BIO *data,
|
|---|
| 13 | unsigned int flags, OSSL_LIB_CTX *ctx,
|
|---|
| 14 | const char *propq);
|
|---|
| 15 | CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
|
|---|
| 16 | BIO *data, unsigned int flags);
|
|---|
| 17 |
|
|---|
| 18 | =head1 DESCRIPTION
|
|---|
| 19 |
|
|---|
| 20 | CMS_sign_ex() creates and returns a CMS SignedData structure.
|
|---|
| 21 | I<signcert> is the certificate to sign with, I<pkey> is the corresponding
|
|---|
| 22 | private key. I<certs> is an optional additional set of certificates to include
|
|---|
| 23 | in the CMS structure (for example any intermediate CAs in the chain). The
|
|---|
| 24 | library context I<libctx> and the property query I<propq> are used when
|
|---|
| 25 | retrieving algorithms from providers. Any or all of these parameters can be
|
|---|
| 26 | B<NULL>, see B<NOTES> below.
|
|---|
| 27 |
|
|---|
| 28 | The data to be signed is read from BIO B<data>.
|
|---|
| 29 |
|
|---|
| 30 | B<flags> is an optional set of flags.
|
|---|
| 31 |
|
|---|
| 32 | CMS_sign() is similar to CMS_sign_ex() but uses default values of NULL
|
|---|
| 33 | for the library context I<libctx> and the property query I<propq>.
|
|---|
| 34 |
|
|---|
| 35 | =head1 NOTES
|
|---|
| 36 |
|
|---|
| 37 | Any of the following flags (ored together) can be passed in the B<flags>
|
|---|
| 38 | parameter.
|
|---|
| 39 |
|
|---|
| 40 | Many S/MIME clients expect the signed content to include valid MIME headers. If
|
|---|
| 41 | the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended
|
|---|
| 42 | to the data.
|
|---|
| 43 |
|
|---|
| 44 | If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
|
|---|
| 45 | CMS_ContentInfo structure, the signer's certificate must still be supplied in
|
|---|
| 46 | the B<signcert> parameter though. This can reduce the size of the signature if
|
|---|
| 47 | the signers certificate can be obtained by other means: for example a
|
|---|
| 48 | previously signed message.
|
|---|
| 49 |
|
|---|
| 50 | The data being signed is included in the CMS_ContentInfo structure, unless
|
|---|
| 51 | B<CMS_DETACHED> is set in which case it is omitted. This is used for
|
|---|
| 52 | CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed
|
|---|
| 53 | messages for example.
|
|---|
| 54 |
|
|---|
| 55 | Normally the supplied content is translated into MIME canonical format (as
|
|---|
| 56 | required by the S/MIME specifications) if B<CMS_BINARY> is set no translation
|
|---|
| 57 | occurs. This option should be used if the supplied data is in binary format
|
|---|
| 58 | otherwise the translation will corrupt it.
|
|---|
| 59 |
|
|---|
| 60 | The SignedData structure includes several CMS signedAttributes including the
|
|---|
| 61 | signing time, the CMS content type and the supported list of ciphers in an
|
|---|
| 62 | SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
|
|---|
| 63 | will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
|
|---|
| 64 | omitted.
|
|---|
| 65 |
|
|---|
| 66 | If present the SMIMECapabilities attribute indicates support for the following
|
|---|
| 67 | algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
|
|---|
| 68 | bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
|
|---|
| 69 | If any of these algorithms is not available then it will not be included:
|
|---|
| 70 | for example the GOST algorithms will not be included if the GOST ENGINE is
|
|---|
| 71 | not loaded.
|
|---|
| 72 |
|
|---|
| 73 | OpenSSL will by default identify signing certificates using issuer name
|
|---|
| 74 | and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
|
|---|
| 75 | identifier value instead. An error occurs if the signing certificate does not
|
|---|
| 76 | have a subject key identifier extension.
|
|---|
| 77 |
|
|---|
| 78 | If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo>
|
|---|
| 79 | structure is just initialized ready to perform the signing operation. The
|
|---|
| 80 | signing is however B<not> performed and the data to be signed is not read from
|
|---|
| 81 | the B<data> parameter. Signing is deferred until after the data has been
|
|---|
| 82 | written. In this way data can be signed in a single pass.
|
|---|
| 83 |
|
|---|
| 84 | If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is
|
|---|
| 85 | output to which additional signers and capabilities can be added before
|
|---|
| 86 | finalization.
|
|---|
| 87 |
|
|---|
| 88 | If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
|
|---|
| 89 | B<not> complete and outputting its contents via a function that does not
|
|---|
| 90 | properly finalize the B<CMS_ContentInfo> structure will give unpredictable
|
|---|
| 91 | results.
|
|---|
| 92 |
|
|---|
| 93 | Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(),
|
|---|
| 94 | PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization
|
|---|
| 95 | can be performed by obtaining the streaming ASN1 B<BIO> directly using
|
|---|
| 96 | BIO_new_CMS().
|
|---|
| 97 |
|
|---|
| 98 | If a signer is specified it will use the default digest for the signing
|
|---|
| 99 | algorithm. This is B<SHA1> for both RSA and DSA keys.
|
|---|
| 100 |
|
|---|
| 101 | If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is
|
|---|
| 102 | output.
|
|---|
| 103 |
|
|---|
| 104 | The function CMS_sign() is a basic CMS signing function whose output will be
|
|---|
| 105 | suitable for many purposes. For finer control of the output format the
|
|---|
| 106 | B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the
|
|---|
| 107 | B<CMS_PARTIAL> flag set. Then one or more signers can be added using the
|
|---|
| 108 | function CMS_sign_add1_signer(), non default digests can be used and custom
|
|---|
| 109 | attributes added. CMS_final() must then be called to finalize the
|
|---|
| 110 | structure if streaming is not enabled.
|
|---|
| 111 |
|
|---|
| 112 | =head1 BUGS
|
|---|
| 113 |
|
|---|
| 114 | Some attributes such as counter signatures are not supported.
|
|---|
| 115 |
|
|---|
| 116 | =head1 RETURN VALUES
|
|---|
| 117 |
|
|---|
| 118 | CMS_sign_ex() and CMS_sign() return either a valid CMS_ContentInfo
|
|---|
| 119 | structure or NULL if an error occurred. The error can be obtained from
|
|---|
| 120 | ERR_get_error(3).
|
|---|
| 121 |
|
|---|
| 122 | =head1 SEE ALSO
|
|---|
| 123 |
|
|---|
| 124 | L<ERR_get_error(3)>, L<CMS_verify(3)>
|
|---|
| 125 |
|
|---|
| 126 | =head1 HISTORY
|
|---|
| 127 |
|
|---|
| 128 | The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8,
|
|---|
| 129 | it is supported for embedded data in OpenSSL 1.0.0 and later.
|
|---|
| 130 |
|
|---|
| 131 | The CMS_sign_ex() method was added in OpenSSL 3.0.
|
|---|
| 132 |
|
|---|
| 133 | =head1 COPYRIGHT
|
|---|
| 134 |
|
|---|
| 135 | Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 136 |
|
|---|
| 137 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 138 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 139 | in the file LICENSE in the source distribution or at
|
|---|
| 140 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 141 |
|
|---|
| 142 | =cut
|
|---|
