OSX/libsecurity_asn1/lib/SecAsn1Types.h

   1 /*
   2  * The contents of this file are subject to the Mozilla Public
   3  * License Version 1.1 (the "License"); you may not use this file
   4  * except in compliance with the License. You may obtain a copy of
   5  * the License at http://www.mozilla.org/MPL/
   6  *
   7  * Software distributed under the License is distributed on an "AS
   8  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
   9  * implied. See the License for the specific language governing
  10  * rights and limitations under the License.
  11  *
  12  * The Original Code is the Netscape security libraries.
  13  *
  14  * The Initial Developer of the Original Code is Netscape
  15  * Communications Corporation.  Portions created by Netscape are
  16  * Copyright (C) 1994-2000 Netscape Communications Corporation.  All
  17  * Rights Reserved.
  18  *
  19  * Contributor(s):
  20  *
  21  * Alternatively, the contents of this file may be used under the
  22  * terms of the GNU General Public License Version 2 or later (the
  23  * "GPL"), in which case the provisions of the GPL are applicable
  24  * instead of those above.  If you wish to allow use of your
  25  * version of this file only under the terms of the GPL and not to
  26  * allow others to use your version of this file under the MPL,
  27  * indicate your decision by deleting the provisions above and
  28  * replace them with the notice and other provisions required by
  29  * the GPL.  If you do not delete the provisions above, a recipient
  30  * may use your version of this file under either the MPL or the
  31  * GPL.
  32  */
  33
  34 /*
  35  * Types for encoding/decoding of ASN.1 using BER/DER (Basic/Distinguished
  36  * Encoding Rules).
  37  */
  38
  39 #ifndef _SEC_ASN1_TYPES_H_
  40 #define _SEC_ASN1_TYPES_H_
  41
  42 #include <CoreFoundation/CFBase.h>              /* Boolean */
  43 #include <sys/types.h>
  44 #include <stdint.h>
  45
  46 #include <TargetConditionals.h>
  47 #if TARGET_OS_EMBEDDED || TARGET_IPHONE_SIMULATOR
  48 /* @@@ We need something that tells us which platform we are building
  49    for that let's us distinguish if we are doing an emulator build. */
  50
  51 typedef struct {
  52     size_t Length;
  53     uint8_t * __nullable Data;
  54 } SecAsn1Item, SecAsn1Oid;
  55
  56 typedef struct {
  57     SecAsn1Oid algorithm;
  58     SecAsn1Item parameters;
  59 } SecAsn1AlgId;
  60
  61 typedef struct {
  62     SecAsn1AlgId algorithm;
  63     SecAsn1Item subjectPublicKey;
  64 } SecAsn1PubKeyInfo;
  65
  66 #else
  67 #include <Security/cssmtype.h>
  68 #include <Security/x509defs.h>
  69
  70 typedef CSSM_DATA SecAsn1Item;
  71 typedef CSSM_OID SecAsn1Oid;
  72 typedef CSSM_X509_ALGORITHM_IDENTIFIER SecAsn1AlgId;
  73 typedef CSSM_X509_SUBJECT_PUBLIC_KEY_INFO SecAsn1PubKeyInfo;
  74
  75 #endif
  76
  77 CF_ASSUME_NONNULL_BEGIN
  78
  79 /*
  80  * An array of these structures defines a BER/DER encoding for an object.
  81  *
  82  * The array usually starts with a dummy entry whose kind is SEC_ASN1_SEQUENCE;
  83  * such an array is terminated with an entry where kind == 0.  (An array
  84  * which consists of a single component does not require a second dummy
  85  * entry -- the array is only searched as long as previous component(s)
  86  * instruct it.)
  87  */
  88 typedef struct SecAsn1Template_struct {
  89     /*
  90      * Kind of item being decoded/encoded, including tags and modifiers.
  91      */
  92     uint32_t kind;
  93
  94     /*
  95      * This value is the offset from the base of the structure (i.e., the
  96          * (void *) passed as 'src' to SecAsn1EncodeItem, or the 'dst' argument
  97          * passed to SecAsn1CoderRef()) to the field that holds the value being
  98          * decoded/encoded.
  99      */
 100     uint32_t offset;
 101
 102     /*
 103      * When kind suggests it (e.g., SEC_ASN1_POINTER, SEC_ASN1_GROUP,
 104          * SEC_ASN1_INLINE, or a component that is *not* a SEC_ASN1_UNIVERSAL),
 105          * this points to a sub-template for nested encoding/decoding.
 106      * OR, iff SEC_ASN1_DYNAMIC is set, then this is a pointer to a pointer
 107      * to a function which will return the appropriate template when called
 108      * at runtime.  NOTE! that explicit level of indirection, which is
 109      * necessary because ANSI does not allow you to store a function
 110      * pointer directly as a "void *" so we must store it separately and
 111      * dereference it to get at the function pointer itself.
 112      */
 113     const void *sub;
 114
 115     /*
 116      * In the first element of a template array, the value is the size
 117      * of the structure to allocate when this template is being referenced
 118      * by another template via SEC_ASN1_POINTER or SEC_ASN1_GROUP.
 119      * In all other cases, the value is ignored.
 120      */
 121     uint32_t size;
 122 } SecAsn1Template;
 123
 124
 125 /*
 126  * BER/DER values for ASN.1 identifier octets.
 127  */
 128 #define SEC_ASN1_TAG_MASK               0xff
 129
 130 /*
 131  * BER/DER universal type tag numbers.
 132  */
 133 #define SEC_ASN1_TAGNUM_MASK            0x1f
 134 #define SEC_ASN1_BOOLEAN                        0x01
 135 #define SEC_ASN1_INTEGER                        0x02
 136 #define SEC_ASN1_BIT_STRING                     0x03
 137 #define SEC_ASN1_OCTET_STRING           0x04
 138 #define SEC_ASN1_NULL                           0x05
 139 #define SEC_ASN1_OBJECT_ID                      0x06
 140 #define SEC_ASN1_OBJECT_DESCRIPTOR  0x07
 141 /* External type and instance-of type   0x08 */
 142 #define SEC_ASN1_REAL               0x09
 143 #define SEC_ASN1_ENUMERATED                     0x0a
 144 #define SEC_ASN1_EMBEDDED_PDV       0x0b
 145 #define SEC_ASN1_UTF8_STRING            0x0c
 146 /* not used                         0x0d */
 147 /* not used                         0x0e */
 148 /* not used                         0x0f */
 149 #define SEC_ASN1_SEQUENCE                       0x10
 150 #define SEC_ASN1_SET                            0x11
 151 #define SEC_ASN1_NUMERIC_STRING     0x12
 152 #define SEC_ASN1_PRINTABLE_STRING       0x13
 153 #define SEC_ASN1_T61_STRING                     0x14
 154 #define SEC_ASN1_VIDEOTEX_STRING        0x15
 155 #define SEC_ASN1_IA5_STRING                     0x16
 156 #define SEC_ASN1_UTC_TIME                       0x17
 157 #define SEC_ASN1_GENERALIZED_TIME       0x18
 158 #define SEC_ASN1_GRAPHIC_STRING         0x19
 159 #define SEC_ASN1_VISIBLE_STRING         0x1a
 160 #define SEC_ASN1_GENERAL_STRING         0x1b
 161 #define SEC_ASN1_UNIVERSAL_STRING       0x1c
 162 /* not used                                                     0x1d */
 163 #define SEC_ASN1_BMP_STRING                     0x1e
 164 #define SEC_ASN1_HIGH_TAG_NUMBER        0x1f
 165 #define SEC_ASN1_TELETEX_STRING SEC_ASN1_T61_STRING
 166
 167 /*
 168  * Modifiers to type tags.  These are also specified by a/the
 169  * standard, and must not be changed.
 170  */
 171 #define SEC_ASN1_METHOD_MASK            0x20
 172 #define SEC_ASN1_PRIMITIVE                      0x00
 173 #define SEC_ASN1_CONSTRUCTED            0x20
 174
 175 #define SEC_ASN1_CLASS_MASK                     0xc0
 176 #define SEC_ASN1_UNIVERSAL                      0x00
 177 #define SEC_ASN1_APPLICATION            0x40
 178 #define SEC_ASN1_CONTEXT_SPECIFIC       0x80
 179 #define SEC_ASN1_PRIVATE                        0xc0
 180
 181 /*
 182  * Our additions, used for templates.
 183  * These are not defined by any standard; the values are used internally only.
 184  * Just be careful to keep them out of the low 8 bits.
 185  */
 186 #define SEC_ASN1_OPTIONAL       0x00100
 187 #define SEC_ASN1_EXPLICIT       0x00200
 188 #define SEC_ASN1_ANY            0x00400
 189 #define SEC_ASN1_INLINE         0x00800
 190 #define SEC_ASN1_POINTER        0x01000
 191 #define SEC_ASN1_GROUP          0x02000 /* with SET or SEQUENCE means
 192                                                                          * SET OF or SEQUENCE OF */
 193 #define SEC_ASN1_DYNAMIC        0x04000 /* subtemplate is found by calling
 194                                                                          * a function at runtime */
 195 #define SEC_ASN1_SKIP           0x08000 /* skip a field; only for decoding */
 196 #define SEC_ASN1_INNER          0x10000 /* with ANY means capture the
 197                                                                          * contents only (not the id, len,
 198                                                                          * or eoc); only for decoding */
 199 #define SEC_ASN1_SAVE           0x20000 /* stash away the encoded bytes first;
 200                                                                          * only for decoding */
 201 #define SEC_ASN1_SKIP_REST      0x80000 /* skip all following fields;
 202                                                                          * only for decoding */
 203 #define SEC_ASN1_CHOICE     0x100000 /* pick one from a template */
 204
 205 /*
 206  * Indicate that a type SEC_ASN1_INTEGER is actually signed.
 207  * The default is unsigned, which causes a leading zero to be
 208  * encoded if the MS bit of the source data is 1.
 209  */
 210 #define SEC_ASN1_SIGNED_INT     0X800000
 211
 212 /* Shorthand/Aliases */
 213 #define SEC_ASN1_SEQUENCE_OF    (SEC_ASN1_GROUP | SEC_ASN1_SEQUENCE)
 214 #define SEC_ASN1_SET_OF                 (SEC_ASN1_GROUP | SEC_ASN1_SET)
 215 #define SEC_ASN1_ANY_CONTENTS   (SEC_ASN1_ANY | SEC_ASN1_INNER)
 216
 217 /*
 218  * Function used for SEC_ASN1_DYNAMIC.
 219  * "arg"  is a pointer to the top-level structure being encoded or
 220  *        decoded.
 221  *
 222  * "enc"  when true, means that we are encoding (false means decoding)
 223  *
 224  * "buf"  For decode only; points to the start of the decoded data for
 225  *        the current template. Callee can use the tag at this location
 226  *        to infer the returned template. Not used on encode.
 227  *
 228  * "len"  For decode only; the length of buf.
 229  *
 230  * "Dest" points to the template-specific item being decoded to
 231  *        or encoded from. (This is as opposed to arg, which
 232  *        points to the start of the struct associated with the
 233  *        current array of templates).
 234  */
 235
 236 typedef const SecAsn1Template * SecAsn1TemplateChooser(
 237         void *arg,
 238         Boolean enc,
 239         const char *buf,
 240         size_t len,
 241         void *dest);
 242
 243 typedef SecAsn1TemplateChooser * SecAsn1TemplateChooserPtr;
 244
 245 CF_ASSUME_NONNULL_END
 246
 247 #endif /* _SEC_ASN1_TYPES_H_ */