certificates/ota_cert_tool/ios_ota_cert_tool/CommonBaseXX.h

   1 /*
   2  * Copyright (c) 2011,2013 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 #ifndef COMMON_BASE_XX_H
  26 #define COMMON_BASE_XX_H
  27
  28 #if !defined(COMMON_NUMERICS_H)
  29 #include <CommonNumerics/CommonNumerics.h>
  30 #endif
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36     /*!
  37      @enum       CNEncodings
  38      @abstract   Encodings available through CommonBaseXX().
  39
  40      @constant   kCNEncodingBase64              Base64 Encoding.
  41      @constant   kCNEncodingBase32              Base32 Encoding.
  42      @constant   kCNEncodingBase32HEX        Base32 Encoding -
  43      @constant   kCNEncodingBase32Recovery   Base32 Simplified Encoding.
  44      */
  45     enum {
  46         kCNEncodingBase64                       = 0x0001,
  47         kCNEncodingBase32                       = 0x0002,
  48         kCNEncodingBase32Recovery       = 0x0003,
  49         kCNEncodingBase32HEX            = 0x0004,
  50         kCNEncodingBase16               = 0x0005,
  51         kCNEncodingCustom               = 0xcafe
  52     };
  53     typedef uint32_t CNEncodings;
  54
  55     /*!
  56      @enum       kCNEncodingDirection
  57      @abstract   Determine whether the CNEncoderRef is to be used
  58      to encode or decode.
  59
  60      @constant   kCNEncode              Encode (base256 to baseXX)
  61      @constant   kCNDecode              Decode (baseXX to base256)
  62      */
  63
  64     enum {
  65         kCNEncode            = 0x0001,
  66         kCNDecode            = 0x0002,
  67     };
  68     typedef uint32_t CNEncodingDirection;
  69
  70     /*!
  71      @typedef    CNEncoderRef
  72      @abstract   Opaque reference to a CNEncoder object.
  73      */
  74
  75     typedef struct _CNEncoder *CNEncoderRef;
  76
  77     /*!
  78      @function   CNEncode
  79      @abstract   One-Shot baseXX encode or decode.
  80      @param      encoding selects one of the base encodings above.
  81      @param      direction   Designate the direction (encode or decode)
  82      @param      in          The bytes to be processed.
  83      @param             inLen           The number of bytes to be processed.
  84      @param             out                     The destination of the processed data.
  85      @param             outLen          The length of the processed data.
  86      @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.
  87
  88      */
  89
  90     CNStatus
  91     CNEncode(CNEncodings encoding,
  92              CNEncodingDirection direction,
  93              const void *in, const size_t inLen,
  94              void *out,  size_t *outLen)
  95     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);
  96
  97
  98
  99
 100     /*!
 101      @function   CCEncoderCreate
 102      @abstract   Create a base encoder context.
 103      @param      encoding    selects one of the base encodings above.
 104      @param      direction   Designate the direction (encode or decode) for this
 105      CNEncoderRef.
 106      @param      coderRef  A (required) pointer to the returned CNEncoderRef.
 107      */
 108
 109     CNStatus
 110     CNEncoderCreate(CNEncodings encoding,
 111                     CNEncodingDirection direction,
 112                     CNEncoderRef *encoderRef)  /* RETURNED */
 113     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);
 114
 115     /*!
 116      @function   CCEncoderCreateCustom
 117      @abstract   Create a custom base encoder context.
 118      @param      name        A name for this encoder (optional)
 119      @param      baseNum     The base of the encoding (16, 32, 64)
 120      @param      charMap     A string containing the characters to map an encoded
 121      byte to for output.
 122      @param      padding     The character to use for padding (usually '=')
 123      @param      direction   Designate the direction (encode or decode) for this
 124      CNEncoderRef.
 125      @param      coderRef  A (required) pointer to the returned CNEncoderRef.
 126      */
 127
 128     CNStatus
 129     CNEncoderCreateCustom(
 130                           const void *name,
 131                           const uint8_t baseNum,
 132                           const void *charMap,
 133                           const char padChar,
 134                           CNEncodingDirection direction,
 135                           CNEncoderRef *coderRef)  /* RETURNED */
 136     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);
 137
 138     /*!
 139      @function   CNEncoderRelease
 140      @abstract   Release a CNEncoderRef and associated objects.
 141      */
 142     CNStatus
 143     CNEncoderRelease(CNEncoderRef *coderRef)
 144     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_5_0);
 145
 146
 147     /*!
 148      @function   CNEncoderGetOutputLength
 149      @abstract   Determine the size required to hold the result of processing the
 150      input.
 151
 152      @param      coderRef    A CNEncoderRef obtained through CNEncoderCreate()
 153      or CNEncoderCreateCustom().
 154
 155      @param             inLen           The number of bytes to be processed.
 156
 157      @result     The length required for the encoding.  Zero (0) will be returned in
 158      the result of a NULL input pointer for the "in" parameter.
 159      */
 160
 161     size_t
 162     CNEncoderGetOutputLength(CNEncoderRef coderRef, const size_t inLen)
 163     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 164
 165     /*!
 166      @function   CNEncoderGetOutputLengthFromEncoding
 167      @abstract   Determine the size required to hold the result of processing the
 168      input given an encoding constant and direction and length.
 169
 170      @param      encoding    selects one of the base encodings above.
 171      @param      direction   Designate the direction (encode or decode) for this
 172      CNEncoderRef.
 173
 174      @param              inLen          The number of bytes to be processed.
 175
 176      @result     The length required for the encoding.  Zero (0) will be returned in
 177      the result of a NULL input pointer for the "in" parameter.
 178      */
 179
 180     size_t
 181     CNEncoderGetOutputLengthFromEncoding(CNEncodings encoding,
 182                                          CNEncodingDirection direction,
 183                                          const size_t inLen)
 184     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 185
 186     /*!
 187      @function   CNEncoderUpdate
 188      @abstract   Encode or decode the input string to or from the designated
 189      encoded format.
 190
 191      @param      coderRef  A CNEncoderRef obtained through CNEncoderCreate()
 192      or CNEncoderCreateCustom().
 193
 194      @param      in          The bytes to be processed.
 195
 196      @param             inLen           The number of bytes to be processed.
 197
 198      @param             out                     The destination of the processed data.
 199
 200      @param             outLen          The length of the processed data.
 201
 202      @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.
 203      */
 204
 205     CNStatus
 206     CNEncoderUpdate(CNEncoderRef coderRef, const void *in, const size_t inLen, void *out,
 207                     size_t *outLen)
 208     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 209
 210
 211     /*!
 212      @function   CNEncoderFinal
 213      @abstract   Complete coding for all available inputs, padding where necessary.
 214
 215      @param      coderRef  A CNEncoderRef obtained through CNEncoderCreate()
 216      or CNEncoderCreateCustom().
 217
 218      @param             out                     The destination of the processed data.
 219
 220      @param             outLen          The length of the processed data.
 221
 222      @result     kCCSuccess or one of kCCParamErr, kCCMemoryFailure.
 223      */
 224
 225     CNStatus
 226     CNEncoderFinal(CNEncoderRef coderRef, void *out, size_t *outLen)
 227     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 228
 229
 230     /*!
 231      @function   CNEncoderBlocksize
 232      @abstract   Get the number of bytes per block of input (base256) to output (base of encoder).
 233
 234      @param      encoding    The encoding format.
 235
 236      @param      inputSize   The number of raw bytes upon which an encoding operation should be performed
 237      if padding should not be added.  If CNEncode is called with this many bytes
 238      the resulting coded bytes will not need padding.
 239      @param      outputSize  The output block size in bytes for this encoding.
 240
 241      @result     kCCSuccess or kCCParamErr.
 242      */
 243
 244
 245
 246     CNStatus
 247     CNEncoderBlocksize(CNEncodings encoding, size_t *inputSize, size_t *outputSize)
 248     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 249
 250     /*!
 251      @function   CNEncoderBlocksizeFromRef
 252      @abstract   Get the number of bytes per block of input (base256) to output (base of encoder).
 253
 254      @param      encoderRef  A CNEncoderRef gotten from CNEncoderCreate or CNEncoderCreateCustom.
 255
 256      @param      inputSize   The number of raw bytes upon which an encoding operation should be performed
 257      if padding should not be added.  If CNEncode is called with this many bytes
 258      the resulting coded bytes will not need padding.
 259      @param      outputSize  The output block size in bytes for this encoding.
 260
 261      @result     kCCSuccess or kCCParamErr.
 262      */
 263
 264     CNStatus
 265     CNEncoderBlocksizeFromRef(CNEncoderRef encoderRef, size_t *inputSize, size_t *outputSize)
 266     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_6_0);
 267
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272
 273 #endif /* COMMON_BASE_XX_H */