libsecurity_smime/lib/SecCmsSignedData.h

   1 /*
   2  *  Copyright (c) 2004,2008,2010 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,2008,2010 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 #if defined(__cplusplus)
  42 extern "C" {
  43 #endif
  44
  45 /*!
  46     @function
  47     @abstract Create a new SecCmsSignedData object.
  48     @param cmsg Pointer to a SecCmsMessage in which this SecCmsSignedData
  49         should be created.
  50  */
  51 extern SecCmsSignedDataRef
  52 SecCmsSignedDataCreate(SecCmsMessageRef cmsg);
  53
  54 /*!
  55     @function
  56  */
  57 extern void
  58 SecCmsSignedDataDestroy(SecCmsSignedDataRef sigd);
  59
  60 /*!
  61     @function
  62     @abstract Retrieve the SignedData's signer list.
  63  */
  64 extern SecCmsSignerInfoRef *
  65 SecCmsSignedDataGetSignerInfos(SecCmsSignedDataRef sigd);
  66
  67 /*!
  68     @function
  69  */
  70 extern int
  71 SecCmsSignedDataSignerInfoCount(SecCmsSignedDataRef sigd);
  72
  73 /*!
  74     @function
  75  */
  76 extern SecCmsSignerInfoRef
  77 SecCmsSignedDataGetSignerInfo(SecCmsSignedDataRef sigd, int i);
  78
  79 /*!
  80     @function
  81     @abstract Retrieve the SignedData's digest algorithm list.
  82  */
  83 extern SECAlgorithmID **
  84 SecCmsSignedDataGetDigestAlgs(SecCmsSignedDataRef sigd);
  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     @function
 160     @abstract Retrieve the SignedData's certificate list.
 161  */
 162 extern SecAsn1Item * *
 163 SecCmsSignedDataGetCertificateList(SecCmsSignedDataRef sigd);
 164
 165 /*!
 166     @function
 167     @abstract Create a certs-only SignedData.
 168     @param cert Base certificate that will be included
 169     @param include_chain If true, include the complete cert chain for cert.
 170     @discussion More certs and chains can be added via AddCertificate and AddCertChain.
 171     @result An error results in a return value of NULL and an error set.
 172  */
 173 extern SecCmsSignedDataRef
 174 SecCmsSignedDataCreateCertsOnly(SecCmsMessageRef cmsg, SecCertificateRef cert, Boolean include_chain);
 175
 176 /*!
 177         @function
 178     @abstract Finalize the digests in digestContext and apply them to sigd.
 179     @param sigd A SecCmsSignedDataRef for which the digests have been calculated
 180     @param digestContext A digestContext created with SecCmsDigestContextStartMultiple.
 181         @result The digest will have been applied to sigd.  After this call completes sigd is ready to accept
 182         SecCmsSignedDataVerifySignerInfo() calls.  The caller should still destroy digestContext with a SecCmsDigestContextDestroy() call.
 183
 184  */
 185 extern OSStatus SecCmsSignedDataSetDigestContext(SecCmsSignedDataRef sigd,
 186                                                                                                  SecCmsDigestContextRef digestContext);
 187
 188 #if defined(__cplusplus)
 189 }
 190 #endif
 191
 192 #endif /* _SECURITY_SECCMSSIGNEDDATA_H_ */