lib/silcasn1/silcber.h

   1 /*
   2
   3   silcber.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2008 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/BER Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The Basic Encoding Rules (BER) is the data encoding format for the
  25  * ASN.1.  This interface provides routines for encoding and decoding
  26  * arbitraty BER data blocks.  Naturally, this interface can be used
  27  * to encode and decode DER blocks as well.  These routines does not
  28  * allocate any memory and have been optimized for general ASN.1 usage.
  29  *
  30  * This is a low level interface and is not usually needed or used
  31  * directly.
  32  *
  33  * References: ITU-T X.690
  34  * http://www.itu.int/ITU-T/studygroups/com17/languages/X690_0702.pdf
  35  *
  36  ***/
  37
  38 #ifndef SILCBER_H
  39 #define SILCBER_H
  40
  41 /****d* silcasn1/SilcBerClass
  42  *
  43  * NAME
  44  *
  45  *    typedef enum { ... } SilcBerClass;
  46  *
  47  * DESCRIPTION
  48  *
  49  *    Defines the BER classes.
  50  *
  51  * SOURCE
  52  */
  53 typedef enum {
  54   SILC_BER_CLASS_UNIVERSAL       = 0x00,   /* Universal */
  55   SILC_BER_CLASS_APPLICATION     = 0x01,   /* Application */
  56   SILC_BER_CLASS_CONTEXT         = 0x02,   /* Context-specific */
  57   SILC_BER_CLASS_PRIVATE         = 0x03,   /* Private */
  58 } SilcBerClass;
  59 /***/
  60
  61 /****d* silcasn1/SilcBerEncoding
  62  *
  63  * NAME
  64  *
  65  *    typedef enum { ... } SilcBerEncoding;
  66  *
  67  * DESCRIPTION
  68  *
  69  *    Defines the BER encoding type.
  70  *
  71  * SOURCE
  72  */
  73 typedef enum {
  74   SILC_BER_ENC_PRIMITIVE         = 0x00,
  75   SILC_BER_ENC_CONSTRUCTED       = 0x01,
  76 } SilcBerEncoding;
  77 /***/
  78
  79 /****f* silcasn1/silc_ber_encode
  80  *
  81  * SYNOPSIS
  82  *
  83  *    SilcBool
  84  *    silc_ber_encode(SilcBuffer ber, SilcBerClass ber_class,
  85  *                    SilcBerEncoding encoding, SilcUInt32 tag,
  86  *                    const unsigned char *data, SilcUInt32 data_len,
  87  *                    SilcBool indefinite);
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Encodes a BER data block into the `ber', which must already have
  92  *    sufficient space allocated.  Caller can use silc_ber_encoded_len
  93  *    function to determine how much to allocate space before calling this
  94  *    function.  If the `indefinite' is TRUE then the BER block will not
  95  *    include the length of the data in the BER block.
  96  *
  97  ***/
  98 SilcBool silc_ber_encode(SilcBuffer ber, SilcBerClass ber_class,
  99                          SilcBerEncoding encoding, SilcUInt32 tag,
 100                          const unsigned char *data, SilcUInt32 data_len,
 101                          SilcBool indefinite);
 102
 103 /****f* silcasn1/silc_ber_decode
 104  *
 105  * SYNOPSIS
 106  *
 107  *    SilcBool
 108  *    silc_ber_decode(SilcBuffer ber, SilcBerClass *ber_class,
 109  *                    SilcBerEncoding *encoding, SilcUInt32 *tag,
 110  *                    const unsigned char **data, SilcUInt32 *data_len,
 111  *                    SilcBool *indefinite, SilcUInt32 *identifier_len);
 112  *
 113  * DESCRIPTION
 114  *
 115  *    Decodesa a BER data from the buffer `ber'.  Returns the class,
 116  *    encoding and the tag number for the BER data into `ber_class',
 117  *    `encoding' and `tag'.  A pointer to the start of the data area is
 118  *    returned into `data'.  If the length of the data is available from
 119  *    the BER data the length is returned into `data_len'.  If the
 120  *    `indefinite' is TRUE then the length found in `data_len' was found
 121  *    by finding end-of-contents octets from the BER data.  The
 122  *    `identifier_len' is the length of the BER header, and the length
 123  *    of the entire BER object is `identifier_len' + `data_len'.
 124  *
 125  ***/
 126 SilcBool silc_ber_decode(SilcBuffer ber, SilcBerClass *ber_class,
 127                          SilcBerEncoding *encoding, SilcUInt32 *tag,
 128                          const unsigned char **data, SilcUInt32 *data_len,
 129                          SilcBool *indefinite, SilcUInt32 *identifier_len);
 130
 131 /****f* silcasn1/silc_ber_encoded_len
 132  *
 133  * SYNOPSIS
 134  *
 135  *    SilcUInt32 silc_ber_encoded_len(SilcUInt32 tag, SilcUInt32 data_len,
 136  *                                    SilcBool indefinite);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Calculates the length of the encoded BER data object.  This utility
 141  *    function can be used to calculate how much to allocate space before
 142  *    encoding with silc_ber_encode.
 143  *
 144  ***/
 145 SilcUInt32 silc_ber_encoded_len(SilcUInt32 tag, SilcUInt32 data_len,
 146                                 SilcBool indefinite);
 147
 148 #endif /* SILCBER_H */