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

   1 /* -*-c-*-
   2  *
   3  * $Id$
   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 #ifndef CATACOMB_KEY_DATA_H
  31 #define CATACOMB_KEY_DATA_H
  32
  33 #ifdef __cplusplus
  34   extern "C" {
  35 #endif
  36
  37 /*----- Header files ------------------------------------------------------*/
  38
  39 #include <stddef.h>
  40
  41 #include <mLib/bits.h>
  42 #include <mLib/dstr.h>
  43 #include <mLib/sym.h>
  44
  45 #ifndef CATACOMB_KEY_ERROR_H
  46 #  include "key-error.h"
  47 #endif
  48
  49 #ifndef CATACOMB_MP_H
  50 #  include "mp.h"
  51 #endif
  52
  53 #ifndef CATACOMB_EC_H
  54 #  include "ec.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     char *p;                            /* String pointer */
  75     ec e;                               /* Elliptic curve point */
  76   } u;
  77 } key_data;
  78
  79 typedef struct key_struct {
  80   sym_base _b;
  81   key_data k;
  82 } key_struct;
  83
  84 /* --- Packing and unpacking --- */
  85
  86 typedef struct key_packdef {
  87   void *p;                              /* Pointer to the destination */
  88   key_data kd;                          /* Key data block */
  89 } key_packdef;
  90
  91 typedef struct key_packstruct {
  92   char *name;                           /* Pointer to name string */
  93   key_packdef kp;                       /* Packing structure */
  94 } key_packstruct;
  95
  96 /* --- Key binary encoding --- *
  97  *
  98  * The binary encoding consists of a header containing a 16-bit encoding type
  99  * and a 16-bit length, followed immediately by the key data, followed by
 100  * between zero and three zero bytes to make the total length a multiple of
 101  * four.  The format of the following data depends on the encoding type:
 102  *
 103  * @KENC_BINARY@        Binary data.
 104  *
 105  * @KENC_MP@            Octet array interpreted in big-endian byte order.
 106  *
 107  * @KENC_STRUCT@        An array of pairs, each containing a string (8-bit
 108  *                      length followed by data and zero-padding to 4-byte
 109  *                      boundary) and key binary encodings.
 110  *
 111  * @KENC_ENCRYPT@       Binary data, format
 112  */
 113
 114 /* --- Key encoding methods and other flags--- */
 115
 116 enum {
 117
 118   /* --- Bottom two bits are the encoding type --- */
 119
 120   KF_ENCMASK    = 0x83,                 /* Encoding mask */
 121   KENC_BINARY   = 0x00,                 /* Plain binary key (@k@) */
 122   KENC_MP       = 0x01,                 /* Multiprecision integer (@i@) */
 123   KENC_STRUCT   = 0x02,                 /* Structured key data (@s@) */
 124   KENC_ENCRYPT  = 0x03,                 /* Encrypted key type (@k@) */
 125   KENC_STRING   = 0x80,                 /* ASCII string (@p@) */
 126   KENC_EC       = 0x81,                 /* Elliptic curve point (@e@) */
 127
 128   /* --- Key category bits --- */
 129
 130   KF_CATMASK    = 0x0c,                 /* Category mask */
 131   KCAT_SYMM     = 0x00,                 /* Symmetric encryption key */
 132   KCAT_PRIV     = 0x04,                 /* Private (asymmetric) key */
 133   KCAT_PUB      = 0x08,                 /* Public (asymmetric) key */
 134   KCAT_SHARE    = 0x0c,                 /* Shared (asymmetric) key */
 135   KF_NONSECRET  = 0x08,                 /* Bit flag for non-secret keys */
 136
 137   /* --- Other flags --- */
 138
 139   KF_BURN       = 0x10,                 /* Burn key after use */
 140   KF_TEMP       = 0x20,                 /* Temporary copy flag */
 141   KF_OPT        = 0x40,                 /* Optional key (for @key_unpack@) */
 142
 143   /* --- Tag end --- */
 144
 145   KENC_MAX                              /* Dummy limit constant */
 146 };
 147
 148 /* --- Key locking return codes --- */
 149
 150 #define KL_OK 0                         /* All good */
 151 #define KL_IOERR -1                     /* I/O problem (e.g., getting pp) */
 152 #define KL_KEYERR -2                    /* Wrong key supplied */
 153 #define KL_DATAERR -3                   /* Data format error */
 154
 155 /* --- Key flag filtering --- */
 156
 157 typedef struct key_filter {
 158   unsigned f;
 159   unsigned m;
 160 } key_filter;
 161
 162 /* --- Matching aginst key selection --- */
 163
 164 #define KEY_MATCH(kd, kf)                                               \
 165   (!(kf) ||                                                             \
 166    ((kd)->e & KF_ENCMASK) == KENC_STRUCT ||                             \
 167    ((kd)->e & (kf)->m) == (kf)->f)
 168
 169 /*----- Key flags and filtering -------------------------------------------*/
 170
 171 /* --- @key_readflags@ --- *
 172  *
 173  * Arguments:   @const char *p@ = pointer to string to read
 174  *              @char **pp@ = where to store the end pointer
 175  *              @unsigned *ff@ = where to store the flags
 176  *              @unsigned *mm@ = where to store the mask
 177  *
 178  * Returns:     Zero if all went well, nonzero if there was an error.
 179  *
 180  * Use:         Reads a flag string.
 181  */
 182
 183 extern int key_readflags(const char */*p*/, char **/*pp*/,
 184                          unsigned */*ff*/, unsigned */*mm*/);
 185
 186 /* --- @key_writeflags@ --- *
 187  *
 188  * Arguments:   @unsigned f@ = flags to write
 189  *              @dstr *d@ = pointer to destination string
 190  *
 191  * Returns:     ---
 192  *
 193  * Use:         Emits a flags word as a string representation.
 194  */
 195
 196 extern void key_writeflags(unsigned /*f*/, dstr */*d*/);
 197
 198 /* --- @key_match@ --- *
 199  *
 200  * Arguments:   @key_data *k@ = pointer to key data block
 201  *              @const key_filter *kf@ = pointer to filter block
 202  *
 203  * Returns:     Nonzero if the key matches the filter.
 204  *
 205  * Use:         Checks whether a key matches a filter.
 206  */
 207
 208 extern int key_match(key_data */*k*/, const key_filter */*kf*/);
 209
 210 /*----- Setting new key data ----------------------------------------------*/
 211
 212 /* --- @key_binary@ --- *
 213  *
 214  * Arguments:   @key_data *k@ = pointer to key data block
 215  *              @const void *p@ = pointer to key data
 216  *              @size_t sz@ = size of the key data
 217  *
 218  * Returns:     ---
 219  *
 220  * Use:         Sets a binary key in a key data block.
 221  */
 222
 223 extern void key_binary(key_data */*k*/, const void */*p*/, size_t /*sz*/);
 224
 225 /* --- @key_encrypted@ --- *
 226  *
 227  * Arguments:   @key_data *k@ = pointer to key data block
 228  *              @const void *p@ = pointer to key data
 229  *              @size_t sz@ = size of the key data
 230  *
 231  * Returns:     ---
 232  *
 233  * Use:         Sets an encrypted key in a key data block.
 234  */
 235
 236 extern void key_encrypted(key_data */*k*/, const void */*p*/, size_t /*sz*/);
 237
 238 /* --- @key_mp@ --- *
 239  *
 240  * Arguments:   @key_data *k@ = pointer to key data block
 241  *              @mp *m@ = pointer to the value to set
 242  *
 243  * Returns:     ---
 244  *
 245  * Use:         Sets a multiprecision integer key in a key block.
 246  */
 247
 248 extern void key_mp(key_data */*k*/, mp */*m*/);
 249
 250 /* --- @key_string@ --- *
 251  *
 252  * Arguments:   @key_data *k@ = pointer to key data block
 253  *              @const char *p@ = pointer to the value to set
 254  *
 255  * Returns:     ---
 256  *
 257  * Use:         Sets a plain string in a key block.
 258  */
 259
 260 extern void key_string(key_data */*k*/, const char */*p*/);
 261
 262 /* --- @key_ec@ --- *
 263  *
 264  * Arguments:   @key_data *k@ = pointer to key data block
 265  *              @const ec *e@ = pointer to the value to set
 266  *
 267  * Returns:     ---
 268  *
 269  * Use:         Sets an elliptic curve point in a key block.
 270  */
 271
 272 extern void key_ec(key_data */*k*/, const ec */*e*/);
 273
 274 /* --- @key_structure@ --- *
 275  *
 276  * Arguments:   @key_data *k@ = pointer to key data block
 277  *
 278  * Returns:     ---
 279  *
 280  * Use:         Initializes a structured key type.
 281  */
 282
 283 extern void key_structure(key_data */*k*/);
 284
 285 /* --- @key_structfind@ --- *
 286  *
 287  * Arguments:   @key_data *k@ = pointer to key data block
 288  *              @const char *tag@ = pointer to tag string
 289  *
 290  * Returns:     Pointer to key data block, or null.
 291  *
 292  * Use:         Looks up the tag in a structured key.
 293  */
 294
 295 extern key_data *key_structfind(key_data */*k*/, const char */*tag*/);
 296
 297 /* --- @key_structcreate@ --- *
 298  *
 299  * Arguments:   @key_data *k@ = pointer to key data block
 300  *              @const char *tag@ = pointer to tag string
 301  *
 302  * Returns:     Pointer to newly created key data.
 303  *
 304  * Use:         Creates a new uninitialized subkey.
 305  */
 306
 307 extern key_data *key_structcreate(key_data */*k*/, const char */*tag*/);
 308
 309 /*----- Miscellaneous operations ------------------------------------------*/
 310
 311 /* --- @key_destroy@ --- *
 312  *
 313  * Arguments:   @key_data *k@ = pointer to key data to destroy
 314  *
 315  * Returns:     ---
 316  *
 317  * Use:         Destroys a lump of key data.
 318  */
 319
 320 extern void key_destroy(key_data */*k*/);
 321
 322 /* --- @key_do@ --- *
 323  *
 324  * Arguments:   @key_data *k@ = pointer to key data block
 325  *              @const key_filter *kf@ = pointer to filter block
 326  *              @dstr *d@ = pointer to base string
 327  *              @int (*func)(key_data *kd, dstr *d, void *p@ = function
 328  *              @void *p@ = argument to function
 329  *
 330  * Returns:     Nonzero return code from function, or zero.
 331  *
 332  * Use:         Runs a function over all the leaves of a key.
 333  */
 334
 335 extern int key_do(key_data */*k*/, const key_filter */*kf*/, dstr */*d*/,
 336                   int (*/*func*/)(key_data */*kd*/,
 337                                   dstr */*d*/, void */*p*/),
 338                   void */*p*/);
 339
 340 /* --- @key_copy@ --- *
 341  *
 342  * Arguments:   @key_data *kd@ = pointer to destination data block
 343  *              @key_data *k@ = pointer to source data block
 344  *              @const key_filter *kf@ = pointer to filter block
 345  *
 346  * Returns:     Nonzero if an item was actually copied.
 347  *
 348  * Use:         Copies a chunk of key data from one place to another.
 349  */
 350
 351 extern int key_copy(key_data */*kd*/, key_data */*k*/,
 352                     const key_filter */*kf*/);
 353
 354 /*----- Textual encoding --------------------------------------------------*/
 355
 356 /* --- @key_read@ --- *
 357  *
 358  * Arguments:   @const char *p@ = pointer to textual key representation
 359  *              @key_data *k@ = pointer to output block for key data
 360  *              @char **pp@ = where to store the end pointer
 361  *
 362  * Returns:     Zero if all went well, nonzero if there was a problem.
 363  *
 364  * Use:         Parses a textual key description.
 365  */
 366
 367 extern int key_read(const char */*p*/, key_data */*k*/, char **/*pp*/);
 368
 369 /* --- @key_write@ --- *
 370  *
 371  * Arguments:   @key_data *k@ = pointer to key data
 372  *              @dstr *d@ = destination string to write on
 373  *              @const key_filter *kf@ = pointer to key selection block
 374  *
 375  * Returns:     Nonzero if any items were actually written.
 376  *
 377  * Use:         Writes a key in a textual encoding.
 378  */
 379
 380 extern int key_write(key_data */*k*/, dstr */*d*/,
 381                      const key_filter */*kf*/);
 382
 383 /*----- Key binary encoding -----------------------------------------------*/
 384
 385 /* --- @key_decode@ --- *
 386  *
 387  * Arguments:   @const void *p@ = pointer to buffer to read
 388  *              @size_t sz@ = size of the buffer
 389  *              @key_data *k@ = pointer to key data block to write to
 390  *
 391  * Returns:     Zero if everything worked, nonzero otherwise.
 392  *
 393  * Use:         Decodes a binary representation of a key.
 394  */
 395
 396 extern int key_decode(const void */*p*/, size_t /*sz*/, key_data */*k*/);
 397
 398 /* --- @key_encode@ --- *
 399  *
 400  * Arguments:   @key_data *k@ = pointer to key data block
 401  *              @dstr *d@ = pointer to destination string
 402  *              @const key_filter *kf@ = pointer to key selection block
 403  *
 404  * Returns:     Nonzero if any items were actually written.
 405  *
 406  * Use:         Encodes a key block as binary data.
 407  */
 408
 409 extern int key_encode(key_data */*k*/, dstr */*d*/,
 410                       const key_filter */*kf*/);
 411
 412 /*----- Packing and unpacking keys ----------------------------------------*/
 413
 414 /* --- @key_pack@ --- *
 415  *
 416  * Arguments:   @key_packdef *kp@ = pointer to packing structure
 417  *              @key_data *kd@ = pointer to destination key data
 418  *              @dstr *d@ = pointer to tag string for the key data
 419  *
 420  * Returns:     Error code, or zero.
 421  *
 422  * Use:         Packs a key from a data structure.
 423  */
 424
 425 extern int key_pack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/);
 426
 427 /* --- @key_unpack@ --- *
 428  *
 429  * Arguments:   @key_packdef *kp@ = pointer to packing structure
 430  *              @key_data *kd@ = pointer to source key data
 431  *              @dstr *d@ = pointer to tag string for the key data
 432  *
 433  * Returns:     Error code, or zero.
 434  *
 435  * Use:         Unpacks a key into an appropriate data structure.
 436  */
 437
 438 extern int key_unpack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/);
 439
 440 /* --- @key_unpackdone@ --- *
 441  *
 442  * Arguments:   @key_packdef *kp@ = pointer to packing definition
 443  *
 444  * Returns:     ---
 445  *
 446  * Use:         Frees the key components contained within a packing
 447  *              definition, created during key unpacking.
 448  */
 449
 450 extern void key_unpackdone(key_packdef */*kp*/);
 451
 452 /*----- Key encryption ----------------------------------------------------*/
 453
 454 /* --- @key_lock@ --- *
 455  *
 456  * Arguments:   @key_data *kt@ = destination block
 457  *              @key_data *k@ = source key data block
 458  *              @const void *e@ = secret to encrypt key with
 459  *              @size_t esz@ = size of the secret
 460  *
 461  * Returns:     ---
 462  *
 463  * Use:         Encrypts a key data block using a secret.
 464  */
 465
 466 extern void key_lock(key_data */*kt*/, key_data */*k*/,
 467                      const void */*e*/, size_t /*esz*/);
 468
 469 /* --- @key_unlock@ --- *
 470  *
 471  * Arguments:   @key_data *kt@ = target block
 472  *              @key_data *k@ = source key data block
 473  *              @const void *e@ = secret to decrypt the block with
 474  *              @size_t esz@ = size of the secret
 475  *
 476  * Returns:     Zero for success, or a @KERR_@ error code.
 477  *
 478  * Use:         Unlocks a key using a secret.
 479  */
 480
 481 extern int key_unlock(key_data */*kt*/, key_data */*k*/,
 482                       const void */*e*/, size_t /*esz*/);
 483
 484 /* --- @key_plock@ --- *
 485  *
 486  * Arguments:   @const char *tag@ = tag to use for passphrase
 487  *              @key_data *k@ = source key data block
 488  *              @key_data *kt@ = target key data block
 489  *
 490  * Returns:     Zero if successful, a @KERR@ error code on failure.
 491  *
 492  * Use:         Locks a key by encrypting it with a passphrase.
 493  */
 494
 495 extern int key_plock(const char */*tag*/, key_data */*k*/, key_data */*kt*/);
 496
 497 /* --- @key_punlock@ --- *
 498  *
 499  * Arguments:   @const char *tag@ = tag to use for passphrase
 500  *              @key_data *k@ = source key data block
 501  *              @key_data *kt@ = target key data block
 502  *
 503  * Returns:     Zero if successful, a @KERR@ error code on failure.
 504  *
 505  * Use:         Unlocks a passphrase-locked key.
 506  */
 507
 508 extern int key_punlock(const char */*tag*/,
 509                        key_data */*k*/, key_data */*kt*/);
 510
 511 /*----- That's all, folks -------------------------------------------------*/
 512
 513 #ifdef __cplusplus
 514   }
 515 #endif
 516
 517 #endif