_ Git - BearSSL/blob - inc/bearssl_pem.h

   1 /*
   2  * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 #ifndef BR_BEARSSL_PEM_H__
  26 #define BR_BEARSSL_PEM_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 /** \file bearssl_pem.h
  32  *
  33  * # PEM Support
  34  *
  35  * PEM is a traditional encoding layer use to store binary objects (in
  36  * particular X.509 certificates, and private keys) in text files. While
  37  * the acronym comes from an old, defunct standard ("Privacy Enhanced
  38  * Mail"), the format has been reused, with some variations, by many
  39  * systems, and is a _de facto_ standard, even though it is not, actually,
  40  * specified in all clarity anywhere.
  41  *
  42  * ## Format Details
  43  *
  44  * BearSSL contains a generic, streamed PEM decoder, which handles the
  45  * following format:
  46  *
  47  *   - The input source (a sequence of bytes) is assumed to be the
  48  *     encoding of a text file in an ASCII-compatible charset. This
  49  *     includes ISO-8859-1, Windows-1252, and UTF-8 encodings. Each
  50  *     line ends on a newline character (U+000A LINE FEED). The
  51  *     U+000D CARRIAGE RETURN characters are ignored, so the code
  52  *     accepts both Windows-style and Unix-style line endings.
  53  *
  54  *   - Each object begins with a banner that occurs at the start of
  55  *     a line; the first banner characters are "`-----BEGIN `" (five
  56  *     dashes, the word "BEGIN", and a space). The banner matching is
  57  *     not case-sensitive.
  58  *
  59  *   - The _object name_ consists in the characters that follow the
  60  *     banner start sequence, up to the end of the line, but without
  61  *     trailing dashes (in "normal" PEM, there are five trailing
  62  *     dashes, but this implementation is not picky about these dashes).
  63  *     The BearSSL decoder normalises the name characters to uppercase
  64  *     (for ASCII letters only) and accepts names up to 127 characters.
  65  *
  66  *   - The object ends with a banner that again occurs at the start of
  67  *     a line, and starts with "`-----END `" (again case-insensitive).
  68  *
  69  *   - Between that start and end banner, only Base64 data shall occur.
  70  *     Base64 converts each sequence of three bytes into four
  71  *     characters; the four characters are ASCII letters, digits, "`+`"
  72  *     or "`-`" signs, and one or two "`=`" signs may occur in the last
  73  *     quartet. Whitespace is ignored (whitespace is any ASCII character
  74  *     of code 32 or less, so control characters are whitespace) and
  75  *     lines may have arbitrary length; the only restriction is that the
  76  *     four characters of a quartet must appear on the same line (no
  77  *     line break inside a quartet).
  78  *
  79  *   - A single file may contain more than one PEM object. Bytes that
  80  *     occur between objects are ignored.
  81  *
  82  *
  83  * ## PEM Decoder API
  84  *
  85  * The PEM decoder offers a state-machine API. The caller allocates a
  86  * decoder context, then injects source bytes. Source bytes are pushed
  87  * with `br_pem_decoder_push()`. The decoder stops accepting bytes when
  88  * it reaches an "event", which is either the start of an object, the
  89  * end of an object, or a decoding error within an object.
  90  *
  91  * The `br_pem_decoder_event()` function is used to obtain the current
  92  * event; it also clears it, thus allowing the decoder to accept more
  93  * bytes. When a object start event is raised, the decoder context
  94  * offers the found object name (normalised to ASCII uppercase).
  95  *
  96  * When an object is reached, the caller must set an appropriate callback
  97  * function, which will receive (by chunks) the decoded object data.
  98  *
  99  * Since the decoder context makes no dynamic allocation, it requires
 100  * no explicit deallocation.
 101  */
 102
 103 /**
 104  * \brief PEM decoder context.
 105  *
 106  * Contents are opaque (they should not be accessed directly).
 107  */
 108 typedef struct {
 109 #ifndef BR_DOXYGEN_IGNORE
 110         /* CPU for the T0 virtual machine. */
 111         struct {
 112                 uint32_t *dp;
 113                 uint32_t *rp;
 114                 const unsigned char *ip;
 115         } cpu;
 116         uint32_t dp_stack[32];
 117         uint32_t rp_stack[32];
 118         int err;
 119
 120         const unsigned char *hbuf;
 121         size_t hlen;
 122
 123         void (*dest)(void *dest_ctx, const void *src, size_t len);
 124         void *dest_ctx;
 125
 126         unsigned char event;
 127         char name[128];
 128         unsigned char buf[255];
 129         size_t ptr;
 130 #endif
 131 } br_pem_decoder_context;
 132
 133 /**
 134  * \brief Initialise a PEM decoder structure.
 135  *
 136  * \param ctx   decoder context to initialise.
 137  */
 138 void br_pem_decoder_init(br_pem_decoder_context *ctx);
 139
 140 /**
 141  * \brief Push some bytes into the decoder.
 142  *
 143  * Returned value is the number of bytes actually consumed; this may be
 144  * less than the number of provided bytes if an event is raised. When an
 145  * event is raised, it must be read (with `br_pem_decoder_event()`);
 146  * until the event is read, this function will return 0.
 147  *
 148  * \param ctx    decoder context.
 149  * \param data   new data bytes.
 150  * \param len    number of new data bytes.
 151  * \return  the number of bytes actually received (may be less than `len`).
 152  */
 153 size_t br_pem_decoder_push(br_pem_decoder_context *ctx,
 154         const void *data, size_t len);
 155
 156 /**
 157  * \brief Set the receiver for decoded data.
 158  *
 159  * When an object is entered, the provided function (with opaque context
 160  * pointer) will be called repeatedly with successive chunks of decoded
 161  * data for that object. If `dest` is set to 0, then decoded data is
 162  * simply ignored. The receiver can be set at any time, but, in practice,
 163  * it should be called immediately after receiving a "start of object"
 164  * event.
 165  *
 166  * \param ctx        decoder context.
 167  * \param dest       callback for receiving decoded data.
 168  * \param dest_ctx   opaque context pointer for the `dest` callback.
 169  */
 170 static inline void
 171 br_pem_decoder_setdest(br_pem_decoder_context *ctx,
 172         void (*dest)(void *dest_ctx, const void *src, size_t len),
 173         void *dest_ctx)
 174 {
 175         ctx->dest = dest;
 176         ctx->dest_ctx = dest_ctx;
 177 }
 178
 179 /**
 180  * \brief Get the last event.
 181  *
 182  * If an event was raised, then this function returns the event value, and
 183  * also clears it, thereby allowing the decoder to proceed. If no event
 184  * was raised since the last call to `br_pem_decoder_event()`, then this
 185  * function returns 0.
 186  *
 187  * \param ctx   decoder context.
 188  * \return  the raised event, or 0.
 189  */
 190 int br_pem_decoder_event(br_pem_decoder_context *ctx);
 191
 192 /**
 193  * \brief Event: start of object.
 194  *
 195  * This event is raised when the start of a new object has been detected.
 196  * The object name (normalised to uppercase) can be accessed with
 197  * `br_pem_decoder_name()`.
 198  */
 199 #define BR_PEM_BEGIN_OBJ   1
 200
 201 /**
 202  * \brief Event: end of object.
 203  *
 204  * This event is raised when the end of the current object is reached
 205  * (normally, i.e. with no decoding error).
 206  */
 207 #define BR_PEM_END_OBJ     2
 208
 209 /**
 210  * \brief Event: decoding error.
 211  *
 212  * This event is raised when decoding fails within an object.
 213  * This formally closes the current object and brings the decoder back
 214  * to the "out of any object" state. The offending line in the source
 215  * is consumed.
 216  */
 217 #define BR_PEM_ERROR       3
 218
 219 /**
 220  * \brief Get the name of the encountered object.
 221  *
 222  * The encountered object name is defined only when the "start of object"
 223  * event is raised. That name is normalised to uppercase (for ASCII letters
 224  * only) and does not include trailing dashes.
 225  *
 226  * \param ctx   decoder context.
 227  * \return  the current object name.
 228  */
 229 static inline const char *
 230 br_pem_decoder_name(br_pem_decoder_context *ctx)
 231 {
 232         return ctx->name;
 233 }
 234
 235 #endif