lib/silcasn1/silcasn1.h

   1 /*
   2
   3   silcasn1.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcasn1/ASN.1 Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Efficient Abstract Syntax Notation One (ASN.1) implementation.  This
  25  * interface provides simple and efficient ASN.1 encoder and decoder.
  26  * The encoder directly encodes BER encoded data blocks from variable
  27  * argument list of ASN.1 types.  Multiple trees can be encoded at once
  28  * and multiple nodes can be encoded into the tree at once.  By default
  29  * encoder does not allocate any memory during encoding but a pre-allocated
  30  * SilcStack is used as memory.
  31  *
  32  * The decoder directly decodes BER encoded data blocks into the correct
  33  * types dictated by the variable argument list of ASN.1 types.  By
  34  * default decoder does not allocate any memory during decoding but a
  35  * pre-allocated SilcStack is used as memory.
  36  *
  37  * The encoding and decoding interface is simple.  silc_asn1_encode is used
  38  * to encode and silc_asn1_decode to decode.  The actual ASN.1 is defined
  39  * as variable argument list to the function.  Various macros can be used
  40  * to encode and decode different ASN.1 types.  All types may also be used
  41  * to encode and decode with various options (such as implicit and explicit
  42  * tagging and defining specific class option).
  43  *
  44  * The implementation supports all the common ASN.1 types.
  45  *
  46  * References: ITU-T X.680 - X.693
  47  * http://www.itu.int/ITU-T/studygroups/com17/languages/
  48  *
  49  ***/
  50
  51 #ifndef SILCASN1_H
  52 #define SILCASN1_H
  53
  54 /****s* silcasn1/SilcASN1API/SilcAsn1
  55  *
  56  * NAME
  57  *
  58  *    typedef struct SilcAsn1Object *SilcAsn1;
  59  *
  60  * DESCRIPTION
  61  *
  62  *    This context is the actual ASN.1 encoder/decoder and is allocated
  63  *    by silc_asn1_alloc and given as argument to all silc_asn1_*
  64  *    functions.  It is freed by the silc_asn1_free function.  It is
  65  *    also possible to use pre-allocated ASN.1 context by using the
  66  *    SilcAsn1Struct instead of SilcAsn1.
  67  *
  68  ***/
  69 typedef struct SilcAsn1Object *SilcAsn1;
  70
  71 /****s* silcasn1/SilcASN1API/SilcAsn1Struct
  72  *
  73  * NAME
  74  *
  75  *    typedef struct SilcAsn1Object SilcAsn1Struct;
  76  *
  77  * DESCRIPTION
  78  *
  79  *    This context is the actual ASN.1 encoder/decoder and can be
  80  *    used as pre-allocated ASN.1 context instead of SilcAsn1 context.
  81  *    This context is initialized with silc_asn1_init and uninitialized
  82  *    with silc_asn1_uninit.
  83  *
  84  ***/
  85 typedef struct SilcAsn1Object SilcAsn1Struct;
  86
  87 /****d* silcasn1/SilcASN1API/SilcAsn1Options
  88  *
  89  * NAME
  90  *
  91  *    typedef enum { ... } SilcAsn1Options;
  92  *
  93  * DESCRIPTION
  94  *
  95  *    Options for ASN.1 encoder and decoder.  The ASN.1 options can be
  96  *    given to the SILC_ASN1_*_T macros and/or SILC_ASN1_OPTS macro.
  97  *
  98  * NOTES
  99  *
 100  *    The SILC_ASN1_ALLOC and SILC_ASN1_ACCUMUL flags can be given only
 101  *    with SILC_ASN1_OPTS macro.  Other options can be given with various
 102  *    SILC_ASN1_*_T macros.
 103  *
 104  * EXAMPLE
 105  *
 106  *    // Encodes boolean value with explicit tag and private class, and
 107  *    // the result is allocated into `dest'.
 108  *    silc_asn1_encode(asn1, &dest,
 109  *                     SILC_ASN1_OPTS(SILC_ASN1_ALLOC),
 110  *                     SILC_ASN1_BOOLEAN_T(SILC_ASN1_PRIVATE |
 111  *                                         SILC_ASN1_EXPLICIT, 100, boolval),
 112  *                     SILC_ASN1_END);
 113  *
 114  *    // Decode optional value, with SILC_ASN1_OPTIONAL the type must be
 115  *    // a pointer so that NULL can be returned if the type is not present.
 116  *    SilcBool *val;
 117  *
 118  *    silc_asn1_decode(asn1, src,
 119  *                     SILC_ASN1_OPTS(SILC_ASN1_OPTIONAL),
 120  *                     SILC_ASN1_BOOLEAN(&val),
 121  *                     SILC_ASN1_END);
 122  *
 123  *    // If val == NULL, the optional value was not present
 124  *    if (val == NULL)
 125  *      error;
 126  *
 127  * SOURCE
 128  */
 129 typedef enum {
 130   /* Default. If only this is set then defaults are implied. */
 131   SILC_ASN1_DEFAULT      = 0x0000,
 132
 133   /* Class options.  User does not need to set these unless specificly
 134      wanted to do so.  If SILC_ASN1_DEFAULT is set the SILC_ASN1_CONTEXT is
 135      implied if any of the tag options are set.  Otherwise SILC_ASN1_UNIVERSAL
 136      is implied. Only one of these can bet set at once. */
 137   SILC_ASN1_UNIVERSAL    = 0x0001,       /* Universal class (default) */
 138   SILC_ASN1_APP          = 0x0002,       /* Application specific class */
 139   SILC_ASN1_CONTEXT      = 0x0003,       /* Context specific class */
 140   SILC_ASN1_PRIVATE      = 0x0004,       /* Private class */
 141
 142   /* Tag options (bitmask) */
 143   SILC_ASN1_IMPLICIT     = 0x0010,       /* Tag is implicit (default) */
 144   SILC_ASN1_EXPLICIT     = 0x0020,       /* Tag is explicit */
 145   SILC_ASN1_DEFINITE     = 0x0040,       /* Length is definite (default) */
 146   SILC_ASN1_INDEFINITE   = 0x0080,       /* Length is indefinite */
 147
 148   /* Decoding options (bitmask) */
 149   SILC_ASN1_OPTIONAL     = 0x0100,       /* Zero or more may be found.  The
 150                                             argument must be pointer to the
 151                                             type pointer so that NULL can be
 152                                             returned if type is not found. */
 153
 154   /* ASN.1 encoder/decoder options (bitmask).  These can be given
 155      only with SILC_ASN1_OPTS macro at the start of encoding/decoding. */
 156   SILC_ASN1_ALLOC        = 0x0400,       /* Dynamically allocate results,
 157                                             or if stack was given to
 158                                             silc_asn1_alloc, they are allocated
 159                                             and consumed from the stack. */
 160   SILC_ASN1_ACCUMUL      = 0x0800,       /* Accumulate memory for results,
 161                                             next call to silc_asn1_decode
 162                                             will not cancel old results. */
 163 } SilcAsn1Options;
 164 /***/
 165
 166 /****d* silcasn1/SilcASN1API/SilcAsn1Tag
 167  *
 168  * NAME
 169  *
 170  *    typedef enum { ... } SilcAsn1Tag;
 171  *
 172  * DESCRIPTION
 173  *
 174  *    Universal ASN.1 tags.  Usually these tags are given automatically
 175  *    to the silc_asn1_encode and silc_asn1_decode by using the various
 176  *    macros (such as SILC_ASN1_BOOLEAN).  Some macros may take the tag
 177  *    as additional argument.
 178  *
 179  * SOURCE
 180  */
 181 typedef enum {
 182   SILC_ASN1_TAG_BOOLEAN               = 1,  /* SILC_ASN1_BOOLEAN */
 183   SILC_ASN1_TAG_INTEGER               = 2,  /* SILC_ASN1_INT */
 184   SILC_ASN1_TAG_BIT_STRING            = 3,  /* SILC_ASN1_BIT_STRING */
 185   SILC_ASN1_TAG_OCTET_STRING          = 4,  /* SILC_ASN1_OCTET_STRING */
 186   SILC_ASN1_TAG_NULL                  = 5,  /* SILC_ASN1_NULL */
 187   SILC_ASN1_TAG_OID                   = 6,  /* SILC_ASN1_OID */
 188   SILC_ASN1_TAG_ODE                   = 7,  /* not supported */
 189   SILC_ASN1_TAG_ETI                   = 8,  /* not supported */
 190   SILC_ASN1_TAG_REAL                  = 9,  /* not supported */
 191   SILC_ASN1_TAG_ENUM                  = 10, /* SILC_ASN1_ENUM */
 192   SILC_ASN1_TAG_EMBEDDED              = 11, /* not supported */
 193   SILC_ASN1_TAG_UTF8_STRING           = 12, /* SILC_ASN1_UTF8_STRING */
 194   SILC_ASN1_TAG_ROI                   = 13, /* not supported */
 195   SILC_ASN1_TAG_SEQUENCE              = 16, /* SILC_ASN1_SEQUENCE */
 196   SILC_ASN1_TAG_SET                   = 17, /* SILC_ASN1_SET */
 197   SILC_ASN1_TAG_NUMERIC_STRING        = 18, /* SILC_ASN1_NUMERIC_STRING */
 198   SILC_ASN1_TAG_PRINTABLE_STRING      = 19, /* SILC_ASN1_PRINTABLE_STRING */
 199   SILC_ASN1_TAG_TELETEX_STRING        = 20, /* SILC_ASN1_TELETEX_STRING */
 200   SILC_ASN1_TAG_VIDEOTEX_STRING       = 21, /* not supported */
 201   SILC_ASN1_TAG_IA5_STRING            = 22, /* SILC_ASN1_IA5_STRING */
 202   SILC_ASN1_TAG_UTC_TIME              = 23, /* SILC_ASN1_UTC_TIME */
 203   SILC_ASN1_TAG_GENERALIZED_TIME      = 24, /* SILC_ASN1_GENERAL_STRING */
 204   SILC_ASN1_TAG_GRAPHIC_STRING        = 25, /* not supported */
 205   SILC_ASN1_TAG_VISIBLE_STRING        = 26, /* SILC_ASN1_VISIBLE_STRING */
 206   SILC_ASN1_TAG_GENERAL_STRING        = 27, /* SILC_ASN1_GENERAL_STRING */
 207   SILC_ASN1_TAG_UNIVERSAL_STRING      = 28, /* SILC_ASN1_UNIVERSAL_STRING */
 208   SILC_ASN1_TAG_UNRESTRICTED_STRING   = 29, /* SILC_ASN1_UNRESTRICTED_STRING */
 209   SILC_ASN1_TAG_BMP_STRING            = 30, /* SILC_ASN1_BMP_STRING */
 210 } SilcAsn1Tag;
 211 /***/
 212
 213 #include "silcasn1_i.h"
 214
 215 /****f* silcasn1/SilcASN1API/silc_asn1_alloc
 216  *
 217  * SYNOPSIS
 218  *
 219  *    SilcAsn1 silc_asn1_alloc(SilcStack stack);
 220  *
 221  * DESCRIPTION
 222  *
 223  *    Allocates and initializes ASN.1 encoder/decoder and returns SilcAsn1
 224  *    context or NULL on error.  This context can be used with both
 225  *    silc_asn1_encode and silc_asn1_decode functions.  If `stack' is non-NULL
 226  *    all memory will be allocated from `stack'.
 227  *
 228  *    Usually SilcAsn1 is allocated when encoder or decoder is needed,
 229  *    however it is also possible to allocate long-lasting SilcAsn1 and
 230  *    use that every time ASN.1 routines are needed.  Application could
 231  *    for example allocate one SilcAsn1 and use that for all ASN.1 encoding
 232  *    and decoding.
 233  *
 234  *    When this context is freed with silc_asn1_free all memory will be
 235  *    freed, and all encoded ASN.1 buffers becomes invalid.  Also all
 236  *    data that is returned by silc_asn1_encode and silc_asn1_decode function
 237  *    becomes invalid, unless SILC_ASN1_ALLOC flag is used, in which case the
 238  *    memory is allocated from `stack' and the `stack' is consumed.
 239  *
 240  ***/
 241 SilcAsn1 silc_asn1_alloc(SilcStack stack);
 242
 243 /****f* silcasn1/SilcASN1API/silc_asn1_free
 244  *
 245  * SYNOPSIS
 246  *
 247  *    void silc_asn1_free(SilcAsn1 asn1);
 248  *
 249  * DESCRIPTION
 250  *
 251  *    Frees the SilcAsn1 context and all allocated memory.  All encoded
 252  *    buffers and all decoded buffers with this context becomes invalid
 253  *    after this call.
 254  *
 255  ***/
 256 void silc_asn1_free(SilcAsn1 asn1);
 257
 258 /****f* silcasn1/SilcASN1API/silc_asn1_init
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcBool silc_asn1_init(SilcAsn1 asn1, SilcStack stack);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Initializes a pre-allocated SilcAsn1 context.  This call is
 267  *    equivalent to silc_asn1_alloc except that this takes the pre-allocated
 268  *    context as argument.
 269  *
 270  * EXAMPLE
 271  *
 272  *    SilcAsn1Struct asn1;
 273  *    if (!silc_asn1_init(&asn1, NULL))
 274  *      error;
 275  *
 276  ***/
 277 SilcBool silc_asn1_init(SilcAsn1 asn1, SilcStack stack);
 278
 279 /****f* silcasn1/SilcASN1API/silc_asn1_uninit
 280  *
 281  * SYNOPSIS
 282  *
 283  *    void silc_asn1_uninit(SilcAsn1 asn1);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Uninitializes a pre-allocated SilcAsn1 context.  Use this function
 288  *    instead of silc_asn1_free if you used silc_asn1_init.
 289  *
 290  ***/
 291 void silc_asn1_uninit(SilcAsn1 asn1);
 292
 293 /****f* silcasn1/SilcASN1API/silc_asn1_encode
 294  *
 295  * SYNOPSIS
 296  *
 297  *    SilcBool silc_asn1_encode(SilcAsn1 asn1, SilcBuffer dest, ...);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Encodes ASN.1 encoded buffer into `dest', from variable argument
 302  *    list of ASN.1 types.  The variable argument list forms the ASN.1
 303  *    trees and nodes that are encoded into the `dest'.  By default, the
 304  *    memory for `dest' is allocated from the `asn1', and the buffer becomes
 305  *    invalid either by calling silc_asn1_free, silc_asn1_uninit, or when
 306  *    silc_asn1_encode is called for the next time.
 307  *
 308  *    If the SILC_ASN1_OPTS macro with SILC_ASN1_ALLOC option is given then
 309  *    the `dest' is dynamically allocated and caller must free it by itself.
 310  *    If the `stack' was given to silc_asn1_alloc, the SILC_ASN1_ALLOC will
 311  *    allocate from that stack and consume the stack.  Alternatively if
 312  *    SILC_ASN1_ACCUMUL is given then memory is accumulated from `asn1' for
 313  *    `dest' and it is freed only when silc_asn1_free or silc_asn1_uninit
 314  *    is called.  Next call to silc_asn1_encode will not cancel the previous
 315  *    result, but will accumulate more memory for new result.
 316  *
 317  *    The variable argument list is constructed by using various
 318  *    macros, for example SILC_ASN1_SEQUENCE, etc.  The variable argument
 319  *    list must always be ended with SILC_ASN1_END type.
 320  *
 321  *    If encoding is successful this returns TRUE, FALSE on error.
 322  *
 323  * EXAMPLE
 324  *
 325  *    silc_asn1_encode(asn1, buf,
 326  *                     SILC_ASN1_SEQUENCE,
 327  *                       SILC_ASN1_BOOLEAN(bool_val),
 328  *                       SILC_ASN1_OCTET_STRING(string, string_len),
 329  *                       SILC_ASN1_SEQUENCE_T(0, 2),
 330  *                         SILC_ASN1_BOOLEAN_T(SILC_ASN1_EXPLICIT, 100, foo),
 331  *                       SILC_ASN1_END,
 332  *                       SILC_ASN1_OCTET_STRING_T(0, 1, string2, string2_len),
 333  *                     SILC_ASN1_END, SILC_ASN1_END);
 334  *
 335  *    Creates ASN.1 tree that looks something like:
 336  *
 337  *    buf ::= SEQUENCE {
 338  *      bool_val      BOOLEAN,
 339  *      string        OCTET-STRING,
 340  *               [2]  SEQUENCE {
 341  *                      foo   [100] EXPLICIT BOOLEAN }
 342  *      string2  [1]  OCTET-STRING }
 343  *
 344  ***/
 345 SilcBool silc_asn1_encode(SilcAsn1 asn1, SilcBuffer dest, ...);
 346
 347 /****f* silcasn1/SilcASN1API/silc_asn1_decode
 348  *
 349  * SYNOPSIS
 350  *
 351  *    SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
 352  *
 353  * DESCRIPTION
 354  *
 355  *    Decodes the ASN.1 encoded buffer `src' by the ASN.1 types sent
 356  *    as argument.  The ASN.1 types sent as argument must be found from
 357  *    the `src' for this function to decode successfully.
 358  *
 359  *    The memory allocated for the results are allocated from `asn1' and
 360  *    they become invalid if `asn1' becomes invalid.  Next (second) call
 361  *    to this function does NOT invalidate the previous results.  However,
 362  *    third call to this function does invalidate the results of the first
 363  *    call but not second.  On the other hand, fourth call invalidates
 364  *    the results of the second call but not third, fifth call invalidates
 365  *    the results of the third call but not fourth, and so on.  This allows
 366  *    efficient decoding, when silc_asn1_decode must be called multiple times
 367  *    to decode all data, without new memory allocations.  However, caller
 368  *    must be cautios and understand that the every second call invalidates
 369  *    the results of every second previous results.
 370  *
 371  *    If the SILC_ASN1_OPTS macro with SILC_ASN1_ALLOC option is given then
 372  *    all results are dynamically allocated and caller must free them by
 373  *    itself. If the `stack' was given to silc_asn1_alloc, the SILC_ASN1_ALLOC
 374  *    will allocate from that stack and consume the stack.  Alternatively if
 375  *    SILC_ASN1_ACCUMUL is given then memory is accumulated from `asn1' for
 376  *    results and they are freed only when the silc_asn1_free or
 377  *    silc_asn1_uninit is called.  Next calls to the silc_asn1_decode will
 378  *    NOT invalidate the old results, but will accumulate more memory for new
 379  *    results.  If the SILC_ASN1_OPTS is not given at all then the default
 380  *    allocation method (decribed above) applies.
 381  *
 382  *    If caller needs to store the results even after `asn1' becomes invalid
 383  *    then call must either use SILC_ASN1_ALLOC option or duplicate the
 384  *    results by itself.
 385  *
 386  * EXAMPLE
 387  *
 388  *    SilcBool bool_val, foo;
 389  *    unsigned char *string, string2;
 390  *    SilcUInt32 string_len, string2_len;
 391  *
 392  *    silc_asn1_decode(asn1, tree,
 393  *                     SILC_ASN1_SEQUENCE,
 394  *                       SILC_ASN1_BOOLEAN(&bool_val),
 395  *                       SILC_ASN1_OCTET_STRING(&string, &string_len),
 396  *                       SILC_ASN1_SEQUENCE_T(0, 2),
 397  *                         SILC_ASN1_BOOLEAN_T(SILC_ASN1_EXPLICIT, 100, &foo),
 398  *                       SILC_ASN1_END,
 399  *                       SILC_ASN1_OCTET_STRING_T(0, 1, &str2, &str2_len),
 400  *                     SILC_ASN1_END, SILC_ASN1_END);
 401  *
 402  ***/
 403 SilcBool silc_asn1_decode(SilcAsn1 asn1, SilcBuffer src, ...);
 404
 405 /****f* silcasn1/SilcASN1API/SILC_ASN1_OPTS
 406  *
 407  * SYNOPSIS
 408  *
 409  *    SILC_ASN1_OPTS(opts)
 410  *
 411  * DESCRIPTION
 412  *
 413  *    The `opts' is SilcAsn1Options.  This macro can be used to set
 414  *    options for silc_asn1_encode and silc_asn1_decode functions.
 415  *
 416  * NOTES
 417  *
 418  *    Only the SILC_ASN1_ALLOC and SILC_ASN1_ACCUMUL flags may be
 419  *    set with this macro.
 420  *
 421  *    This macro must be the first macro in the variable argument list
 422  *    in the function.
 423  *
 424  * EXAMPLE
 425  *
 426  *    silc_asn1_decode(asn1, tree,
 427  *                     SILC_ASN1_OPTS(SILC_ASN1_ALLOC),
 428  *                     SILC_ASN1_SEQUENCE,
 429  *                       SILC_ASN1_BOOLEAN(&bool_val),
 430  *                       SILC_ASN1_OCTET_STRING(&string, &string_len),
 431  *                     SILC_ASN1_END, SILC_ASN1_END);
 432  *
 433  ***/
 434 #define SILC_ASN1_OPTS(opts) SILC_ASN1_TAG_OPTS, (opts)
 435
 436 /****f* silcasn1/SilcASN1API/SILC_ASN1_ANY
 437  *
 438  * SYNOPSIS
 439  *
 440  *    Encoding:
 441  *    SILC_ASN1_ANY(buffer)
 442  *    SILC_ASN1_ANY_T(opts, tag, buffer)
 443  *
 444  *    Decoding:
 445  *    SILC_ASN1_ANY(&buffer)
 446  *    SILC_ASN1_ANY_T(opts, tag, buffer)
 447  *
 448  * DESCRIPTION
 449  *
 450  *    Macro used to encode or decode another ASN.1 node.  The buffer type
 451  *    is SilcBuffer.  This macro can be used for example to split large
 452  *    tree into multiple nodes, and then decoding the nodes separately from
 453  *    the buffers.
 454  *
 455  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 456  *
 457  * EXAMPLE
 458  *
 459  *    // Encode node of two boolean values
 460  *    silc_asn1_encode(asn1, node,
 461  *                     SILC_ASN1_BOOLEAN(val1),
 462  *                     SILC_ASN1_BOOLEAN(val2),
 463  *                     SILC_ASN1_END);
 464  *
 465  *    // Encode tree with the node
 466  *    silc_asn1_encode(asn1, tree,
 467  *                     SILC_ASN1_SEQUENCE_T(SILC_ASN1_PRIVATE, 101),
 468  *                       SILC_ASN1_ANY(node),
 469  *                       SILC_ASN1_BOOLEAN(boolval),
 470  *                     SILC_ASN1_END, SILC_ASN1_END);
 471  *
 472  ***/
 473 #define SILC_ASN1_ANY(x) SILC_ASN1_U1(ANY, x)
 474 #define SILC_ASN1_ANY_T(o, t, x) SILC_ASN1_T1(ANY, o, t, x)
 475
 476 /****f* silcasn1/SilcASN1API/SILC_ASN1_ANY_PRIMITIVE
 477  *
 478  * SYNOPSIS
 479  *
 480  *    Encoding:
 481  *    SILC_ASN1_ANY_PRIMITIVE(tag, buffer)
 482  *    SILC_ASN1_ANY_PRIMITIVE_T(opts, tag, buffer)
 483  *
 484  *    Decoding:
 485  *    SILC_ASN1_ANY_PRIMITIVE(tag, &buffer)
 486  *    SILC_ASN1_ANY_PRIMITIVE_T(opts, tag, buffer)
 487  *
 488  * DESCRIPTION
 489  *
 490  *    Special macro used to encode pre-encoded primitive data blob.  The data
 491  *    can be any primitive type that is already encoded in correct format.
 492  *    The caller is responsible of making sure the data is formatted
 493  *    correctly.  When decoding this returns the raw data blob and the caller
 494  *    must know of what type and format it is.  The buffer type is SilcBuffer.
 495  *
 496  *    This macro can be used in cases when the data to be encoded is already
 497  *    in encoded format, and it only needs to be added to ASN.1 tree.  The
 498  *    SILC_ASN1_ANY cannot be used with primitives when tagging implicitly,
 499  *    in these cases this macro can be used.
 500  *
 501  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 502  *
 503  * EXAMPLE
 504  *
 505  *    // Get MP integer in encoded format
 506  *    mpbuf = mp_get_octet_string(mp);
 507  *
 508  *    // Encode the MP integer data to the tree
 509  *    silc_asn1_encode(asn1, tree,
 510  *                     SILC_ASN1_ANY_PRIMITIVE(SILC_ASN1_TAG_INTEGER, mpbuf),
 511  *                     SILC_ASN1_END);
 512  *
 513  *    // Decode the MP integer data from the tree
 514  *    silc_asn1_decode(asn1, tree,
 515  *                     SILC_ASN1_ANY_PRIMITIVE(SILC_ASN1_TAG_INTEGER, &buffer),
 516  *                     SILC_ASN1_END);
 517  *
 518  ***/
 519 #define SILC_ASN1_ANY_PRIMITIVE(t, x) SILC_ASN1_T1(ANY_PRIMITIVE, 0, t, x)
 520 #define SILC_ASN1_ANY_PRIMITIVE_T(o, t, x) SILC_ASN1_T1(ANY_PRIMITIVE, o, t, x)
 521
 522 /****f* silcasn1/SilcASN1API/SILC_ASN1_SEQUENCE
 523  *
 524  * SYNOPSIS
 525  *
 526  *    Encoding:
 527  *    SILC_ASN1_SEQUENCE
 528  *    SILC_ASN1_SEQUENCE_T(opts, tag)
 529  *
 530  *    Decoding:
 531  *    SILC_ASN1_SEQUENCE
 532  *    SILC_ASN1_SEQUENCE_T(opts, tag)
 533  *
 534  * DESCRIPTION
 535  *
 536  *    Macro used to encode or decode sequence.  The sequence must be
 537  *    terminated with SILC_ASN1_END.
 538  *
 539  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 540  *
 541  * EXAMPLE
 542  *
 543  *    silc_asn1_encode(asn1, tree,
 544  *                     SILC_ASN1_SEQUENCE,
 545  *                       SILC_ASN1_ANY(node),
 546  *                       SILC_ASN1_BOOLEAN(boolval),
 547  *                     SILC_ASN1_END, SILC_ASN1_END);
 548  *
 549  ***/
 550 #define SILC_ASN1_SEQUENCE SILC_ASN1_U0(SEQUENCE)
 551 #define SILC_ASN1_SEQUENCE_T(o, t) SILC_ASN1_T0(SEQUENCE, o, t)
 552
 553 /****f* silcasn1/SilcASN1API/SILC_ASN1_SET
 554  *
 555  * SYNOPSIS
 556  *
 557  *    Encoding:
 558  *    SILC_ASN1_SET
 559  *    SILC_ASN1_SET_T(opts, tag)
 560  *
 561  *    Decoding:
 562  *    SILC_ASN1_SET
 563  *    SILC_ASN1_SET_T(opts, tag)
 564  *
 565  * DESCRIPTION
 566  *
 567  *    Macro used to encode or decode set.  The set must be terminated
 568  *    with SILC_ASN1_END.
 569  *
 570  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 571  *
 572  * EXAMPLE
 573  *
 574  *    silc_asn1_encode(asn1, tree,
 575  *                     SILC_ASN1_SET_T(SILC_ASN1_EXPLICIT, 0),
 576  *                       SILC_ASN1_BOOLEAN(boolval),
 577  *                     SILC_ASN1_END, SILC_ASN1_END);
 578  *
 579  ***/
 580 #define SILC_ASN1_SET SILC_ASN1_U0(SET)
 581 #define SILC_ASN1_SET_T(o, t) SILC_ASN1_T0(SET, o, t)
 582
 583 /****f* silcasn1/SilcASN1API/SILC_ASN1_SEQUENCE_OF
 584  *
 585  * SYNOPSIS
 586  *
 587  *    Decoding:
 588  *    SILC_ASN1_SEQUENCE_OF(bufarray, numbufs)
 589  *
 590  * DESCRIPTION
 591  *
 592  *    Macro used to decode sequence of specified type.  This returns
 593  *    an array of SilcBuffers and number of buffers in the array.  The
 594  *    SILC_ASN1_CHOICE macro may also be used with this macro.
 595  *
 596  * NOTES
 597  *
 598  *    This macro must be used either with SILC_ASN1_ALLOC or SILC_ASN1_ACCUMUL
 599  *    flags.  Do not use this macro without flags.
 600  *
 601  * EXAMPLE
 602  *
 603  *     SilcBuffer bufs;
 604  *     SilcUInt32 count;
 605  *
 606  *     // Decode sequence of sequences.  Each returned buffer in the array
 607  *     // is a sequence.
 608  *     silc_asn1_decode(asn1, exts,
 609  *                      SILC_ASN1_OPTS(SILC_ASN1_ACCUMUL),
 610  *                      SILC_ASN1_SEQUENCE_OF(&bufs, &count),
 611  *                        SILC_ASN1_TAG_SEQUENCE,
 612  *                      SILC_ASN1_END, SILC_ASN1_END);
 613  *
 614  ***/
 615 #define SILC_ASN1_SEQUENCE_OF(x, c) SILC_ASN1_U2(SEQUENCE_OF, x, c)
 616
 617 /****f* silcasn1/SilcASN1API/SILC_ASN1_SET_OF
 618  *
 619  * SYNOPSIS
 620  *
 621  *    Decoding:
 622  *    SILC_ASN1_SET_OF(bufarray, numbufs)
 623  *
 624  * DESCRIPTION
 625  *
 626  *    Macro used to decode set of specified type.  This returns
 627  *    an array of SilcBuffers and number of buffers in the array.  The
 628  *    SILC_ASN1_CHOICE macro may also be used with this macro.
 629  *
 630  * NOTES
 631  *
 632  *    This macro must be used either with SILC_ASN1_ALLOC or SILC_ASN1_ACCUMUL
 633  *    flags.  Do not use this macro without flags.
 634  *
 635  * EXAMPLE
 636  *
 637  *     // Decode set of sequences.  Each returned buffer in the array
 638  *     // is a sequence.
 639  *     silc_asn1_decode(asn1, exts,
 640  *                      SILC_ASN1_OPTS(SILC_ASN1_ALLOC),
 641  *                      SILC_ASN1_SET_OF(&bufs, &count),
 642  *                        SILC_ASN1_TAG_SEQUENCE,
 643  *                      SILC_ASN1_END, SILC_ASN1_END);
 644  *
 645  ***/
 646 #define SILC_ASN1_SET_OF(x, c) SILC_ASN1_U2(SEQUENCE_OF, x, c)
 647
 648 /****f* silcasn1/SilcASN1API/SILC_ASN1_CHOICE
 649  *
 650  * SYNOPSIS
 651  *
 652  *    Decoding:
 653  *    SILC_ASN1_CHOICE(&chosen)
 654  *
 655  * DESCRIPTION
 656  *
 657  *    Macro used to specify choices in decoding.  The choice list must
 658  *    be terminated with SILC_ASN1_END.  There is no limit how many choices
 659  *    can be specified in the list.  The `chosen' is SilcUInt32 and its
 660  *    value tells which of the choice was found.  First choice in the list
 661  *    has value 1, second value 2, and so on.
 662  *
 663  * EXAMPLE
 664  *
 665  *    // Decode timeval that is either UTC or generalized time
 666  *    silc_asn1_decode(asn1, tree,
 667  *                     SILC_ASN1_SEQUENCE,
 668  *                       SILC_ASN1_CHOICE(&chosen),
 669  *                         SILC_ASN1_UTC_TIME(&timeval),
 670  *                         SILC_ASN1_GEN_TIME(&timeval),
 671  *                       SILC_ASN1_END,
 672  *                     SILC_ASN1_END, SILC_ASN1_END);
 673  *
 674  ***/
 675 #define SILC_ASN1_CHOICE(x) SILC_ASN1_U1(CHOICE, x)
 676
 677 /****f* silcasn1/SilcASN1API/SILC_ASN1_BOOLEAN
 678  *
 679  * SYNOPSIS
 680  *
 681  *    Encoding:
 682  *    SILC_ASN1_BOOLEAN(boolval)
 683  *    SILC_ASN1_BOOLEAN_T(opts, tag, boolval)
 684  *
 685  *    Decoding:
 686  *    SILC_ASN1_BOOLEAN(&boolval)
 687  *    SILC_ASN1_BOOLEAN_T(opts, tag, &boolval)
 688  *
 689  * DESCRIPTION
 690  *
 691  *    Macro used to encode or decode boolean value.  The boolean type
 692  *    is SilcBool.
 693  *
 694  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 695  *
 696  ***/
 697 #define SILC_ASN1_BOOLEAN(x) SILC_ASN1_U1(BOOLEAN, x)
 698 #define SILC_ASN1_BOOLEAN_T(o, t, x) SILC_ASN1_T1(BOOLEAN, o, t, x)
 699
 700 /****f* silcasn1/SilcASN1API/SILC_ASN1_INT
 701  *
 702  * SYNOPSIS
 703  *
 704  *    Encoding:
 705  *    SILC_ASN1_INT(integer)
 706  *    SILC_ASN1_INT_T(opts, tag, &integer)
 707  *
 708  *    Decoding:
 709  *    SILC_ASN1_INT(&integer)
 710  *    SILC_ASN1_INT_T(opts, tag, &integer);
 711  *
 712  * DESCRIPTION
 713  *
 714  *    Macro used to encode or decode multiple precision integer.  The
 715  *    integer type is SilcMPInt.
 716  *
 717  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 718  *
 719  ***/
 720 #define SILC_ASN1_INT(x) SILC_ASN1_U1(INTEGER, x)
 721 #define SILC_ASN1_INT_T(o, t, x) SILC_ASN1_T1(INTEGER, o, t, x)
 722
 723 /****f* silcasn1/SilcASN1API/SILC_ASN1_SHORT_INT
 724  *
 725  * SYNOPSIS
 726  *
 727  *    Encoding:
 728  *    SILC_ASN1_SHORT_INT(integer)
 729  *    SILC_ASN1_SHORT_INT_T(opts, tag, &integer)
 730  *
 731  *    Decoding:
 732  *    SILC_ASN1_SHORT_INT(&integer)
 733  *    SILC_ASN1_SHORT_INT_T(opts, tag, &integer);
 734  *
 735  * DESCRIPTION
 736  *
 737  *    Macro used to encode or decode short integer (32 bits).  The
 738  *    integer type is SilcUInt32.
 739  *
 740  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 741  *
 742  ***/
 743 #define SILC_ASN1_SHORT_INT(x) SILC_ASN1_U1(SHORT_INTEGER, x)
 744 #define SILC_ASN1_SHORT_INT_T(o, t, x) SILC_ASN1_T1(SHORT_INTEGER, o, t, x)
 745
 746 /****f* silcasn1/SilcASN1API/SILC_ASN1_ENUM
 747  *
 748  * SYNOPSIS
 749  *
 750  *    Encoding:
 751  *    SILC_ASN1_ENUM(enum)
 752  *    SILC_ASN1_ENUM_T(opts, tag, &enum)
 753  *
 754  *    Decoding:
 755  *    SILC_ASN1_ENUM(&enum)
 756  *    SILC_ASN1_ENUM_T(opts, tag, &enum);
 757  *
 758  * DESCRIPTION
 759  *
 760  *    Macro used to encode or decode enumeration value.  The enumeration
 761  *    type is SilcMPInt.
 762  *
 763  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 764  *
 765  ***/
 766 #define SILC_ASN1_ENUM(x) SILC_ASN1_U1(ENUM, x)
 767 #define SILC_ASN1_ENUM_T(o, t, x) SILC_ASN1_T1(ENUM, o, t, x)
 768
 769 /****f* silcasn1/SilcASN1API/SILC_ASN1_BIT_STRING
 770  *
 771  * SYNOPSIS
 772  *
 773  *    Encoding:
 774  *    SILC_ASN1_BIT_STRING(str, str_len)
 775  *    SILC_ASN1_BIT_STRING_T(opts, tag, str, str_len)
 776  *
 777  *    Decoding:
 778  *    SILC_ASN1_BIT_STRING(&str, &str_len)
 779  *    SILC_ASN1_BIT_STRING_T(opts, tag, &str, &str_len)
 780  *
 781  * DESCRIPTION
 782  *
 783  *    Macro used to encode or decode bit string.  The string length in
 784  *    encoding must be in bits (bytes * 8).  The decoded length is in
 785  *    bits as well.  The string type is unsigned char and string length
 786  *    SilcUInt32.
 787  *
 788  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 789  *
 790  ***/
 791 #define SILC_ASN1_BIT_STRING(x, xl) SILC_ASN1_U2(BIT_STRING, x, xl)
 792 #define SILC_ASN1_BIT_STRING_T(o, t, x, xl) SILC_ASN1_T2(BIT_STRING, o, t, x, xl)
 793
 794 /****f* silcasn1/SilcASN1API/SILC_ASN1_NULL
 795  *
 796  * SYNOPSIS
 797  *
 798  *    Encoding:
 799  *    SILC_ASN1_NULL
 800  *    SILC_ASN1_NULL_T(opts, tag, set)
 801  *
 802  *    Decoding:
 803  *    SILC_ASN1_NULL
 804  *    SILC_ASN1_NULL_T(opts, tag, &set)
 805  *
 806  * DESCRIPTION
 807  *
 808  *    Macro used to encode or decode null value.
 809  *
 810  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.  In encoding
 811  *    `set' is SilcBool and if it is TRUE the NULL value will be encoded.  If
 812  *    it is FALSE the SILC_ASN1_NULL will be ignored.  In decoding the `set'
 813  *    is SilcBool and if it is TRUE the NULL value was present.  This can be
 814  *    used to verify whether NULL was present if it is SILC_ASN1_OPTIONAL.
 815  *
 816  ***/
 817 #define SILC_ASN1_NULL(x) SILC_ASN1_U1(NULL, x)
 818 #define SILC_ASN1_NULL_T(o, t, x) SILC_ASN1_T1(NULL, o, t, x)
 819
 820 /****f* silcasn1/SilcASN1API/SILC_ASN1_OID
 821  *
 822  * SYNOPSIS
 823  *
 824  *    Encoding:
 825  *    SILC_ASN1_OID(oid)
 826  *    SILC_ASN1_OID_T(opts, tag, oid)
 827  *
 828  *    Decoding:
 829  *    SILC_ASN1_OID(&oid)
 830  *    SILC_ASN1_OID_T(opts, tag, &oid)
 831  *
 832  * DESCRIPTION
 833  *
 834  *    Macro used to encode or decode OID string.  The OID string type
 835  *    is NULL terminated char.  Its length can be determinted with strlen().
 836  *
 837  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 838  *
 839  ***/
 840 #define SILC_ASN1_OID(x) SILC_ASN1_U1(OID, x)
 841 #define SILC_ASN1_OID_T(o, t, x) SILC_ASN1_UT(OID, o, t, x)
 842
 843 /****f* silcasn1/SilcASN1API/SILC_ASN1_OCTET_STRING
 844  *
 845  * SYNOPSIS
 846  *
 847  *    Encoding:
 848  *    SILC_ASN1_OCTET_STRING(str, str_len)
 849  *    SILC_ASN1_OCTET_STRING_T(opts, tag, str, str_len)
 850  *
 851  *    Decoding:
 852  *    SILC_ASN1_OCTET_STRING(&str, &str_len)
 853  *    SILC_ASN1_OCTET_STRING_T(opts, tag, &str, &str_len)
 854  *
 855  * DESCRIPTION
 856  *
 857  *    Macro used to encode or decode octet string.  The string type is
 858  *    unsigned char and string length SilcUInt32.  Octet string is
 859  *    considered to be 8-bit unsigned binary data.
 860  *
 861  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 862  *
 863  ***/
 864 #define SILC_ASN1_OCTET_STRING(x, xl) SILC_ASN1_U2(OCTET_STRING, x, xl)
 865 #define SILC_ASN1_OCTET_STRING_T(o, t, x, xl) SILC_ASN1_T2(OCTET_STRING, o, t, x, xl)
 866
 867 /****f* silcasn1/SilcASN1API/SILC_ASN1_UTF8_STRING
 868  *
 869  * SYNOPSIS
 870  *
 871  *    Encoding:
 872  *    SILC_ASN1_UTF8_STRING(str, str_len)
 873  *    SILC_ASN1_UTF8_STRING_T(opts, tag, str, str_len)
 874  *
 875  *    Decoding:
 876  *    SILC_ASN1_UTF8_STRING(&str, &str_len)
 877  *    SILC_ASN1_UTF8_STRING_T(opts, tag, &str, &str_len)
 878  *
 879  * DESCRIPTION
 880  *
 881  *    Macro used to encode or decode UTF-8 string.  The string type is
 882  *    unsigned char and string length SilcUInt32.
 883  *
 884  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 885  *
 886  * NOTES
 887  *
 888  *    The string must be in UTF-8 encoding when encoding.  The decoded
 889  *    string will be in UTF-8 encoding.  The data is also encoded to
 890  *    or decoded from UTF-8.
 891  *
 892  ***/
 893 #define SILC_ASN1_UTF8_STRING(x, xl) SILC_ASN1_U2(UTF8_STRING, x, xl)
 894 #define SILC_ASN1_UTF8_STRING_T(o, t, x, xl) SILC_ASN1_T2(UTF8_STRING, o, t, x, xl)
 895
 896 /****f* silcasn1/SilcASN1API/SILC_ASN1_NUMERIC_STRING
 897  *
 898  * SYNOPSIS
 899  *
 900  *    Encoding:
 901  *    SILC_ASN1_NUMERIC_STRING(str, str_len)
 902  *    SILC_ASN1_NUMERIC_STRING_T(opts, tag, str, str_len)
 903  *
 904  *    Decoding:
 905  *    SILC_ASN1_NUMERIC_STRING(&str, &str_len)
 906  *    SILC_ASN1_NUMERIC_STRING_T(opts, tag, &str, &str_len)
 907  *
 908  * DESCRIPTION
 909  *
 910  *    Macro used to encode or decode numerical string.  The string type is
 911  *    unsigned char and string length SilcUInt32.
 912  *
 913  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 914  *
 915  * NOTES
 916  *
 917  *    The string must be in UTF-8 encoding when encoding.  The decoded
 918  *    string will be in UTF-8 encoding.  The actual data is encoded to
 919  *    or decoded from numerical.
 920  *
 921  ***/
 922 #define SILC_ASN1_NUMERIC_STRING(x, xl) SILC_ASN1_U2(NUMERIC_STRING, x, xl)
 923 #define SILC_ASN1_NUMERIC_STRING_T(o, t, x, xl) SILC_ASN1_T2(NUMERIC_STRING, o, t, x, xl)
 924
 925 /****f* silcasn1/SilcASN1API/SILC_ASN1_PRINTABLE_STRING
 926  *
 927  * SYNOPSIS
 928  *
 929  *    Encoding:
 930  *    SILC_ASN1_PRINTABLE_STRING(str, str_len)
 931  *    SILC_ASN1_PRINTABLE_STRING_T(opts, tag, str, str_len)
 932  *
 933  *    Decoding:
 934  *    SILC_ASN1_PRINTABLE_STRING(&str, &str_len)
 935  *    SILC_ASN1_PRINTABLE_STRING_T(opts, tag, &str, &str_len)
 936  *
 937  * DESCRIPTION
 938  *
 939  *    Macro used to encode or decode printable string.  The string type is
 940  *    unsigned char and string length SilcUInt32.
 941  *
 942  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 943  *
 944  * NOTES
 945  *
 946  *    The string must be in UTF-8 encoding when encoding.  The decoded
 947  *    string will be in UTF-8 encoding.  The actual data is encoded to
 948  *    or decoded from printable.
 949  *
 950  ***/
 951 #define SILC_ASN1_PRINTABLE_STRING(x, xl) SILC_ASN1_U2(PRINTABLE_STRING, x, xl)
 952 #define SILC_ASN1_PRINTABLE_STRING_T(o, t, x, xl) SILC_ASN1_T2(PRINTABLE_STRING, o, t, x, xl)
 953
 954 /****f* silcasn1/SilcASN1API/SILC_ASN1_TELETEX_STRING
 955  *
 956  * SYNOPSIS
 957  *
 958  *    Encoding:
 959  *    SILC_ASN1_TELETEX_STRING(str, str_len)
 960  *    SILC_ASN1_TELETEX_STRING_T(opts, tag, str, str_len)
 961  *
 962  *    Decoding:
 963  *    SILC_ASN1_TELETEX_STRING(&str, &str_len)
 964  *    SILC_ASN1_TELETEX_STRING_T(opts, tag, &str, &str_len)
 965  *
 966  * DESCRIPTION
 967  *
 968  *    Macro used to encode or decode teletex (T61) string.  The string type is
 969  *    unsigned char and string length SilcUInt32.
 970  *
 971  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
 972  *
 973  * NOTES
 974  *
 975  *    The string must be in UTF-8 encoding when encoding.  The decoded
 976  *    string will be in UTF-8 encoding.  The actual data is encoded to
 977  *    or decoded from teletex (T61).
 978  *
 979  ***/
 980 #define SILC_ASN1_TELETEX_STRING(x, xl) SILC_ASN1_U2(TELETEX_STRING, x, xl)
 981 #define SILC_ASN1_TELETEX_STRING_T(o, t, x, xl) SILC_ASN1_T2(TELETEX_STRING, o, t, x, xl)
 982
 983 /****f* silcasn1/SilcASN1API/SILC_ASN1_IA5_STRING
 984  *
 985  * SYNOPSIS
 986  *
 987  *    Encoding:
 988  *    SILC_ASN1_IA5_STRING(str, str_len)
 989  *    SILC_ASN1_IA5_STRING_T(opts, tag, str, str_len)
 990  *
 991  *    Decoding:
 992  *    SILC_ASN1_IA5_STRING(&str, &str_len)
 993  *    SILC_ASN1_IA5_STRING_T(opts, tag, &str, &str_len)
 994  *
 995  * DESCRIPTION
 996  *
 997  *    Macro used to encode or decode US ASCII (IA5) string.  The string type
 998  *    is unsigned char and string length SilcUInt32.
 999  *
1000  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1001  *
1002  * NOTES
1003  *
1004  *    The string must be in UTF-8 encoding when encoding.  The decoded
1005  *    string will be in UTF-8 encoding.  The actual data is encoded to
1006  *    or decoded from US ASCII (IA5).
1007  *
1008  ***/
1009 #define SILC_ASN1_IA5_STRING(x, xl) SILC_ASN1_U2(IA5_STRING, x, xl)
1010 #define SILC_ASN1_IA5_STRING_T(o, t, x, xl) SILC_ASN1_T2(IA5_STRING, o, t, x, xl)
1011
1012 /****f* silcasn1/SilcASN1API/SILC_ASN1_VISIBLE_STRING
1013  *
1014  * SYNOPSIS
1015  *
1016  *    Encoding:
1017  *    SILC_ASN1_VISIBLE_STRING(str, str_len)
1018  *    SILC_ASN1_VISIBLE_STRING_T(opts, tag, str, str_len)
1019  *
1020  *    Decoding:
1021  *    SILC_ASN1_VISIBLE_STRING(&str, &str_len)
1022  *    SILC_ASN1_VISIBLE_STRING_T(opts, tag, &str, &str_len)
1023  *
1024  * DESCRIPTION
1025  *
1026  *    Macro used to encode or decode visible string.  The string type is
1027  *    unsigned char and string length SilcUInt32.
1028  *
1029  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1030  *
1031  * NOTES
1032  *
1033  *    The string must be in UTF-8 encoding when encoding.  The decoded
1034  *    string will be in UTF-8 encoding.  The actual data is encoded to
1035  *    or decoded from visible.
1036  *
1037  ***/
1038 #define SILC_ASN1_VISIBLE_STRING(x, xl) SILC_ASN1_U2(VISIBLE_STRING, x, xl)
1039 #define SILC_ASN1_VISIBLE_STRING_T(o, t, x, xl) SILC_ASN1_T2(VISIBLE_STRING, o, t, x, xl)
1040
1041 /****f* silcasn1/SilcASN1API/SILC_ASN1_UNIVERSAL_STRING
1042  *
1043  * SYNOPSIS
1044  *
1045  *    Encoding:
1046  *    SILC_ASN1_UNIVERSAL_STRING(str, str_len)
1047  *    SILC_ASN1_UNIVERSAL_STRING_T(opts, tag, str, str_len)
1048  *
1049  *    Decoding:
1050  *    SILC_ASN1_UNIVERSAL_STRING(&str, &str_len)
1051  *    SILC_ASN1_UNIVERSAL_STRING_T(opts, tag, &str, &str_len)
1052  *
1053  * DESCRIPTION
1054  *
1055  *    Macro used to encode or decode universal (UCS-4) string.  The string
1056  *    type is unsigned char and string length SilcUInt32.
1057  *
1058  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1059  *
1060  * NOTES
1061  *
1062  *    The string must be in UTF-8 encoding when encoding.  The decoded
1063  *    string will be in UTF-8 encoding.  The actual data is encoded to
1064  *    or decoded from universal (UCS-4).
1065  *
1066  ***/
1067 #define SILC_ASN1_UNIVERSAL_STRING(x, xl) SILC_ASN1_U2(UNIVERSAL_STRING, x, xl)
1068 #define SILC_ASN1_UNIVERSAL_STRING_T(o, t, x, xl) SILC_ASN1_T2(UNIVERSAL_STRING, o, t, x, xl)
1069
1070 /****f* silcasn1/SilcASN1API/SILC_ASN1_BMP_STRING
1071  *
1072  * SYNOPSIS
1073  *
1074  *    Encoding:
1075  *    SILC_ASN1_BMP_STRING(str, str_len)
1076  *    SILC_ASN1_BMP_STRING_T(opts, tag, str, str_len)
1077  *
1078  *    Decoding:
1079  *    SILC_ASN1_BMP_STRING(&str, &str_len)
1080  *    SILC_ASN1_BMP_STRING_T(opts, tag, &str, &str_len)
1081  *
1082  * DESCRIPTION
1083  *
1084  *    Macro used to encode or decode BMP (UCS-2) string.  The string type is
1085  *    unsigned char and string length SilcUInt32.
1086  *
1087  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1088  *
1089  * NOTES
1090  *
1091  *    The string must be in UTF-8 encoding when encoding.  The decoded
1092  *    string will be in UTF-8 encoding.  The actual data is encoded to
1093  *    or decoded from BMP (UCS-2)
1094  *
1095  ***/
1096 #define SILC_ASN1_BMP_STRING(x, xl) SILC_ASN1_U2(BMP_STRING, x, xl)
1097 #define SILC_ASN1_BMP_STRING_T(o, t, x, xl) SILC_ASN1_T2(BMP_STRING, o, t, x, xl)
1098
1099 /****f* silcasn1/SilcASN1API/SILC_ASN1_UNRESTRICTED_STRING
1100  *
1101  * SYNOPSIS
1102  *
1103  *    Encoding:
1104  *    SILC_ASN1_UNRESTRICTED_STRING(str, str_len)
1105  *    SILC_ASN1_UNRESTRICTED_STRING_T(opts, tag, str, str_len)
1106  *
1107  *    Decoding:
1108  *    SILC_ASN1_UNRESTRICTED_STRING(&str, &str_len)
1109  *    SILC_ASN1_UNRESTRICTED_STRING_T(opts, tag, &str, &str_len)
1110  *
1111  * DESCRIPTION
1112  *
1113  *    Macro used to encode or decode unrestricted string.  The string type is
1114  *    unsigned char and string length SilcUInt32.
1115  *
1116  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1117  *
1118  * NOTES
1119  *
1120  *    The string must be in UTF-8 encoding when encoding.  The decoded
1121  *    string will be in UTF-8 encoding.  The actual data is encoded to
1122  *    or decoded from unrestricted.  NOTE: this implementation use 8-bit ASCII.
1123  *
1124  ***/
1125 #define SILC_ASN1_UNRESTRICTED_STRING(x, xl) SILC_ASN1_U2(UNRESTRICTED_STRING, x, xl)
1126 #define SILC_ASN1_UNRESTRICTED_STRING_T(o, t, x, xl) SILC_ASN1_T2(UNRESTRICTED_STRING, o, t, x, xl)
1127
1128 /****f* silcasn1/SilcASN1API/SILC_ASN1_GENERAL_STRING
1129  *
1130  * SYNOPSIS
1131  *
1132  *    Encoding:
1133  *    SILC_ASN1_GENERAL_STRING(str, str_len)
1134  *    SILC_ASN1_GENERAL_STRING_T(opts, tag, str, str_len)
1135  *
1136  *    Decoding:
1137  *    SILC_ASN1_GENERAL_STRING(&str, &str_len)
1138  *    SILC_ASN1_GENERAL_STRING_T(opts, tag, &str, &str_len)
1139  *
1140  * DESCRIPTION
1141  *
1142  *    Macro used to encode or decode general string.  The string type is
1143  *    unsigned char and string length SilcUInt32.
1144  *
1145  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1146  *
1147  * NOTES
1148  *
1149  *    The string must be in UTF-8 encoding when encoding.  The decoded
1150  *    string will be in UTF-8 encoding.  The actual data is encoded to
1151  *    or decoded from general.  NOTE: this implementation use 8-bit ASCII.
1152  *
1153  ***/
1154 #define SILC_ASN1_GENERAL_STRING(x, xl) SILC_ASN1_U2(GENERAL_STRING, x, xl)
1155 #define SILC_ASN1_GENERAL_STRING_T(o, t, x, xl) SILC_ASN1_T2(GENERAL_STRING, o, t, x, xl)
1156
1157 /****f* silcasn1/SilcASN1API/SILC_ASN1_UTC_TIME
1158  *
1159  * SYNOPSIS
1160  *
1161  *    Encoding:
1162  *    SILC_ASN1_UTC_TIME(timeval)
1163  *    SILC_ASN1_UTC_TIME_T(opts, tag, timeval)
1164  *
1165  *    Decoding:
1166  *    SILC_ASN1_UTC_TIME(&str, &timeval)
1167  *    SILC_ASN1_UTC_TIME_T(opts, tag, timeval)
1168  *
1169  * DESCRIPTION
1170  *
1171  *    Macro used to encode or decode universal (UTC) time value.  The
1172  *    time value type is SilcTime.
1173  *
1174  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1175  *
1176  ***/
1177 #define SILC_ASN1_UTC_TIME(x) SILC_ASN1_U1(UTC_TIME, x)
1178 #define SILC_ASN1_UTC_TIME_T(o, t, x) SILC_ASN1_T1(UTC_TIME, o, t, x)
1179
1180 /****f* silcasn1/SilcASN1API/SILC_ASN1_GEN_TIME
1181  *
1182  * SYNOPSIS
1183  *
1184  *    Encoding:
1185  *    SILC_ASN1_GEN_TIME(timeval)
1186  *    SILC_ASN1_GEN_TIME_T(opts, tag, timeval)
1187  *
1188  *    Decoding:
1189  *    SILC_ASN1_GEN_TIME(&str, &timeval)
1190  *    SILC_ASN1_GEN_TIME_T(opts, tag, timeval)
1191  *
1192  * DESCRIPTION
1193  *
1194  *    Macro used to encode or decode generalized time value.  The
1195  *    time value type is SilcTime.
1196  *
1197  *    The `opts' is SilcAsn1Options.  The `tag' is a tag number.
1198  *
1199  ***/
1200 #define SILC_ASN1_GEN_TIME(x) SILC_ASN1_U1(GENERALIZED_TIME, x)
1201 #define SILC_ASN1_GEN_TIME_T(o, t, x) SILC_ASN1_T1(GENERALIZED_TIME, o, t, x)
1202
1203 /****f* silcasn1/SilcASN1API/SILC_ASN1_END
1204  *
1205  * SYNOPSIS
1206  *
1207  *    SILC_ASN1_END
1208  *
1209  * DESCRIPTION
1210  *
1211  *    The SILC_ASN1_END is used to terminate the variable argument list in
1212  *    silc_asn1_encode and silc_asn1_decode functions.  It is also used to
1213  *    terminate SILC_ASN1_SEQUENCE, SILC_ASN1_SEQUENCE_T, SILC_ASN1_SET,
1214  *    SILC_ASN1_SET_T, SILC_ASN1_SEQUENCE_OF, SILC_ASN1_SET_OF and
1215  *    SILC_ASN1_CHOICE macros.
1216  *
1217  ***/
1218 #define SILC_ASN1_END 0
1219
1220 #endif /* SILCASN1_H */