OSX/libsecurity_smime/lib/SecCmsSignedData.h

   1 /*
   2  *  Copyright (c) 2004,2011,2014 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     @Copyright (c) 2004,2011,2014 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_SECCMSSIGNEDDATA_H_
  36 #define _SECURITY_SECCMSSIGNEDDATA_H_  1
  37
  38 #include <Security/SecCmsBase.h>
  39 #include <Security/SecTrust.h>
  40
  41
  42 #if defined(__cplusplus)
  43 extern "C" {
  44 #endif
  45
  46 /*!
  47     @function
  48     @abstract Create a new SecCmsSignedData object.
  49     @param cmsg Pointer to a SecCmsMessage in which this SecCmsSignedData
  50         should be created.
  51  */
  52 extern SecCmsSignedDataRef
  53 SecCmsSignedDataCreate(SecCmsMessageRef cmsg);
  54
  55 /*!
  56     @function
  57  */
  58 extern void
  59 SecCmsSignedDataDestroy(SecCmsSignedDataRef sigd);
  60
  61 /*!
  62     @function
  63     @abstract Retrieve the SignedData's signer list.
  64  */
  65 extern SecCmsSignerInfoRef *
  66 SecCmsSignedDataGetSignerInfos(SecCmsSignedDataRef sigd);
  67
  68 /*!
  69     @function
  70  */
  71 extern int
  72 SecCmsSignedDataSignerInfoCount(SecCmsSignedDataRef sigd);
  73
  74 /*!
  75     @function
  76  */
  77 extern SecCmsSignerInfoRef
  78 SecCmsSignedDataGetSignerInfo(SecCmsSignedDataRef sigd, int i);
  79
  80 /*!
  81     @function
  82     @abstract Retrieve the SignedData's digest algorithm list.
  83  */
  84 extern SECAlgorithmID **
  85 SecCmsSignedDataGetDigestAlgs(SecCmsSignedDataRef sigd);
  86
  87 /*!
  88     @function
  89     @abstract Return pointer to this signedData's contentinfo.
  90  */
  91 extern SecCmsContentInfoRef
  92 SecCmsSignedDataGetContentInfo(SecCmsSignedDataRef sigd);
  93
  94 /*!
  95     @function
  96     @discussion XXX Should be obsoleted.
  97  */
  98 extern OSStatus
  99 SecCmsSignedDataImportCerts(SecCmsSignedDataRef sigd, SecKeychainRef keychain,
 100                                 SECCertUsage certusage, Boolean keepcerts);
 101
 102 /*!
 103     @function
 104     @abstract See if we have digests in place.
 105  */
 106 extern Boolean
 107 SecCmsSignedDataHasDigests(SecCmsSignedDataRef sigd);
 108
 109 /*!
 110     @function
 111     @abstract Check the signatures.
 112     @discussion The digests were either calculated during decoding (and are stored in the
 113                 signedData itself) or set after decoding using SecCmsSignedDataSetDigests.
 114
 115                 The verification checks if the signing cert is valid and has a trusted chain
 116                 for the purpose specified by "policies".
 117
 118                 If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
 119                 Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
 120  */
 121 extern OSStatus
 122 SecCmsSignedDataVerifySignerInfo(SecCmsSignedDataRef sigd, int i, SecKeychainRef keychainOrArray,
 123                                  CFTypeRef policies, SecTrustRef *trustRef);
 124
 125 /*!
 126     @function
 127     @abstract Verify the certs in a certs-only message.
 128 */
 129 extern OSStatus
 130 SecCmsSignedDataVerifyCertsOnly(SecCmsSignedDataRef sigd,
 131                                   SecKeychainRef keychainOrArray,
 132                                   CFTypeRef policies);
 133
 134 /*!
 135     @function
 136  */
 137 extern OSStatus
 138 SecCmsSignedDataAddCertList(SecCmsSignedDataRef sigd, CFArrayRef certlist);
 139
 140 /*!
 141     @function
 142     @abstract Add cert and its entire chain to the set of certs.
 143  */
 144 extern OSStatus
 145 SecCmsSignedDataAddCertChain(SecCmsSignedDataRef sigd, SecCertificateRef cert);
 146
 147 /*!
 148     @function
 149  */
 150 extern OSStatus
 151 SecCmsSignedDataAddCertificate(SecCmsSignedDataRef sigd, SecCertificateRef cert);
 152
 153 /*!
 154     @function
 155  */
 156 extern Boolean
 157 SecCmsSignedDataContainsCertsOrCrls(SecCmsSignedDataRef sigd);
 158
 159 /*!
 160     @function
 161     @abstract Retrieve the SignedData's certificate list.
 162  */
 163 extern CSSM_DATA_PTR *
 164 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd);
 165
 166 /*!
 167     @function
 168  */
 169 extern OSStatus
 170 SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd,
 171                                 SecCmsSignerInfoRef signerinfo);
 172
 173 /*!
 174     @function
 175  */
 176 extern OSStatus
 177 SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd,
 178                                 SECAlgorithmID **digestalgs,
 179                                 CSSM_DATA_PTR *digests);
 180
 181 /*!
 182     @function
 183     @abstract Create a certs-only SignedData.
 184     @param cert Base certificate that will be included
 185     @param include_chain If true, include the complete cert chain for cert.
 186     @discussion More certs and chains can be added via AddCertificate and AddCertChain.
 187     @result An error results in a return value of NULL and an error set.
 188  */
 189 extern SecCmsSignedDataRef
 190 SecCmsSignedDataCreateCertsOnly(SecCmsMessageRef cmsg, SecCertificateRef cert, Boolean include_chain);
 191
 192
 193 #if defined(__cplusplus)
 194 }
 195 #endif
 196
 197 #endif /* _SECURITY_SECCMSSIGNEDDATA_H_ */