1/* 2 * Copyright (c) 2003-2006,2008-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 * SecAsn1Coder.h: ANS1 encode/decode object. 24 * 25 * A SecAsn1Coder is capable of encoding and decoding both DER and BER data 26 * streams, based on caller-supplied templates which in turn are based 27 * upon ASN.1 specifications. A SecAsn1Coder allocates memory during encode 28 * and decode using a memory pool which is owned and managed by the SecAsn1Coder 29 * object, and which is freed when the SecAsn1Coder object os released. 30 */ 31 32#ifndef _SEC_ASN1_CODER_H_ 33#define _SEC_ASN1_CODER_H_ 34 35#include <sys/types.h> 36#include <Security/SecAsn1Types.h> 37#include <TargetConditionals.h> 38#include <Security/SecBase.h> /* error codes */ 39 40#ifdef __cplusplus 41extern "C" { 42#endif 43 44/* 45 * Opaque reference to a SecAsn1Coder object. 46 */ 47typedef struct SecAsn1Coder *SecAsn1CoderRef; 48 49/* 50 * Create/destroy SecAsn1Coder object. 51 */ 52OSStatus SecAsn1CoderCreate( 53 SecAsn1CoderRef *coder); 54 55OSStatus SecAsn1CoderRelease( 56 SecAsn1CoderRef coder); 57 58/* 59 * DER decode an untyped item per the specified template array. 60 * The result is allocated in this SecAsn1Coder's memory pool and 61 * is freed when this object is released. 62 * 63 * The templates argument points to a an array of SecAsn1Templates 64 * defining the object to be decoded; the end of the array is 65 * indicated by a SecAsn1Template with file kind equalling 0. 66 * 67 * The dest pointer is a template-specific struct allocated by the caller 68 * and must be zeroed by the caller. 69 * 70 * Returns errSecUnknownFormat on decode-specific error. 71 */ 72OSStatus SecAsn1Decode( 73 SecAsn1CoderRef coder, 74 const void *src, // DER-encoded source 75 size_t len, 76 const SecAsn1Template *templates, 77 void *dest); 78 79/* 80 * Convenience routine, decode from a SecAsn1Item. 81 */ 82OSStatus SecAsn1DecodeData( 83 SecAsn1CoderRef coder, 84 const SecAsn1Item *src, 85 const SecAsn1Template *templ, 86 void *dest); 87 88/* 89 * DER encode. The encoded data (in dest.Data) is allocated in this 90 * SecAsn1Coder's memory pool and is freed when this object is released. 91 * 92 * The src pointer is a template-specific struct. 93 * 94 * The templates argument points to a an array of SecAsn1Templates 95 * defining the object to be decoded; the end of the array is 96 * indicated by a SecAsn1Template with file kind equalling 0. 97 */ 98OSStatus SecAsn1EncodeItem( 99 SecAsn1CoderRef coder, 100 const void *src, 101 const SecAsn1Template *templates, 102 SecAsn1Item *dest); 103 104/* 105 * Some alloc-related methods which come in handy when using 106 * this object. All memory is allocated using this object's 107 * memory pool. Caller never has to free it. Used for 108 * temp allocs of memory which only needs a scope which is the 109 * same as this object. 110 * 111 * All except SecAsn1Malloc return a errSecAllocate in the highly 112 * unlikely event of a malloc failure. 113 * 114 * SecAsn1Malloc() returns a pointer to allocated memory, like 115 * malloc(). 116 */ 117void *SecAsn1Malloc( 118 SecAsn1CoderRef coder, 119 size_t len); 120 121/* Allocate item.Data, set item.Length */ 122OSStatus SecAsn1AllocItem( 123 SecAsn1CoderRef coder, 124 SecAsn1Item *item, 125 size_t len); 126 127/* Allocate and copy, various forms */ 128OSStatus SecAsn1AllocCopy( 129 SecAsn1CoderRef coder, 130 const void *src, /* memory copied from here */ 131 size_t len, /* length to allocate & copy */ 132 SecAsn1Item *dest); /* dest->Data allocated and copied to; 133 * dest->Length := len */ 134 135OSStatus SecAsn1AllocCopyItem( 136 SecAsn1CoderRef coder, 137 const SecAsn1Item *src, /* src->Length bytes allocated and copied from 138 * src->Data */ 139 SecAsn1Item *dest); /* dest->Data allocated and copied to; 140 * dest->Length := src->Length */ 141 142/* Compare two decoded OIDs. Returns true iff they are equivalent. */ 143bool SecAsn1OidCompare(const SecAsn1Oid *oid1, const SecAsn1Oid *oid2); 144 145#ifdef __cplusplus 146} 147#endif 148 149#endif /* _SEC_ASN1_CODER_H_ */ 150