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 void
  96 CmsMessageSetTSAContext(CMSEncoderRef cmsEncoder, CFTypeRef tsaContext);
  97
  98 /***
  99  *** Private CMSDecoder routines
 100  ***/
 101
 102 /*
 103  * Obtain the SecCmsMessageRef associated with a CMSDecoderRef. Intended
 104  * to be called after decoding the message (i.e., after
 105  * CMSDecoderFinalizeMessage() to gain finer access to the contents of the
 106  * SecCmsMessageRef than is otherwise available via the CMSDecoder interface.
 107  * Returns a NULL SecCmsMessageRef if CMSDecoderFinalizeMessage() has not been
 108  * called.
 109  *
 110  * The CMSDecoder retains ownership of the returned SecCmsMessageRef.
 111  */
 112 OSStatus CMSDecoderGetCmsMessage(
 113         CMSDecoderRef           cmsDecoder,
 114         SecCmsMessageRef        *cmsMessage);           /* RETURNED */
 115
 116
 117 /*
 118  * Optionally specify a SecCmsDecoderRef to use with a CMSDecoderRef.
 119  * If this is called, it must be called before the first call to
 120  * CMSDecoderUpdateMessage(). The CMSDecoderRef takes ownership of the
 121  * incoming SecCmsDecoderRef.
 122  */
 123 OSStatus CMSDecoderSetDecoder(
 124         CMSDecoderRef           cmsDecoder,
 125         SecCmsDecoderRef        decoder);
 126
 127 /*
 128  * Obtain the SecCmsDecoderRef associated with a CMSDecoderRef.
 129  * Returns a NULL SecCmsDecoderRef if neither CMSDecoderSetDecoder() nor
 130  * CMSDecoderUpdateMessage() has been called.
 131  * The CMSDecoderRef retains ownership of the SecCmsDecoderRef.
 132  */
 133 OSStatus CMSDecoderGetDecoder(
 134         CMSDecoderRef           cmsDecoder,
 135         SecCmsDecoderRef        *decoder);                      /* RETURNED */
 136
 137 /*
 138  * Obtain the Hash Agility attribute value of signer 'signerIndex'
 139  * of a CMS message, if present.
 140  *
 141  * Returns errSecParam if the CMS message was not signed or if signerIndex
 142  * is greater than the number of signers of the message minus one.
 143  *
 144  * This cannot be called until after CMSDecoderFinalizeMessage() is called.
 145  */
 146 OSStatus CMSDecoderCopySignerAppleCodesigningHashAgility(
 147     CMSDecoderRef               cmsDecoder,
 148     size_t                              signerIndex,            /* usually 0 */
 149     CFDataRef  CF_RETURNS_RETAINED *hashAgilityAttrValue);              /* RETURNED */
 150
 151 #ifdef __cplusplus
 152 }
 153 #endif
 154
 155 #endif  /* _CMS_PRIVATE_H_ */
 156