1/*
2 * Copyright (c) 2003-2006,2008-2010 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