| // Copyright 2025 The BoringSSL Authors | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // https://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| #ifndef OPENSSL_HEADER_CMS_H | |
| #define OPENSSL_HEADER_CMS_H | |
| #include <openssl/base.h> // IWYU pragma: export | |
| #include <openssl/stack.h> | |
| #if defined(__cplusplus) | |
| extern "C" { | |
| #endif | |
| // CMS. | |
| // | |
| // This library contains functions for implementing a small subset of OpenSSL's | |
| // API for CMS (RFC 5652). A general CMS implementation, notably one suitable | |
| // for S/MIME, is out of scope for BoringSSL. | |
| // | |
| // As this library is intentionally not a general CMS implementation, BoringSSL | |
| // continues to define |OPENSSL_NO_CMS|, so that most callers turn off their | |
| // general-purpose CMS code. In callers that are compatible with this subset, | |
| // the |BORINGSSL_NO_NO_CMS| build option can be used to suppress | |
| // |OPENSSL_NO_CMS|. | |
| DECLARE_STACK_OF(X509) | |
| // CMS_* are flags that can be passed to functions in this library. Their | |
| // interpretation is specified in the corresponding functions. | |
| #define CMS_NOCERTS 0x2 | |
| #define CMS_DETACHED 0x40 | |
| #define CMS_BINARY 0x80 | |
| #define CMS_NOATTR 0x100 | |
| #define CMS_NOSMIMECAP 0x200 | |
| #define CMS_STREAM 0x1000 | |
| #define CMS_PARTIAL 0x4000 | |
| #define CMS_USE_KEYID 0x10000 | |
| #define CMS_NO_SIGNING_TIME 0x400000 | |
| // CMS_sign returns a newly-allocated |CMS_ContentInfo| structure for building a | |
| // SignedData (RFC 5652), or NULL on error. | |
| // | |
| // |certs| must be NULL or zero length. BoringSSL does not support embedding | |
| // certificates in SignedData. | |
| // | |
| // |flags| must contain |CMS_DETACHED|, which indicates an external signature. | |
| // BoringSSL only supports generating external signatures and does not support | |
| // embedding encapsulated content directly in a SignedData. | |
| // | |
| // If |pkey| is non-NULL, |CMS_add1_signer| is automatically called with | |
| // |signcert|, |pkey|, a default hash of SHA-256, and |flags|. |flags| will then | |
| // additionally be interpreted as in |CMS_add1_signer|. | |
| // | |
| // If |CMS_PARTIAL| or |CMS_STREAM| is set in |flags|, the object will be left | |
| // incomplete. |data| will then be ignored and should be NULL. The caller can | |
| // then continue configuring it and finalizing it with |CMS_final|. Otherwise, | |
| // the object will be finalized with |data| and |flags| passed to |CMS_final|. | |
| OPENSSL_EXPORT CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, | |
| STACK_OF(X509) *certs, BIO *data, | |
| uint32_t flags); | |
| // CMS_ContentInfo_free releases memory associated with |cms|. | |
| OPENSSL_EXPORT void CMS_ContentInfo_free(CMS_ContentInfo *cms); | |
| // CMS_add1_signer adds a signer to |cms|, which must be a SignedData created by | |
| // |CMS_sign|, with the |CMS_PARTIAL| flag set. The signer will use |signcert|, | |
| // |pkey|, and |md| for the signing certificate, private key, and digest | |
| // algorithm, respectively. It returns a non-NULL pointer to the signer on | |
| // success, and NULL on error. The signer is owned by |cms| and should not be | |
| // released by the caller. | |
| // | |
| // |flags| is interpreted as follows: | |
| // | |
| // - |CMS_PARTIAL| must not be set. BoringSSL does not support configuring a | |
| // signer in multiple steps. | |
| // | |
| // - |CMS_NOCERTS| must be set. BoringSSL does not support embedding | |
| // certificates in SignedData. | |
| // | |
| // - |CMS_NOATTR| must be set. BoringSSL does not support attributes in | |
| // SignedData. | |
| // | |
| // - If |CMS_USE_KEYID| is set, SignerInfos will be identified by subject key | |
| // identifier instead of issuer and serial number. |signcert| must then have | |
| // the subject key identifier extension. | |
| // | |
| // BoringSSL currently only supports one signer per |CMS_ContentInfo|. | |
| // Subsequent calls will fail. Additionally, only RSA keys are currently | |
| // supported for |pkey|. | |
| OPENSSL_EXPORT CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, | |
| X509 *signcert, EVP_PKEY *pkey, | |
| const EVP_MD *md, | |
| uint32_t flags); | |
| // CMS_final finalizes constructing |cms|, which must have been initialized with | |
| // the |CMS_PARTIAL| flag. |data| is read, until EOF, as the data to be | |
| // processed by CMS. It returns one on success and zero on error. | |
| // | |
| // |CMS_BINARY| must be set in |flags|. BoringSSL does not support translating | |
| // inputs according to S/MIME. | |
| // | |
| // |dcont| must be NULL. What a non-NULL |dcont| does is not clearly documented | |
| // by OpenSSL, and there are no tests to demonstrate its behavior. | |
| OPENSSL_EXPORT int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, | |
| uint32_t flags); | |
| // i2d_CMS_bio encodes |cms| as a DER-encoded ContentInfo structure (RFC 5652). | |
| // It returns one on success and zero on failure. | |
| OPENSSL_EXPORT int i2d_CMS_bio(BIO *out, CMS_ContentInfo *cms); | |
| // i2d_CMS_bio_stream calls |i2d_CMS_bio|. |in| must be NULL and |flags| must | |
| // not contain |CMS_STREAM|. BoringSSL does not support any streaming modes for | |
| // CMS. | |
| OPENSSL_EXPORT int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *in, | |
| int flags); | |
| #if defined(__cplusplus) | |
| } // extern C | |
| extern "C++" { | |
| BSSL_NAMESPACE_BEGIN | |
| BORINGSSL_MAKE_DELETER(CMS_ContentInfo, CMS_ContentInfo_free) | |
| BSSL_NAMESPACE_END | |
| } // extern C++ | |
| #endif | |
| #define CMS_R_CERTIFICATE_HAS_NO_KEYID 100 | |
| #define CMS_R_PRIVATE_KEY_DOES_NOT_MATCH_CERTIFICATE 101 | |
| #endif // OPENSSL_HEADER_CMS_H |