marshal.h

   1 /*
   2  * marshal.h - SKS compatible marshalling routines
   3  *
   4  * Copyright 2011 Jonathan McDowell <noodles@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the Free
   8  * Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along with
  16  * this program.  If not, see <https://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __MARSHAL_H__
  20 #define __MARSHAL_H__
  21
  22 #include "keyid.h"
  23 #include "keystructs.h"
  24
  25 /**
  26  *      marshal_publickey - Output an OpenPGP key as a byte stream
  27  *      @putchar_func: The function to put the next character to the stream
  28  *      @ctx: A pointer to the context structure for putchar_func.
  29  *      @key: The key to output.
  30  *
  31  *      Takes an OpenPGP key and marshals it to a byte stream - writes
  32  *      a 32 bit size of the forthcoming data in network byte order and
  33  *      then the flattened byte representation of the key.
  34  */
  35 void marshal_publickey(int (*putchar_func)(void *ctx, size_t count,
  36                                 void *c),
  37                                 void *ctx,
  38                                 const struct openpgp_publickey *key);
  39
  40 /**
  41  *      unmarshal_publickey - Turn a byte stream into an OpenPGP key
  42  *      @getchar_func: The function to get the next character from the stream
  43  *      @ctx: A pointer to the context structure for getchar_func.
  44  *
  45  *      Returns an OpenPGP structure which is the unmarshalled result of
  46  *      the input byte stream - ie the inverse of marshal_publickey.
  47  */
  48 struct openpgp_publickey *unmarshal_publickey(int (*getchar_func)(void *ctx,
  49                                 size_t count,
  50                                 void *c),
  51                                 void *ctx);
  52
  53 /**
  54  *      marshal_skshash - Output an SKS hash as a byte stream
  55  *      @putchar_func: The function to put the next character to the stream
  56  *      @ctx: A pointer to the context structure for putchar_func.
  57  *      @hash: The hash to output.
  58  *
  59  *      Takes an SKS hash and marshals it to a byte stream - writes
  60  *      a 32 bit size of the forthcoming data (16 bytes) in network byte order
  61  *      and then the byte representation of the hash.
  62  */
  63 void marshal_skshash(int (*putchar_func)(void *ctx, size_t count,
  64                                 void *c),
  65                                 void *ctx,
  66                                 const struct skshash *hash);
  67
  68 /**
  69  *      unmarshal_skshash - Turn a byte stream into an SKS hash structure
  70  *      @getchar_func: The function to get the next character from the stream
  71  *      @ctx: A pointer to the context structure for getchar_func.
  72  *
  73  *      Returns an SKS hash structure which is the unmarshalled result of
  74  *      the input byte stream - ie the inverse of marshal_skshash.
  75  */
  76 struct skshash *unmarshal_skshash(int (*getchar_func)(void *ctx, size_t count,
  77                                 void *c),
  78                                 void *ctx);
  79
  80 /**
  81  *      marshal_string - Output a string as a byte stream
  82  *      @putchar_func: The function to put the next character to the stream
  83  *      @ctx: A pointer to the context structure for putchar_func.
  84  *      @string: The string to output.
  85  *
  86  *      Takes a string and marshals it to a byte stream - writes a 32 bit size
  87  *      of the forthcoming data in network byte order and then the string.
  88  */
  89 void marshal_string(int (*putchar_func)(void *ctx, size_t count,
  90                                 void *c),
  91                                 void *ctx,
  92                                 const char *string);
  93
  94 /**
  95  *      unmarshal_string - Turn a byte stream into a string
  96  *      @getchar_func: The function to get the next character from the stream
  97  *      @ctx: A pointer to the context structure for getchar_func.
  98  *
  99  *      Returns a string which is the unmarshalled result of the input byte
 100  *      stream - ie the inverse of marshal_string.
 101  */
 102 char *unmarshal_string(int (*getchar_func)(void *ctx, size_t count,
 103                                 void *c),
 104                                 void *ctx);
 105
 106 /**
 107  *      marshal_array - Outputs an array as a byte stream
 108  *      @putchar_func: The function to put the next character to the stream
 109  *      @ctx: A pointer to the context structure for putchar_func.
 110  *      @marshal_func: The function to use to marshal each array element.
 111  *      @array: A pointer to the array to marshal
 112  *      @size:: The number of elements in the array.
 113  *
 114  *      Takes an array and marshals it into a byte stream. Outputs a 32 bit
 115  *      count of the elements in the array in network byte order and then
 116  *      calls marshal_func for each element in the array to provide the
 117  *      marshalled contents.
 118  */
 119 void marshal_array(int (*putchar_func)(void *ctx, size_t count,
 120                                 void *c),
 121                                 void *ctx,
 122                                 void (*marshal_func)(int
 123                                         (*putchar_func)(void *ctx,
 124                                                 size_t count, void *c),
 125                                         void *ctx, const void *item),
 126                                 void **array,
 127                                 int size);
 128
 129 /**
 130  *      unmarshal_array - Turn a byte stream into an array of elements
 131  *      @getchar_func: The function to get the next character from the stream
 132  *      @ctx: A pointer to the context structure for getchar_func.
 133  *      @unmarshal_func: The function to use to unmarshal each array element.
 134  *      @size: A pointer to where to store the number of elements unmarshalled
 135  *
 136  *      Takes a byte stream and unmarshals it into an array of elements,
 137  *      as determined by the supplied unmarshal_func function. ie the reverse
 138  *      of marshal_array.
 139  */
 140 void **unmarshal_array(int (*getchar_func)(void *ctx, size_t count,
 141                                 void *c),
 142                                 void *ctx,
 143                                 void *(*unmarshal_func)(int
 144                                         (*getchar_func)(void *ctx,
 145                                                 size_t count, void *c),
 146                                         void *ctx),
 147                                 int *size);
 148
 149 #endif /* __MARSHAL_H__ */