SecCmsSignedData.h
1 /* 2 * Copyright (c) 2004-2018 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24 /*! 25 @header SecCmsSignedData.h 26 27 @availability 10.4 and later 28 @abstract Interfaces of the CMS implementation. 29 @discussion The functions here implement functions for encoding 30 and decoding Cryptographic Message Syntax (CMS) objects 31 as described in rfc3369. 32 */ 33 34 #ifndef _SECURITY_SECCMSSIGNEDDATA_H_ 35 #define _SECURITY_SECCMSSIGNEDDATA_H_ 1 36 37 #include <Security/SecCmsBase.h> 38 #include <Security/SecTrust.h> 39 40 __BEGIN_DECLS 41 42 /*! 43 @function 44 @abstract Create a new SecCmsSignedData object. 45 @param cmsg Pointer to a SecCmsMessage in which this SecCmsSignedData 46 should be created. 47 */ 48 extern SecCmsSignedDataRef 49 SecCmsSignedDataCreate(SecCmsMessageRef cmsg); 50 51 /*! 52 @function 53 */ 54 extern void 55 SecCmsSignedDataDestroy(SecCmsSignedDataRef sigd); 56 57 /*! 58 @function 59 @abstract Retrieve the SignedData's signer list. 60 */ 61 extern SecCmsSignerInfoRef * 62 SecCmsSignedDataGetSignerInfos(SecCmsSignedDataRef sigd); 63 64 /*! 65 @function 66 */ 67 extern int 68 SecCmsSignedDataSignerInfoCount(SecCmsSignedDataRef sigd); 69 70 /*! 71 @function 72 */ 73 extern SecCmsSignerInfoRef 74 SecCmsSignedDataGetSignerInfo(SecCmsSignedDataRef sigd, int i); 75 76 /*! 77 @function 78 @abstract Retrieve the SignedData's digest algorithm list. 79 */ 80 #pragma clang diagnostic push 81 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 82 extern SECAlgorithmID ** 83 SecCmsSignedDataGetDigestAlgs(SecCmsSignedDataRef sigd); 84 #pragma clang diagnostic pop 85 86 /*! 87 @function 88 @abstract Return pointer to this signedData's contentinfo. 89 */ 90 extern SecCmsContentInfoRef 91 SecCmsSignedDataGetContentInfo(SecCmsSignedDataRef sigd); 92 93 /*! 94 @function 95 @discussion XXX Should be obsoleted. 96 */ 97 extern OSStatus 98 SecCmsSignedDataImportCerts(SecCmsSignedDataRef sigd, SecKeychainRef keychain, 99 SECCertUsage certusage, Boolean keepcerts); 100 101 /*! 102 @function 103 @abstract See if we have digests in place. 104 */ 105 extern Boolean 106 SecCmsSignedDataHasDigests(SecCmsSignedDataRef sigd); 107 108 /*! 109 @function 110 @abstract Check the signatures. 111 @discussion The digests were either calculated during decoding (and are stored in the 112 signedData itself) or set after decoding using SecCmsSignedDataSetDigests. 113 114 The verification checks if the signing cert is valid and has a trusted chain 115 for the purpose specified by "policies". 116 117 If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly. 118 Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate(). 119 */ 120 extern OSStatus 121 SecCmsSignedDataVerifySignerInfo(SecCmsSignedDataRef sigd, int i, SecKeychainRef keychainOrArray, 122 CFTypeRef policies, SecTrustRef *trustRef); 123 124 /*! 125 @function 126 @abstract Verify the certs in a certs-only message. 127 */ 128 extern OSStatus 129 SecCmsSignedDataVerifyCertsOnly(SecCmsSignedDataRef sigd, 130 SecKeychainRef keychainOrArray, 131 CFTypeRef policies); 132 133 /*! 134 @function 135 */ 136 extern OSStatus 137 SecCmsSignedDataAddCertList(SecCmsSignedDataRef sigd, CFArrayRef certlist); 138 139 /*! 140 @function 141 @abstract Add cert and its entire chain to the set of certs. 142 */ 143 extern OSStatus 144 SecCmsSignedDataAddCertChain(SecCmsSignedDataRef sigd, SecCertificateRef cert); 145 146 /*! 147 @function 148 */ 149 extern OSStatus 150 SecCmsSignedDataAddCertificate(SecCmsSignedDataRef sigd, SecCertificateRef cert); 151 152 /*! 153 @function 154 */ 155 extern Boolean 156 SecCmsSignedDataContainsCertsOrCrls(SecCmsSignedDataRef sigd); 157 158 159 #if TARGET_OS_OSX 160 /*! 161 @function 162 @abstract Retrieve the SignedData's certificate list. 163 */ 164 #pragma clang diagnostic push 165 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 166 extern CSSM_DATA_PTR * 167 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd) 168 API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst); 169 #pragma clang diagnostic pop 170 #else // !TARGET_OS_OSX 171 /*! 172 @function 173 @abstract Retrieve the SignedData's certificate list. 174 */ 175 extern SecAsn1Item * * 176 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd) 177 API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macCatalyst); 178 #endif // !TARGET_OS_OSX 179 180 /*! 181 @function 182 @abstract Create a certs-only SignedData. 183 @param cert Base certificate that will be included 184 @param include_chain If true, include the complete cert chain for cert. 185 @discussion More certs and chains can be added via AddCertificate and AddCertChain. 186 @result An error results in a return value of NULL and an error set. 187 */ 188 extern SecCmsSignedDataRef 189 SecCmsSignedDataCreateCertsOnly(SecCmsMessageRef cmsg, SecCertificateRef cert, Boolean include_chain); 190 191 #if TARGET_OS_IPHONE 192 /*! 193 @function 194 @abstract Finalize the digests in digestContext and apply them to sigd. 195 @param sigd A SecCmsSignedDataRef for which the digests have been calculated 196 @param digestContext A digestContext created with SecCmsDigestContextStartMultiple. 197 @result The digest will have been applied to sigd. After this call completes sigd is ready to accept 198 SecCmsSignedDataVerifySignerInfo() calls. The caller should still destroy digestContext with a SecCmsDigestContextDestroy() call. 199 200 */ 201 extern OSStatus SecCmsSignedDataSetDigestContext(SecCmsSignedDataRef sigd, 202 SecCmsDigestContextRef digestContext) 203 API_AVAILABLE(ios(2.0), tvos(2.0), watchos(1.0)) API_UNAVAILABLE(macos, macCatalyst); 204 #endif 205 206 #if TARGET_OS_OSX 207 extern OSStatus 208 SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd, 209 SecCmsSignerInfoRef signerinfo); 210 211 #pragma clang diagnostic push 212 #pragma clang diagnostic ignored "-Wdeprecated-declarations" 213 extern OSStatus 214 SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd, 215 SECAlgorithmID **digestalgs, 216 CSSM_DATA_PTR *digests) 217 API_AVAILABLE(macos(10.4)) API_UNAVAILABLE(macCatalyst); 218 #pragma clang diagnostic pop 219 #endif 220 221 __END_DECLS 222 223 #endif /* _SECURITY_SECCMSSIGNEDDATA_H_ */