cms.h (5889B)
1 // Copyright 2025 The BoringSSL Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_CMS_H 16 #define OPENSSL_HEADER_CMS_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 20 #include <openssl/stack.h> 21 22 #if defined(__cplusplus) 23 extern "C" { 24 #endif 25 26 27 // CMS. 28 // 29 // This library contains functions for implementing a small subset of OpenSSL's 30 // API for CMS (RFC 5652). A general CMS implementation, notably one suitable 31 // for S/MIME, is out of scope for BoringSSL. 32 // 33 // As this library is intentionally not a general CMS implementation, BoringSSL 34 // continues to define |OPENSSL_NO_CMS|, so that most callers turn off their 35 // general-purpose CMS code. In callers that are compatible with this subset, 36 // the |BORINGSSL_NO_NO_CMS| build option can be used to suppress 37 // |OPENSSL_NO_CMS|. 38 39 DECLARE_STACK_OF(X509) 40 41 // CMS_* are flags that can be passed to functions in this library. Their 42 // interpretation is specified in the corresponding functinos. 43 #define CMS_NOCERTS 0x2 44 #define CMS_DETACHED 0x40 45 #define CMS_BINARY 0x80 46 #define CMS_NOATTR 0x100 47 #define CMS_NOSMIMECAP 0x200 48 #define CMS_STREAM 0x1000 49 #define CMS_PARTIAL 0x4000 50 #define CMS_USE_KEYID 0x10000 51 #define CMS_NO_SIGNING_TIME 0x400000 52 53 // CMS_sign returns a newly-allocated |CMS_ContentInfo| structure for building a 54 // SignedData (RFC 5652), or NULL on error. 55 // 56 // |certs| must be NULL or zero length. BoringSSL does not support embedding 57 // certificates in SignedData. 58 // 59 // |flags| must contain |CMS_DETACHED|, which indicates an external signature. 60 // BoringSSL only supports generating external signatures and does not support 61 // embedding encapsulated content directly in a SignedData. 62 // 63 // If |pkey| is non-NULL, |CMS_add1_signer| is automatically called with 64 // |signcert|, |pkey|, a default hash of SHA-256, and |flags|. |flags| will then 65 // additionally be interpreted as in |CMS_add1_signer|. 66 // 67 // If |CMS_PARTIAL| or |CMS_STREAM| is set in |flags|, the object will be left 68 // incomplete. |data| will then be ignored and should be NULL. The caller can 69 // then continue configuring it and finalizing it with |CMS_final|. Otherwise, 70 // the object will be finalized with |data| and |flags| passed to |CMS_final|. 71 OPENSSL_EXPORT CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, 72 STACK_OF(X509) *certs, BIO *data, 73 uint32_t flags); 74 75 // CMS_ContentInfo_free releases memory associated with |cms|. 76 OPENSSL_EXPORT void CMS_ContentInfo_free(CMS_ContentInfo *cms); 77 78 // CMS_add1_signer adds a signer to |cms|, which must be a SignedData created by 79 // |CMS_sign|, with the |CMS_PARTIAL| flag set. The signer will use |signcert|, 80 // |pkey|, and |md| for the signing certificate, private key, and digest 81 // algorithm, respectively. It returns a non-NULL pointer to the signer on 82 // success, and NULL on error. The signer is owned by |cms| and should not be 83 // released by the caller. 84 // 85 // |flags| is interpreted as follows: 86 // 87 // - |CMS_PARTIAL| must not be set. BoringSSL does not support configuring a 88 // signer in multiple steps. 89 // 90 // - |CMS_NOCERTS| must be set. BoringSSL does not support embedding 91 // certificates in SignedData. 92 // 93 // - |CMS_NOATTR| must be set. BoringSSL does not support attributes in 94 // SignedData. 95 // 96 // - If |CMS_USE_KEYID| is set, SignerInfos will be identified by subject key 97 // identifier instead of issuer and serial number. |signcert| must then have 98 // the subject key identifier extension. 99 // 100 // BoringSSL currently only supports one signer per |CMS_ContentInfo|. 101 // Subsequent calls will fail. Additionally, only RSA keys are currently 102 // supported for |pkey|. 103 OPENSSL_EXPORT CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, 104 X509 *signcert, EVP_PKEY *pkey, 105 const EVP_MD *md, 106 uint32_t flags); 107 108 // CMS_final finalizes constructing |cms|, which must have been initialized with 109 // the |CMS_PARTIAL| flag. |data| is read, until EOF, as the data to be 110 // processed by CMS. It returns one on success and zero on error. 111 // 112 // |CMS_BINARY| must be set in |flags|. BoringSSL does not support translating 113 // inputs according to S/MIME. 114 // 115 // |dcont| must be NULL. What a non-NULL |dcont| does is not clearly documented 116 // by OpenSSL, and there are no tests to demonstrate its behavior. 117 OPENSSL_EXPORT int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, 118 uint32_t flags); 119 120 // i2d_CMS_bio encodes |cms| as a DER-encoded ContentInfo structure (RFC 5652). 121 // It returns one on success and zero on failure. 122 OPENSSL_EXPORT int i2d_CMS_bio(BIO *out, CMS_ContentInfo *cms); 123 124 // i2d_CMS_bio_stream calls |i2d_CMS_bio|. |in| must be NULL and |flags| must 125 // not contain |CMS_STREAM|. BoringSSL does not support any streaming modes for 126 // CMS. 127 OPENSSL_EXPORT int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *in, 128 int flags); 129 130 131 #if defined(__cplusplus) 132 } // extern C 133 134 extern "C++" { 135 BSSL_NAMESPACE_BEGIN 136 137 BORINGSSL_MAKE_DELETER(CMS_ContentInfo, CMS_ContentInfo_free) 138 139 BSSL_NAMESPACE_END 140 } // extern C++ 141 #endif 142 143 #define CMS_R_CERTIFICATE_HAS_NO_KEYID 100 144 #define CMS_R_PRIVATE_KEY_DOES_NOT_MATCH_CERTIFICATE 101 145 146 #endif // OPENSSL_HEADER_CMS_H