chiark - git - mdw - catacomb/blob - key-data.h

   1 /* -*-c-*-
   2  *
   3  * $Id: key-data.h,v 1.1 2000/02/12 18:21:23 mdw Exp $
   4  *
   5  * Manipulating key data
   6  *
   7  * (c) 1999 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  14  * Catacomb is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * Catacomb is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with Catacomb; if not, write to the Free
  26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: key-data.h,v $
  33  * Revision 1.1  2000/02/12 18:21:23  mdw
  34  * Overhaul of key management (again).
  35  *
  36  */
  37
  38 #ifndef CATACOMB_KEY_DATA_H
  39 #define CATACOMB_KEY_DATA_H
  40
  41 #ifdef __cplusplus
  42   extern "C" {
  43 #endif
  44
  45 /*----- Header files ------------------------------------------------------*/
  46
  47 #include <stddef.h>
  48
  49 #include <mLib/bits.h>
  50 #include <mLib/dstr.h>
  51 #include <mLib/sym.h>
  52
  53 #ifndef CATACOMB_MP_H
  54 #  include "mp.h"
  55 #endif
  56
  57 /*----- Data structures ---------------------------------------------------*/
  58
  59 /* --- Key binary data --- */
  60
  61 typedef struct key_bin {
  62   octet *k;                             /* Pointer to key data */
  63   size_t sz;                            /* Size of the key data (in bytes) */
  64 } key_bin;
  65
  66 /* --- Key data structure --- */
  67
  68 typedef struct key_data {
  69   unsigned e;                           /* Encoding type for key data */
  70   union {
  71     key_bin k;                          /* Binary key data */
  72     mp *m;                              /* Multiprecision integer */
  73     sym_table s;                        /* Structured key data */
  74   } u;
  75 } key_data;
  76
  77 typedef struct key_struct {
  78   sym_base _b;
  79   key_data k;
  80 } key_struct;
  81
  82 /* --- Key binary encoding --- *
  83  *
  84  * The binary encoding consists of a header containing a 16-bit encoding type
  85  * and a 16-bit length, followed immediately by the key data, followed by
  86  * between zero and three zero bytes to make the total length a multiple of
  87  * four.  The format of the following data depends on the encoding type:
  88  *
  89  * @KENC_BINARY@        Binary data.
  90  *
  91  * @KENC_MP@            Octet array interpreted in big-endian byte order.
  92  *
  93  * @KENC_STRUCT@        An array of pairs, each containing a string (8-bit
  94  *                      length followed by data and zero-padding to 4-byte
  95  *                      boundary) and key binary encodings.
  96  *
  97  * @KENC_ENCRYPT@       Binary data, format
  98  */
  99
 100 /* --- Key encoding methods and other flags--- */
 101
 102 enum {
 103
 104   /* --- Bottom two bits are the encoding type --- */
 105
 106   KF_ENCMASK    = 0x03,                 /* Encoding mask */
 107   KENC_BINARY   = 0x00,                 /* Plain binary key (@k@) */
 108   KENC_MP       = 0x01,                 /* Multiprecision integer (@i@) */
 109   KENC_STRUCT   = 0x02,                 /* Structured key data (@s@) */
 110   KENC_ENCRYPT  = 0x03,                 /* Encrypted key type (@k@) */
 111
 112   /* --- Key category bits --- */
 113
 114   KF_CATMASK    = 0x0c,                 /* Category mask */
 115   KCAT_SYMM     = 0x00,                 /* Symmetric encryption key */
 116   KCAT_PRIV     = 0x04,                 /* Private (asymmetric) key */
 117   KCAT_PUB      = 0x08,                 /* Public (asymmetric) key */
 118   KCAT_SHARE    = 0x0c,                 /* Shared (asymmetric) key */
 119   KF_NONSECRET  = 0x08,                 /* Bit flag for non-secret keys */
 120
 121   /* --- Other flags --- */
 122
 123   KF_BURN       = 0x10,                 /* Burn key after use */
 124   KF_TEMP       = 0x20,                 /* Temporary copy flag */
 125
 126   /* --- Tag end --- */
 127
 128   KENC_MAX                              /* Dummy limit constant */
 129 };
 130
 131 /* --- Key flag filtering --- */
 132
 133 typedef struct key_filter {
 134   unsigned f;
 135   unsigned m;
 136 } key_filter;
 137
 138 /* --- Matching aginst key selection --- */
 139
 140 #define KEY_MATCH(kd, kf)                                               \
 141   (!(kf) ||                                                             \
 142    ((kd)->e & KF_ENCMASK) == KENC_STRUCT ||                             \
 143    ((kd)->e & (kf)->m) == (kf)->f)
 144
 145 /*----- Key flags and filtering -------------------------------------------*/
 146
 147 /* --- @key_readflags@ --- *
 148  *
 149  * Arguments:   @const char *p@ = pointer to string to read
 150  *              @char **pp@ = where to store the end pointer
 151  *              @unsigned *ff@ = where to store the flags
 152  *              @unsigned *mm@ = where to store the mask
 153  *
 154  * Returns:     Zero if all went well, nonzero if there was an error.
 155  *
 156  * Use:         Reads a flag string.
 157  */
 158
 159 extern int key_readflags(const char */*p*/, char **/*pp*/,
 160                          unsigned */*ff*/, unsigned */*mm*/);
 161
 162 /* --- @key_writeflags@ --- *
 163  *
 164  * Arguments:   @unsigned f@ = flags to write
 165  *              @dstr *d@ = pointer to destination string
 166  *
 167  * Returns:     ---
 168  *
 169  * Use:         Emits a flags word as a string representation.
 170  */
 171
 172 extern void key_writeflags(unsigned /*f*/, dstr */*d*/);
 173
 174 /* --- @key_match@ --- *
 175  *
 176  * Arguments:   @key_data *k@ = pointer to key data block
 177  *              @const key_filter *kf@ = pointer to filter block
 178  *
 179  * Returns:     Nonzero if the key matches the filter.
 180  *
 181  * Use:         Checks whether a key matches a filter.
 182  */
 183
 184 extern int key_match(key_data */*k*/, const key_filter */*kf*/);
 185
 186 /*----- Setting new key data ----------------------------------------------*/
 187
 188 /* --- @key_binary@ --- *
 189  *
 190  * Arguments:   @key_data *k@ = pointer to key data block
 191  *              @const void *p@ = pointer to key data
 192  *              @size_t sz@ = size of the key data
 193  *
 194  * Returns:     ---
 195  *
 196  * Use:         Sets a binary key in a key data block.
 197  */
 198
 199 extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/);
 200
 201 /* --- @key_encrypted@ --- *
 202  *
 203  * Arguments:   @key_data *k@ = pointer to key data block
 204  *              @const void *p@ = pointer to key data
 205  *              @size_t sz@ = size of the key data
 206  *
 207  * Returns:     ---
 208  *
 209  * Use:         Sets an encrypted key in a key data block.
 210  */
 211
 212 extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/);
 213
 214 /* --- @key_mp@ --- *
 215  *
 216  * Arguments:   @key_data *k@ = pointer to key data block
 217  *              @mp *m@ = pointer to the value to set
 218  *
 219  * Returns:     ---
 220  *
 221  * Use:         Sets a multiprecision integer key in a key block.
 222  */
 223
 224 extern void key_mp(key_data */*k*/, mp */*m*/);
 225
 226 /* --- @key_structure@ --- *
 227  *
 228  * Arguments:   @key_data *k@ = pointer to key data block
 229  *
 230  * Returns:     ---
 231  *
 232  * Use:         Initializes a structured key type.
 233  */
 234
 235 extern void key_structure(key_data */*k*/);
 236
 237 /* --- @key_structfind@ --- *
 238  *
 239  * Arguments:   @key_data *k@ = pointer to key data block
 240  *              @const char *tag@ = pointer to tag string
 241  *
 242  * Returns:     Pointer to key data block, or null.
 243  *
 244  * Use:         Looks up the tag in a structured key.
 245  */
 246
 247 extern key_data *key_structfind(key_data */*k*/, const char */*tag*/);
 248
 249 /* --- @key_structcreate@ --- *
 250  *
 251  * Arguments:   @key_data *k@ = pointer to key data block
 252  *              @const char *tag@ = pointer to tag string
 253  *
 254  * Returns:     Pointer to newly created key data.
 255  *
 256  * Use:         Creates a new uninitialized subkey.
 257  */
 258
 259 extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/);
 260
 261 /*----- Miscellaneous operations ------------------------------------------*/
 262
 263 /* --- @key_destroy@ --- *
 264  *
 265  * Arguments:   @key_data *k@ = pointer to key data to destroy
 266  *
 267  * Returns:     ---
 268  *
 269  * Use:         Destroys a lump of key data.
 270  */
 271
 272 extern void key_destroy(key_data */*k*/);
 273
 274 /* --- @key_do@ --- *
 275  *
 276  * Arguments:   @key_data *k@ = pointer to key data block
 277  *              @const key_filter *kf@ = pointer to filter block
 278  *              @dstr *d@ = pointer to base string
 279  *              @int (*func)(key_data *kd, dstr *d, void *p@ = function
 280  *              @void *p@ = argument to function
 281  *
 282  * Returns:     Nonzero return code from function, or zero.
 283  *
 284  * Use:         Runs a function over all the leaves of a key.
 285  */
 286
 287 extern int key_do(key_data */*k*/, const key_filter */*kf*/, dstr */*d*/,
 288                   int (*/*func*/)(key_data */*kd*/,
 289                                   dstr */*d*/, void */*p*/),
 290                   void */*p*/);
 291
 292 /* --- @key_copy@ --- *
 293  *
 294  * Arguments:   @key_data *kd@ = pointer to destination data block
 295  *              @key_data *k@ = pointer to source data block
 296  *              @const key_filter *kf@ = pointer to filter block
 297  *
 298  * Returns:     Nonzero if an item was actually copied.
 299  *
 300  * Use:         Copies a chunk of key data from one place to another.
 301  */
 302
 303 extern int key_copy(key_data */*kd*/, key_data */*k*/,
 304                     const key_filter */*kf*/);
 305
 306 /*----- Textual encoding --------------------------------------------------*/
 307
 308 /* --- @key_read@ --- *
 309  *
 310  * Arguments:   @const char *p@ = pointer to textual key representation
 311  *              @key_data *k@ = pointer to output block for key data
 312  *              @char **pp@ = where to store the end pointer
 313  *
 314  * Returns:     Zero if all went well, nonzero if there was a problem.
 315  *
 316  * Use:         Parses a textual key description.
 317  */
 318
 319 extern int key_read(const char */*p*/, key_data */*k*/, char **/*pp*/);
 320
 321 /* --- @key_write@ --- *
 322  *
 323  * Arguments:   @key_data *k@ = pointer to key data
 324  *              @dstr *d@ = destination string to write on
 325  *              @const key_filter *kf@ = pointer to key selection block
 326  *
 327  * Returns:     Nonzero if any items were actually written.
 328  *
 329  * Use:         Writes a key in a textual encoding.
 330  */
 331
 332 extern int key_write(key_data */*k*/, dstr */*d*/,
 333                       const key_filter */*kf*/);
 334
 335 /*----- Key binary encoding -----------------------------------------------*/
 336
 337 /* --- @key_decode@ --- *
 338  *
 339  * Arguments:   @const void *p@ = pointer to buffer to read
 340  *              @size_t sz@ = size of the buffer
 341  *              @key_data *k@ = pointer to key data block to write to
 342  *
 343  * Returns:     Zero if everything worked, nonzero otherwise.
 344  *
 345  * Use:         Decodes a binary representation of a key.
 346  */
 347
 348 extern int key_decode(const void */*p*/, size_t /*sz*/, key_data */*k*/);
 349
 350 /* --- @key_encode@ --- *
 351  *
 352  * Arguments:   @key_data *k@ = pointer to key data block
 353  *              @dstr *d@ = pointer to destination string
 354  *              @const key_filter *kf@ = pointer to key selection block
 355  *
 356  * Returns:     Nonzero if any items were actually written.
 357  *
 358  * Use:         Encodes a key block as binary data.
 359  */
 360
 361 extern int key_encode(key_data */*k*/, dstr */*d*/,
 362                       const key_filter */*kf*/);
 363
 364 /*----- Passphrase encryption ---------------------------------------------*/
 365
 366 /* --- @key_plock@ --- *
 367  *
 368  * Arguments:   @const char *tag@ = tag to use for passphrase
 369  *              @key_data *k@ = source key data block
 370  *              @key_data *kt@ = target key data block
 371  *
 372  * Returns:     Zero if successful, nonzero if there was a problem.
 373  *
 374  * Use:         Locks a key by encrypting it with a passphrase.
 375  */
 376
 377 extern int key_plock(const char */*tag*/, key_data */*k*/, key_data */*kt*/);
 378
 379 /* --- @key_punlock@ --- *
 380  *
 381  * Arguments:   @const char *tag@ = tag to use for passphrase
 382  *              @key_data *k@ = source key data block
 383  *              @key_data *kt@ = target key data block
 384  *
 385  * Returns:     Zero if it worked, nonzero if it didn't.
 386  *
 387  * Use:         Unlocks a passphrase-locked key.
 388  */
 389
 390 extern int key_punlock(const char */*tag*/,
 391                        key_data */*k*/, key_data */*kt*/);
 392
 393 /*----- That's all, folks -------------------------------------------------*/
 394
 395 #ifdef __cplusplus
 396   }
 397 #endif
 398
 399 #endif