CMS/CMSPrivate.h

   1 /*
   2  * Copyright (c) 2006-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  * CMSPrivate.h - access to low-level CMS objects used by CMSDecoder and CMSEncoder.
  26  */
  27 #ifndef _CMS_PRIVATE_H_
  28 #define _CMS_PRIVATE_H_
  29
  30 #include <Security/CMSEncoder.h>
  31 #include <Security/CMSDecoder.h>
  32 #include <Security/SecCmsEncoder.h>
  33 #include <Security/SecCmsDecoder.h>
  34 #include <Security/SecCmsMessage.h>
  35 #include <AvailabilityMacros.h>
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /***
  42  *** Private CMSEncoder routines
  43  ***/
  44
  45 /*
  46  * Obtain the SecCmsMessageRef associated with a CMSEncoderRef. Intended
  47  * to be called after (optionally) setting the encoder's various attributes
  48  * via CMSEncoderAddSigners(), CMSEncoderAddRecipients(), etc. and before
  49  * the first call to CMSEncoderUpdateContent(). The returned SecCmsMessageRef
  50  * will be initialized per the previously specified attributes; the caller
  51  * can manipulate the SecCmsMessageRef prior to proceeding with
  52  * CMSEncoderUpdateContent() calls.
  53  */
  54 OSStatus CMSEncoderGetCmsMessage(
  55         CMSEncoderRef           cmsEncoder,
  56         SecCmsMessageRef        *cmsMessage);           /* RETURNED */
  57
  58 /*
  59  * Optionally specify a SecCmsEncoderRef to use with a CMSEncoderRef.
  60  * If this is called, it must be called before the first call to
  61  * CMSEncoderUpdateContent(). The CMSEncoderRef takes ownership of the
  62  * incoming SecCmsEncoderRef.
  63  */
  64 OSStatus CMSEncoderSetEncoder(
  65         CMSEncoderRef           cmsEncoder,
  66         SecCmsEncoderRef        encoder);
  67
  68 /*
  69  * Obtain the SecCmsEncoderRef associated with a CMSEncoderRef.
  70  * Returns a NULL SecCmsEncoderRef if neither CMSEncoderSetEncoder nor
  71  * CMSEncoderUpdateContent() has been called.
  72  * The CMSEncoderRef retains ownership of the SecCmsEncoderRef.
  73  */
  74 OSStatus CMSEncoderGetEncoder(
  75         CMSEncoderRef           cmsEncoder,
  76         SecCmsEncoderRef        *encoder);                      /* RETURNED */
  77
  78 /*
  79  * Set the signing time for a CMSEncoder.
  80  * This is only used if the kCMSAttrSigningTime attribute is included.
  81  */
  82 OSStatus CMSEncoderSetSigningTime(
  83         CMSEncoderRef           cmsEncoder,
  84         CFAbsoluteTime          time);
  85
  86 /*
  87  * Set the hash agility attribute for a CMSEncoder.
  88  * This is only used if the kCMSAttrAppleCodesigningHashAgility attribute
  89  * is included.
  90  */
  91 OSStatus CMSEncoderSetAppleCodesigningHashAgility(
  92         CMSEncoderRef   cmsEncoder,
  93         CFDataRef       hashAgilityAttrValue);
  94
  95 /*
  96  * Set the hash agility attribute for a CMSEncoder.
  97  * This is only used if the kCMSAttrAppleCodesigningHashAgilityV2 attribute
  98  * is included. V2 encodes the hash agility values using DER.
  99  * The dictionary should have CFNumberRef keys, corresponding to SECOidTags
 100  * (from SecCmsBase.h) for digest algorithms, and CFDataRef values,
 101  * corresponding to the digest value for that digest algorithm.
 102  */
 103 OSStatus CMSEncoderSetAppleCodesigningHashAgilityV2(
 104     CMSEncoderRef       cmsEncoder,
 105     CFDictionaryRef     hashAgilityV2AttrValues);
 106
 107 /*
 108  * Set the expiration time for a CMSEncoder.
 109  * This is only used if the kCMSAttrAppleExpirationTime attribute is included.
 110  */
 111 OSStatus CMSEncoderSetAppleExpirationTime(
 112                                           CMSEncoderRef        cmsEncoder,
 113                                           CFAbsoluteTime        time);
 114
 115
 116 void
 117 CmsMessageSetTSAContext(CMSEncoderRef cmsEncoder, CFTypeRef tsaContext)
 118     API_AVAILABLE(macos(10.8)) API_UNAVAILABLE(ios, tvos, watchos, bridgeos, macCatalyst);
 119
 120 /***
 121  *** Private CMSDecoder routines
 122  ***/
 123
 124 /*
 125  * Obtain the SecCmsMessageRef associated with a CMSDecoderRef. Intended
 126  * to be called after decoding the message (i.e., after
 127  * CMSDecoderFinalizeMessage() to gain finer access to the contents of the
 128  * SecCmsMessageRef than is otherwise available via the CMSDecoder interface.
 129  * Returns a NULL SecCmsMessageRef if CMSDecoderFinalizeMessage() has not been
 130  * called.
 131  *
 132  * The CMSDecoder retains ownership of the returned SecCmsMessageRef.
 133  */
 134 OSStatus CMSDecoderGetCmsMessage(
 135         CMSDecoderRef           cmsDecoder,
 136         SecCmsMessageRef        *cmsMessage);           /* RETURNED */
 137
 138
 139 /*
 140  * Optionally specify a SecCmsDecoderRef to use with a CMSDecoderRef.
 141  * If this is called, it must be called before the first call to
 142  * CMSDecoderUpdateMessage(). The CMSDecoderRef takes ownership of the
 143  * incoming SecCmsDecoderRef.
 144  */
 145 OSStatus CMSDecoderSetDecoder(
 146         CMSDecoderRef           cmsDecoder,
 147         SecCmsDecoderRef        decoder);
 148
 149 /*
 150  * Obtain the SecCmsDecoderRef associated with a CMSDecoderRef.
 151  * Returns a NULL SecCmsDecoderRef if neither CMSDecoderSetDecoder() nor
 152  * CMSDecoderUpdateMessage() has been called.
 153  * The CMSDecoderRef retains ownership of the SecCmsDecoderRef.
 154  */
 155 OSStatus CMSDecoderGetDecoder(
 156         CMSDecoderRef           cmsDecoder,
 157         SecCmsDecoderRef        *decoder);                      /* RETURNED */
 158
 159 /*
 160  * Obtain the Hash Agility attribute value of signer 'signerIndex'
 161  * of a CMS message, if present.
 162  *
 163  * Returns errSecParam if the CMS message was not signed or if signerIndex
 164  * is greater than the number of signers of the message minus one.
 165  *
 166  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 167  */
 168 OSStatus CMSDecoderCopySignerAppleCodesigningHashAgility(
 169     CMSDecoderRef               cmsDecoder,
 170     size_t                              signerIndex,            /* usually 0 */
 171     CFDataRef  CF_RETURNS_RETAINED *hashAgilityAttrValue)               /* RETURNED */
 172     API_AVAILABLE(macos(10.12.4), ios(11.0));
 173
 174 /*
 175  * Obtain the Hash Agility v2 attribute value of signer 'signerIndex'
 176  * of a CMS message, if present. V2 encodes the hash agility values using DER.
 177  *
 178  * Returns errSecParam if the CMS message was not signed or if signerIndex
 179  * is greater than the number of signers of the message minus one.
 180  *
 181  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 182  */
 183 OSStatus CMSDecoderCopySignerAppleCodesigningHashAgilityV2(
 184     CMSDecoderRef                           cmsDecoder,
 185     size_t                                  signerIndex,            /* usually 0 */
 186     CFDictionaryRef CF_RETURNS_RETAINED *   hashAgilityAttrValues)   /* RETURNED */
 187     API_AVAILABLE(macos(10.13.4), ios(11.3));
 188
 189 /*
 190  * Obtain the expiration time of signer 'signerIndex' of a CMS message, if
 191  * present. This is part of the signed attributes of the message.
 192  *
 193  * Returns errSecParam if the CMS message was not signed or if signerIndex
 194  * is greater than the number of signers of the message minus one.
 195  *
 196  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 197  */
 198 OSStatus CMSDecoderCopySignerAppleExpirationTime(
 199     CMSDecoderRef      cmsDecoder,
 200     size_t             signerIndex,
 201     CFAbsoluteTime     *expirationTime)            /* RETURNED */
 202     API_AVAILABLE(macos(10.14), ios(12.0));
 203
 204 #ifdef __cplusplus
 205 }
 206 #endif
 207
 208 #endif  /* _CMS_PRIVATE_H_ */
 209