OSX/libsecurity_cms/lib/CMSPrivate.h

   1 /*
   2  * Copyright (c) 2006,2011-2012,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  * 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 void
 116 CmsMessageSetTSAContext(CMSEncoderRef cmsEncoder, CFTypeRef tsaContext);
 117
 118 /***
 119  *** Private CMSDecoder routines
 120  ***/
 121
 122 /*
 123  * Obtain the SecCmsMessageRef associated with a CMSDecoderRef. Intended
 124  * to be called after decoding the message (i.e., after
 125  * CMSDecoderFinalizeMessage() to gain finer access to the contents of the
 126  * SecCmsMessageRef than is otherwise available via the CMSDecoder interface.
 127  * Returns a NULL SecCmsMessageRef if CMSDecoderFinalizeMessage() has not been
 128  * called.
 129  *
 130  * The CMSDecoder retains ownership of the returned SecCmsMessageRef.
 131  */
 132 OSStatus CMSDecoderGetCmsMessage(
 133         CMSDecoderRef           cmsDecoder,
 134         SecCmsMessageRef        *cmsMessage);           /* RETURNED */
 135
 136
 137 /*
 138  * Optionally specify a SecCmsDecoderRef to use with a CMSDecoderRef.
 139  * If this is called, it must be called before the first call to
 140  * CMSDecoderUpdateMessage(). The CMSDecoderRef takes ownership of the
 141  * incoming SecCmsDecoderRef.
 142  */
 143 OSStatus CMSDecoderSetDecoder(
 144         CMSDecoderRef           cmsDecoder,
 145         SecCmsDecoderRef        decoder);
 146
 147 /*
 148  * Obtain the SecCmsDecoderRef associated with a CMSDecoderRef.
 149  * Returns a NULL SecCmsDecoderRef if neither CMSDecoderSetDecoder() nor
 150  * CMSDecoderUpdateMessage() has been called.
 151  * The CMSDecoderRef retains ownership of the SecCmsDecoderRef.
 152  */
 153 OSStatus CMSDecoderGetDecoder(
 154         CMSDecoderRef           cmsDecoder,
 155         SecCmsDecoderRef        *decoder);                      /* RETURNED */
 156
 157 /*
 158  * Obtain the Hash Agility attribute value of signer 'signerIndex'
 159  * of a CMS message, if present.
 160  *
 161  * Returns errSecParam if the CMS message was not signed or if signerIndex
 162  * is greater than the number of signers of the message minus one.
 163  *
 164  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 165  */
 166 OSStatus CMSDecoderCopySignerAppleCodesigningHashAgility(
 167     CMSDecoderRef               cmsDecoder,
 168     size_t                              signerIndex,            /* usually 0 */
 169     CFDataRef  CF_RETURNS_RETAINED *hashAgilityAttrValue);              /* RETURNED */
 170
 171 /*
 172  * Obtain the Hash Agility v2 attribute value of signer 'signerIndex'
 173  * of a CMS message, if present. V2 encodes the hash agility values using DER.
 174  *
 175  * Returns errSecParam if the CMS message was not signed or if signerIndex
 176  * is greater than the number of signers of the message minus one.
 177  *
 178  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 179  */
 180 OSStatus CMSDecoderCopySignerAppleCodesigningHashAgilityV2(
 181     CMSDecoderRef                           cmsDecoder,
 182     size_t                                  signerIndex,            /* usually 0 */
 183     CFDictionaryRef CF_RETURNS_RETAINED *   hashAgilityAttrValues);   /* RETURNED */
 184
 185 /*
 186  * Obtain the expiration time of signer 'signerIndex' of a CMS message, if
 187  * present. This is part of the signed attributes of the message.
 188  *
 189  * Returns errSecParam if the CMS message was not signed or if signerIndex
 190  * is greater than the number of signers of the message minus one.
 191  *
 192  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 193  */
 194 OSStatus CMSDecoderCopySignerAppleExpirationTime(
 195                                                  CMSDecoderRef      cmsDecoder,
 196                                                  size_t             signerIndex,
 197                                                  CFAbsoluteTime     *expirationTime);            /* RETURNED */
 198
 199 #ifdef __cplusplus
 200 }
 201 #endif
 202
 203 #endif  /* _CMS_PRIVATE_H_ */
 204