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

   1 /* -*-c-*-
   2  *
   3  * Manipulating key data
   4  *
   5  * (c) 1999 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef CATACOMB_KEY_DATA_H
  29 #define CATACOMB_KEY_DATA_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <stddef.h>
  38
  39 #include <mLib/bits.h>
  40 #include <mLib/dstr.h>
  41 #include <mLib/macros.h>
  42 #include <mLib/sym.h>
  43
  44 #ifndef CATACOMB_KEY_ERROR_H
  45 #  include "key-error.h"
  46 #endif
  47
  48 #ifndef CATACOMB_MP_H
  49 #  include "mp.h"
  50 #endif
  51
  52 #ifndef CATACOMB_EC_H
  53 #  include "ec.h"
  54 #endif
  55
  56 /*----- Data structures ---------------------------------------------------*/
  57
  58 /* --- Key binary data --- */
  59
  60 typedef struct key_bin {
  61   octet *k;                             /* Pointer to key data */
  62   size_t sz;                            /* Size of the key data (in bytes) */
  63 } key_bin;
  64
  65 /* --- Key data structure --- */
  66
  67 typedef struct key_data {
  68   unsigned e;                           /* Encoding type for key data */
  69   unsigned ref;                         /* Reference counter */
  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 typedef struct key_subkeyiter { sym_iter i; } key_subkeyiter;
  85
  86 /* --- Packing and unpacking --- */
  87
  88 typedef struct key_packdef {
  89   unsigned e;                           /* Key data encoding type */
  90   void *p;                              /* Pointer to the destination */
  91   key_data *kd;                         /* Key data block */
  92 } key_packdef;
  93
  94 typedef struct key_packstruct {
  95   char *name;                           /* Pointer to name string */
  96   key_packdef kp;                       /* Packing structure */
  97 } key_packstruct;
  98
  99 /* --- Key binary encoding --- *
 100  *
 101  * The binary encoding consists of a header containing a 16-bit encoding type
 102  * and a 16-bit length, followed immediately by the key data, followed by
 103  * between zero and three zero bytes to make the total length a multiple of
 104  * four.  The format of the following data depends on the encoding type:
 105  *
 106  * @KENC_BINARY@        Binary data.
 107  *
 108  * @KENC_MP@            Octet array interpreted in big-endian byte order.
 109  *
 110  * @KENC_STRUCT@        An array of pairs, each containing a string (8-bit
 111  *                      length followed by data and zero-padding to 4-byte
 112  *                      boundary) and key binary encodings.
 113  *
 114  * @KENC_ENCRYPT@       Binary data, format
 115  */
 116
 117 /* --- Key encoding methods and other flags--- */
 118
 119 enum {
 120
 121   /* --- Bottom two bits are the encoding type --- */
 122
 123   KF_ENCMASK    = 0x83,                 /* Encoding mask */
 124   KENC_BINARY   = 0x00,                 /* Plain binary key (@k@) */
 125   KENC_MP       = 0x01,                 /* Multiprecision integer (@i@) */
 126   KENC_STRUCT   = 0x02,                 /* Structured key data (@s@) */
 127   KENC_ENCRYPT  = 0x03,                 /* Encrypted key type (@k@) */
 128   KENC_STRING   = 0x80,                 /* ASCII string (@p@) */
 129   KENC_EC       = 0x81,                 /* Elliptic curve point (@e@) */
 130
 131   /* --- Key category bits --- */
 132
 133   KF_CATMASK    = 0x0c,                 /* Category mask */
 134   KCAT_SYMM     = 0x00,                 /* Symmetric encryption key */
 135   KCAT_PRIV     = 0x04,                 /* Private (asymmetric) key */
 136   KCAT_PUB      = 0x08,                 /* Public (asymmetric) key */
 137   KCAT_SHARE    = 0x0c,                 /* Shared (asymmetric) key */
 138   KF_NONSECRET  = 0x08,                 /* Bit flag for non-secret keys */
 139
 140   /* --- Other flags --- */
 141
 142   KF_BURN       = 0x10,                 /* Burn key after use */
 143   KF_OPT        = 0x20,                 /* Optional key (for @key_unpack@) */
 144
 145   /* --- Tag end --- */
 146
 147   KENC_MAX                              /* Dummy limit constant */
 148 };
 149
 150 /* --- Key locking return codes --- */
 151
 152 #define KL_OK 0                         /* All good */
 153 #define KL_IOERR -1                     /* I/O problem (e.g., getting pp) */
 154 #define KL_KEYERR -2                    /* Wrong key supplied */
 155 #define KL_DATAERR -3                   /* Data format error */
 156
 157 /* --- Key flag filtering --- */
 158
 159 typedef struct key_filter {
 160   unsigned f;
 161   unsigned m;
 162 } key_filter;
 163
 164 /* --- Matching aginst key selection --- */
 165
 166 #define KEY_MATCH(kd, kf)                                               \
 167   (MUFFLE_WARNINGS_EXPR(GCC_WARNING("-Waddress"), !(kf)) ||             \
 168    ((kd)->e & KF_ENCMASK) == KENC_STRUCT ||                             \
 169    ((kd)->e & (kf)->m) == (kf)->f)
 170
 171 /*----- Key flags and filtering -------------------------------------------*/
 172
 173 /* --- @key_readflags@ --- *
 174  *
 175  * Arguments:   @const char *p@ = pointer to string to read
 176  *              @char **pp@ = where to store the end pointer
 177  *              @unsigned *ff@ = where to store the flags
 178  *              @unsigned *mm@ = where to store the mask
 179  *
 180  * Returns:     Zero if all went well, nonzero if there was an error.
 181  *
 182  * Use:         Reads a flag string.
 183  */
 184
 185 extern int key_readflags(const char */*p*/, char **/*pp*/,
 186                          unsigned */*ff*/, unsigned */*mm*/);
 187
 188 /* --- @key_writeflags@ --- *
 189  *
 190  * Arguments:   @unsigned f@ = flags to write
 191  *              @dstr *d@ = pointer to destination string
 192  *
 193  * Returns:     ---
 194  *
 195  * Use:         Emits a flags word as a string representation.
 196  */
 197
 198 extern void key_writeflags(unsigned /*f*/, dstr */*d*/);
 199
 200 /* --- @key_match@ --- *
 201  *
 202  * Arguments:   @key_data *k@ = pointer to key data block
 203  *              @const key_filter *kf@ = pointer to filter block
 204  *
 205  * Returns:     Nonzero if the key matches the filter.
 206  *
 207  * Use:         Checks whether a key matches a filter.
 208  */
 209
 210 extern int key_match(key_data */*k*/, const key_filter */*kf*/);
 211
 212 /*----- Setting new key data ----------------------------------------------*/
 213
 214 /* --- @key_newraw@ --- *
 215  *
 216  * Arguments:   @unsigned e@ = encoding type to set
 217  *
 218  * Returns:     New key block, not filled in.
 219  */
 220
 221 extern key_data *key_newraw(unsigned /*e*/);
 222
 223 /* --- @key_newbinary@ --- *
 224  *
 225  * Arguments:   @unsigned e@ = other encoding flags
 226  *              @const void *p@ = pointer to key data
 227  *              @size_t sz@ = size of the key data
 228  *
 229  * Returns:     New key data object.
 230  */
 231
 232 extern key_data *key_newbinary(unsigned /*e*/,
 233                                const void */*p*/, size_t /*sz*/);
 234
 235 /* --- @key_newencrypted@ --- *
 236  *
 237  * Arguments:   @unsigned e@ = other encoding flags
 238  *              @const void *p@ = pointer to key data
 239  *              @size_t sz@ = size of the key data
 240  *
 241  * Returns:     New key data object.
 242  */
 243
 244 extern key_data *key_newencrypted(unsigned /*e*/,
 245                                   const void */*p*/, size_t /*sz*/);
 246
 247 /* --- @key_newmp@ --- *
 248  *
 249  * Arguments:   @unsigned e@ = other encoding flags
 250  *              @mp *m@ = pointer to the value to set
 251  *
 252  * Returns:     New key data object.
 253  */
 254
 255 extern key_data *key_newmp(unsigned /*e*/, mp */*m*/);
 256
 257 /* --- @key_newstring@ --- *
 258  *
 259  * Arguments:   @unsigned e@ = other encoding flags
 260  *              @const char *p@ = pointer to the value to set
 261  *
 262  * Returns:     New key data object.
 263  */
 264
 265 extern key_data *key_newstring(unsigned /*e*/, const char */*p*/);
 266
 267 /* --- @key_newec@ --- *
 268  *
 269  * Arguments:   @unsigned e@ = other encoding flags
 270  *              @const ec *pt@ = pointer to the value to set
 271  *
 272  * Returns:     New key data object.
 273  */
 274
 275 extern key_data *key_newec(unsigned /*e*/, const ec */*pt*/);
 276
 277 /* --- @key_newstruct@ --- *
 278  *
 279  * Arguments:   ---
 280  *
 281  * Returns:     New key data object.
 282  */
 283
 284 extern key_data *key_newstruct(void);
 285
 286 /* --- @key_structfind@ --- *
 287  *
 288  * Arguments:   @key_data *k@ = pointer to key data block
 289  *              @const char *tag@ = pointer to tag string
 290  *
 291  * Returns:     Pointer to key data block, or null.
 292  *
 293  * Use:         Looks up the tag in a structured key.
 294  */
 295
 296 extern key_data *key_structfind(key_data */*k*/, const char */*tag*/);
 297
 298 /* --- @key_mksubkeyiter@ --- *
 299  *
 300  * Arguments:   @key_subkeyiter *i@ = pointer to iterator block
 301  *              @key_data *k@ = pointer to key data block
 302  *
 303  * Returns:     ---
 304  *
 305  * Use:         Initializes a subkey iterator.
 306  */
 307
 308 extern void key_mksubkeyiter(key_subkeyiter */*i*/, key_data */*k*/);
 309
 310 /* --- @key_nextsubkey@ --- *
 311  *
 312  * Arguments:   @key_structiter *i@ = pointer to iterator block
 313  *              @const char **tag@ = where to put the tag pointer, or null
 314  *              @key_data **kd@ = where to put the key data pointer, or null
 315  *
 316  * Returns:     Nonzero if there was another item, zero if we hit the
 317  *              end-stop.
 318  *
 319  * Use:         Collects the next subkey of a structured key.
 320  */
 321
 322 extern int key_nextsubkey(key_subkeyiter */*i*/,
 323                           const char **/*tag*/, key_data **/*kd*/);
 324
 325 /* --- @key_structset@, @key_structsteal@ --- *
 326  *
 327  * Arguments:   @key_data *k@ = pointer to key data block
 328  *              @const char *tag@ = pointer to tag string
 329  *              @key_data *kd@ = new key data to store
 330  *
 331  * Returns:     ---
 332  *
 333  * Use:         Creates a new subkey.  Stealing doesn't affect @kd@'s
 334  *              refcount.  If @kd@ is null, the subkey is deleted.
 335  */
 336
 337 extern void key_structset(key_data */*k*/,
 338                           const char */*tag*/, key_data */*kd*/);
 339 extern void key_structsteal(key_data */*k*/,
 340                             const char */*tag*/, key_data */*kd*/);
 341
 342 /* --- @key_split@ --- *
 343  *
 344  * Arguments:   @key_data **kk@ = address of pointer to key data block
 345  *
 346  * Returns:     ---
 347  *
 348  * Use:         Replaces @*kk@ with a pointer to the same key data, but with
 349  *              just one reference.
 350  */
 351
 352 extern void key_split(key_data **/*kk*/);
 353
 354 /*----- Miscellaneous operations ------------------------------------------*/
 355
 356 /* --- @key_incref@ --- *
 357  *
 358  * Arguments:   @key_data *k@ = pointer to key data
 359  *
 360  * Returns:     ---
 361  *
 362  * Use:         Increments the refcount on a key data block.
 363  */
 364
 365 #define KEY_INCREF(k) ((k)->ref++)
 366 extern void key_incref(key_data */*k*/);
 367
 368 /* --- @key_destroy@ --- *
 369  *
 370  * Arguments:   @key_data *k@ = pointer to key data to destroy
 371  *
 372  * Returns:     ---
 373  *
 374  * Use:         Destroys a block of key data, regardless of reference count.
 375  *              Don't use this unless you know what you're doing.
 376  */
 377
 378 extern void key_destroy(key_data */*k*/);
 379
 380 /* --- @key_drop@ --- *
 381  *
 382  * Arguments:   @key_data *k@ = pointer to key data to destroy
 383  *
 384  * Returns:     ---
 385  *
 386  * Use:         Drops a reference to key data, destroying it if necessary.
 387  */
 388
 389 #define KEY_DROP(k) do {                                                \
 390   key_data *_k = k;                                                     \
 391   _k->ref--;                                                            \
 392   if (_k->ref == 0)                                                     \
 393     key_destroy(_k);                                                    \
 394 } while (0)
 395
 396 extern void key_drop(key_data */*k*/);
 397
 398 /* --- @key_do@ --- *
 399  *
 400  * Arguments:   @key_data *k@ = pointer to key data block
 401  *              @const key_filter *kf@ = pointer to filter block
 402  *              @dstr *d@ = pointer to base string
 403  *              @int (*func)(key_data *kd, dstr *d, void *p@ = function
 404  *              @void *p@ = argument to function
 405  *
 406  * Returns:     Nonzero return code from function, or zero.
 407  *
 408  * Use:         Runs a function over all the leaves of a key.
 409  */
 410
 411 extern int key_do(key_data */*k*/, const key_filter */*kf*/, dstr */*d*/,
 412                   int (*/*func*/)(key_data */*kd*/,
 413                                   dstr */*d*/, void */*p*/),
 414                   void */*p*/);
 415
 416 /* --- @key_copydata@ --- *
 417  *
 418  * Arguments:   @key_data *k@ = key data to copy
 419  *              @const key_filter *kf@ = pointer to filter block
 420  *
 421  * Returns:     Pointer to a copy of the data, or null if the root subkey
 422  *              didn't match the filter.
 423  *
 424  * Use:         Copies a chunk of key data.  Subkeys, whether they're
 425  *              structured or leaves, which don't match the filter aren't
 426  *              copied.  The copy may or may not have structure in common
 427  *              with the original.
 428  */
 429
 430 extern key_data *key_copydata(key_data */*k*/, const key_filter */*kf*/);
 431
 432 /*----- Textual encoding --------------------------------------------------*/
 433
 434 /* --- @key_read@ --- *
 435  *
 436  * Arguments:   @const char *p@ = pointer to textual key representation
 437  *              @char **pp@ = where to store the end pointer
 438  *
 439  * Returns:     The newly-read key data, or null if it failed.
 440  *
 441  * Use:         Parses a textual key description.
 442  */
 443
 444 extern key_data *key_read(const char */*p*/, char **/*pp*/);
 445
 446 /* --- @key_write@ --- *
 447  *
 448  * Arguments:   @key_data *k@ = pointer to key data
 449  *              @dstr *d@ = destination string to write on
 450  *              @const key_filter *kf@ = pointer to key selection block
 451  *
 452  * Returns:     Nonzero if any items were actually written.
 453  *
 454  * Use:         Writes a key in a textual encoding.
 455  */
 456
 457 extern int key_write(key_data */*k*/, dstr */*d*/, const key_filter */*kf*/);
 458
 459 /*----- Key binary encoding -----------------------------------------------*/
 460
 461 /* --- @key_decode@ --- *
 462  *
 463  * Arguments:   @const void *p@ = pointer to buffer to read
 464  *              @size_t sz@ = size of the buffer
 465  *
 466  * Returns:     The newly-read key data, or null if it failed.
 467  *
 468  * Use:         Decodes a binary representation of a key.
 469  */
 470
 471 extern key_data *key_decode(const void */*p*/, size_t /*sz*/);
 472
 473 /* --- @key_encode@ --- *
 474  *
 475  * Arguments:   @key_data *k@ = pointer to key data block
 476  *              @dstr *d@ = pointer to destination string
 477  *              @const key_filter *kf@ = pointer to key selection block
 478  *
 479  * Returns:     Nonzero if any items were actually written.
 480  *
 481  * Use:         Encodes a key block as binary data.
 482  */
 483
 484 extern int key_encode(key_data */*k*/, dstr */*d*/,
 485                       const key_filter */*kf*/);
 486
 487 /*----- Packing and unpacking keys ----------------------------------------*/
 488
 489 /* --- @key_pack@ --- *
 490  *
 491  * Arguments:   @key_packdef *kp@ = pointer to packing structure
 492  *              @key_data **kd@ = where to put the key data pointer
 493  *              @dstr *d@ = pointer to tag string for the key data
 494  *
 495  * Returns:     Error code, or zero.
 496  *
 497  * Use:         Packs a key from a data structure.
 498  */
 499
 500 extern int key_pack(key_packdef */*kp*/, key_data **/*kd*/, dstr */*d*/);
 501
 502 /* --- @key_unpack@ --- *
 503  *
 504  * Arguments:   @key_packdef *kp@ = pointer to packing structure
 505  *              @key_data *kd@ = pointer to source key data
 506  *              @dstr *d@ = pointer to tag string for the key data
 507  *
 508  * Returns:     Error code, or zero.
 509  *
 510  * Use:         Unpacks a key into an appropriate data structure.
 511  */
 512
 513 extern int key_unpack(key_packdef */*kp*/, key_data */*kd*/, dstr */*d*/);
 514
 515 /* --- @key_unpackdone@ --- *
 516  *
 517  * Arguments:   @key_packdef *kp@ = pointer to packing definition
 518  *
 519  * Returns:     ---
 520  *
 521  * Use:         Frees the key components contained within a packing
 522  *              definition, created during key unpacking.
 523  */
 524
 525 extern void key_unpackdone(key_packdef */*kp*/);
 526
 527 /*----- Key encryption ----------------------------------------------------*/
 528
 529 /* --- @key_lock@ --- *
 530  *
 531  * Arguments:   @key_data **kt@ = where to store the destination pointer
 532  *              @key_data *k@ = source key data block or null to use @*kt@
 533  *              @const void *e@ = secret to encrypt key with
 534  *              @size_t esz@ = size of the secret
 535  *
 536  * Returns:     ---
 537  *
 538  * Use:         Encrypts a key data block using a secret.
 539  */
 540
 541 extern void key_lock(key_data **/*kt*/, key_data */*k*/,
 542                      const void */*e*/, size_t /*esz*/);
 543
 544 /* --- @key_unlock@ --- *
 545  *
 546  * Arguments:   @key_data **kt@ = where to store the destination pointer
 547  *              @key_data *k@ = source key data block or null to use @*kt@
 548  *              @const void *e@ = secret to decrypt the block with
 549  *              @size_t esz@ = size of the secret
 550  *
 551  * Returns:     Zero for success, or a @KERR_@ error code.
 552  *
 553  * Use:         Unlocks a key using a secret.
 554  */
 555
 556 extern int key_unlock(key_data **/*kt*/, key_data */*k*/,
 557                       const void */*e*/, size_t /*esz*/);
 558
 559 /* --- @key_plock@ --- *
 560  *
 561  * Arguments:   @key_data **kt@ = where to store the destination pointer
 562  *              @key_data *k@ = source key data block or null to use @*kt@
 563  *              @const char *tag@ = tag to use for passphrase
 564  *
 565  * Returns:     Zero if successful, a @KERR@ error code on failure.
 566  *
 567  * Use:         Locks a key by encrypting it with a passphrase.
 568  */
 569
 570 extern int key_plock(key_data **/*kt*/, key_data */*k*/,
 571                      const char */*tag*/);
 572
 573 /* --- @key_punlock@ --- *
 574  *
 575  * Arguments:   @key_data **kt@ = where to store the destination pointer
 576  *              @key_data *k@ = source key data block or null to use @*kt@
 577  *              @const char *tag@ = tag to use for passphrase
 578  *
 579  * Returns:     Zero if successful, a @KERR@ error code on failure.
 580  *
 581  * Use:         Unlocks a passphrase-locked key.
 582  */
 583
 584 extern int key_punlock(key_data **/*kt*/, key_data */*k*/,
 585                        const char */*tag*/);
 586
 587 /*----- That's all, folks -------------------------------------------------*/
 588
 589 #ifdef __cplusplus
 590   }
 591 #endif
 592
 593 #endif