1/* 2 * Copyright (c) 2004,2008,2010,2013 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 SecCmsSignerInfo.h 26 @Copyright (c) 2004,2008,2010,2013 Apple Inc. All Rights Reserved. 27 28 @availability 10.4 and later 29 @abstract Interfaces of the CMS implementation. 30 @discussion The functions here implement functions for encoding 31 and decoding Cryptographic Message Syntax (CMS) objects 32 as described in rfc3369. 33 */ 34 35#ifndef _SECURITY_SECCMSSIGNERINFO_H_ 36#define _SECURITY_SECCMSSIGNERINFO_H_ 1 37 38#include <Security/SecCmsBase.h> 39 40#include <Security/SecTrust.h> 41 42 43#if defined(__cplusplus) 44extern "C" { 45#endif 46 47/*! 48 @function 49 */ 50extern SecCmsSignerInfoRef 51SecCmsSignerInfoCreate(SecCmsSignedDataRef sigd, SecIdentityRef identity, SECOidTag digestalgtag); 52 53/*! 54 @function 55 */ 56extern SecCmsSignerInfoRef 57SecCmsSignerInfoCreateWithSubjKeyID(SecCmsSignedDataRef sigd, const SecAsn1Item *subjKeyID, SecPublicKeyRef pubKey, SecPrivateKeyRef signingKey, SECOidTag digestalgtag); 58 59/*! 60 @function 61 */ 62extern SecCmsVerificationStatus 63SecCmsSignerInfoGetVerificationStatus(SecCmsSignerInfoRef signerinfo); 64 65/*! 66 @function 67 */ 68extern SECOidData * 69SecCmsSignerInfoGetDigestAlg(SecCmsSignerInfoRef signerinfo); 70 71/*! 72 @function 73 */ 74extern SECOidTag 75SecCmsSignerInfoGetDigestAlgTag(SecCmsSignerInfoRef signerinfo); 76 77/*! 78 @function 79 */ 80extern CFArrayRef 81SecCmsSignerInfoGetCertList(SecCmsSignerInfoRef signerinfo); 82 83/*! 84 @function 85 @abstract Return the signing time, in UTCTime format, of a CMS signerInfo. 86 @param sinfo SignerInfo data for this signer. 87 @discussion Returns a pointer to XXXX (what?) 88 @result A return value of NULL is an error. 89 */ 90extern OSStatus 91SecCmsSignerInfoGetSigningTime(SecCmsSignerInfoRef sinfo, CFAbsoluteTime *stime); 92 93/*! 94 @function 95 @abstract Return the signing cert of a CMS signerInfo. 96 @discussion The certs in the enclosing SignedData must have been imported already. 97 */ 98extern SecCertificateRef 99SecCmsSignerInfoGetSigningCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray); 100 101/*! 102 @function 103 @abstract Return the common name of the signer. 104 @param sinfo SignerInfo data for this signer. 105 @discussion Returns a CFStringRef containing the common name of the signer. 106 @result A return value of NULL is an error. 107 */ 108extern CF_RETURNS_RETAINED CFStringRef 109SecCmsSignerInfoGetSignerCommonName(SecCmsSignerInfoRef sinfo); 110 111/*! 112 @function 113 @abstract Return the email address of the signer 114 @param sinfo SignerInfo data for this signer. 115 @discussion Returns a CFStringRef containing the name of the signer. 116 @result A return value of NULL is an error. 117 */ 118extern CF_RETURNS_RETAINED CFStringRef 119SecCmsSignerInfoGetSignerEmailAddress(SecCmsSignerInfoRef sinfo); 120 121/*! 122 @function 123 @abstract Add the signing time to the authenticated (i.e. signed) attributes of "signerinfo". 124 @discussion This is expected to be included in outgoing signed 125 messages for email (S/MIME) but is likely useful in other situations. 126 127 This should only be added once; a second call will do nothing. 128 129 XXX This will probably just shove the current time into "signerinfo" 130 but it will not actually get signed until the entire item is 131 processed for encoding. Is this (expected to be small) delay okay? 132 */ 133extern OSStatus 134SecCmsSignerInfoAddSigningTime(SecCmsSignerInfoRef signerinfo, CFAbsoluteTime t); 135 136/*! 137 @function 138 @abstract Add a SMIMECapabilities attribute to the authenticated (i.e. signed) attributes of "signerinfo". 139 @discussion This is expected to be included in outgoing signed messages for email (S/MIME). 140 */ 141extern OSStatus 142SecCmsSignerInfoAddSMIMECaps(SecCmsSignerInfoRef signerinfo); 143 144/*! 145 @function 146 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo". 147 @discussion This is expected to be included in outgoing signed messages for email (S/MIME). 148 */ 149OSStatus 150SecCmsSignerInfoAddSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray); 151 152/*! 153 @function 154 @abstract Add a SMIMEEncryptionKeyPreferences attribute to the authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft. 155 @discussion This is expected to be included in outgoing signed messages for email (S/MIME), if compatibility with Microsoft mail clients is wanted. 156 */ 157OSStatus 158SecCmsSignerInfoAddMSSMIMEEncKeyPrefs(SecCmsSignerInfoRef signerinfo, SecCertificateRef cert, SecKeychainRef keychainOrArray); 159 160/*! 161 @function 162 @abstract Countersign a signerinfo. 163 */ 164extern OSStatus 165SecCmsSignerInfoAddCounterSignature(SecCmsSignerInfoRef signerinfo, 166 SECOidTag digestalg, SecIdentityRef identity); 167 168/*! 169 @function 170 @abstract The following needs to be done in the S/MIME layer code after signature of a signerinfo has been verified. 171 @param signerinfo The SecCmsSignerInfo object for which we verified the signature. 172 @result The preferred encryption certificate of the user who signed this message will be added to the users default Keychain and it will be marked as the preferred certificate to use when sending that person messages from now on. 173 */ 174extern OSStatus 175SecCmsSignerInfoSaveSMIMEProfile(SecCmsSignerInfoRef signerinfo); 176 177/*! 178 @function 179 @abstract Set cert chain inclusion mode for this signer. 180 */ 181extern OSStatus 182SecCmsSignerInfoIncludeCerts(SecCmsSignerInfoRef signerinfo, SecCmsCertChainMode cm, SECCertUsage usage); 183 184/*! @functiongroup CMS misc utility functions */ 185/*! 186 @function 187 Convert a SecCmsVerificationStatus to a human readable string. 188 */ 189extern const char * 190SecCmsUtilVerificationStatusToString(SecCmsVerificationStatus vs); 191 192 193#if defined(__cplusplus) 194} 195#endif 196 197#endif /* _SECURITY_SECCMSSIGNERINFO_H_ */ 198