contrib/bind-9.3/lib/dns/include/dst/dst.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: dst.h,v 1.1.4.1 2004/12/09 04:07:19 marka Exp $ */
  19
  20 #ifndef DST_DST_H
  21 #define DST_DST_H 1
  22
  23 #include <isc/lang.h>
  24
  25 #include <dns/types.h>
  26
  27 ISC_LANG_BEGINDECLS
  28
  29 /***
  30  *** Types
  31  ***/
  32
  33 /*
  34  * The dst_key structure is opaque.  Applications should use the accessor
  35  * functions provided to retrieve key attributes.  If an application needs
  36  * to set attributes, new accessor functions will be written.
  37  */
  38
  39 typedef struct dst_key          dst_key_t;
  40 typedef struct dst_context      dst_context_t;
  41
  42 /* DST algorithm codes */
  43 #define DST_ALG_UNKNOWN         0
  44 #define DST_ALG_RSAMD5          1
  45 #define DST_ALG_RSA             DST_ALG_RSAMD5  /* backwards compatibility */
  46 #define DST_ALG_DH              2
  47 #define DST_ALG_DSA             3
  48 #define DST_ALG_ECC             4
  49 #define DST_ALG_RSASHA1         5
  50 #define DST_ALG_HMACMD5         157
  51 #define DST_ALG_GSSAPI          160
  52 #define DST_ALG_PRIVATE         254
  53 #define DST_ALG_EXPAND          255
  54 #define DST_MAX_ALGS            255
  55
  56 /* A buffer of this size is large enough to hold any key */
  57 #define DST_KEY_MAXSIZE         1280
  58
  59 /*
  60  * A buffer of this size is large enough to hold the textual representation
  61  * of any key
  62  */
  63 #define DST_KEY_MAXTEXTSIZE     2048
  64
  65 /* 'Type' for dst_read_key() */
  66 #define DST_TYPE_KEY            0x1000000       /* KEY key */
  67 #define DST_TYPE_PRIVATE        0x2000000
  68 #define DST_TYPE_PUBLIC         0x4000000
  69
  70 /***
  71  *** Functions
  72  ***/
  73
  74 isc_result_t
  75 dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags);
  76 /*
  77  * Initializes the DST subsystem.
  78  *
  79  * Requires:
  80  *      "mctx" is a valid memory context
  81  *      "ectx" is a valid entropy context
  82  *
  83  * Returns:
  84  *      ISC_R_SUCCESS
  85  *      ISC_R_NOMEMORY
  86  *
  87  * Ensures:
  88  *      DST is properly initialized.
  89  */
  90
  91 void
  92 dst_lib_destroy(void);
  93 /*
  94  * Releases all resources allocated by DST.
  95  */
  96
  97 isc_boolean_t
  98 dst_algorithm_supported(unsigned int alg);
  99 /*
 100  * Checks that a given algorithm is supported by DST.
 101  *
 102  * Returns:
 103  *      ISC_TRUE
 104  *      ISC_FALSE
 105  */
 106
 107 isc_result_t
 108 dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp);
 109 /*
 110  * Creates a context to be used for a sign or verify operation.
 111  *
 112  * Requires:
 113  *      "key" is a valid key.
 114  *      "mctx" is a valid memory context.
 115  *      dctxp != NULL && *dctxp == NULL
 116  *
 117  * Returns:
 118  *      ISC_R_SUCCESS
 119  *      ISC_R_NOMEMORY
 120  *
 121  * Ensures:
 122  *      *dctxp will contain a usable context.
 123  */
 124
 125 void
 126 dst_context_destroy(dst_context_t **dctxp);
 127 /*
 128  * Destroys all memory associated with a context.
 129  *
 130  * Requires:
 131  *      *dctxp != NULL && *dctxp == NULL
 132  *
 133  * Ensures:
 134  *      *dctxp == NULL
 135  */
 136
 137 isc_result_t
 138 dst_context_adddata(dst_context_t *dctx, const isc_region_t *data);
 139 /*
 140  * Incrementally adds data to the context to be used in a sign or verify
 141  * operation.
 142  *
 143  * Requires:
 144  *      "dctx" is a valid context
 145  *      "data" is a valid region
 146  *
 147  * Returns:
 148  *      ISC_R_SUCCESS
 149  *      DST_R_SIGNFAILURE
 150  *      all other errors indicate failure
 151  */
 152
 153 isc_result_t
 154 dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig);
 155 /*
 156  * Computes a signature using the data and key stored in the context.
 157  *
 158  * Requires:
 159  *      "dctx" is a valid context.
 160  *      "sig" is a valid buffer.
 161  *
 162  * Returns:
 163  *      ISC_R_SUCCESS
 164  *      DST_R_VERIFYFAILURE
 165  *      all other errors indicate failure
 166  *
 167  * Ensures:
 168  *      "sig" will contain the signature
 169  */
 170
 171 isc_result_t
 172 dst_context_verify(dst_context_t *dctx, isc_region_t *sig);
 173 /*
 174  * Verifies the signature using the data and key stored in the context.
 175  *
 176  * Requires:
 177  *      "dctx" is a valid context.
 178  *      "sig" is a valid region.
 179  *
 180  * Returns:
 181  *      ISC_R_SUCCESS
 182  *      all other errors indicate failure
 183  *
 184  * Ensures:
 185  *      "sig" will contain the signature
 186  */
 187
 188 isc_result_t
 189 dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
 190                       isc_buffer_t *secret);
 191 /*
 192  * Computes a shared secret from two (Diffie-Hellman) keys.
 193  *
 194  * Requires:
 195  *     "pub" is a valid key that can be used to derive a shared secret
 196  *     "priv" is a valid private key that can be used to derive a shared secret
 197  *     "secret" is a valid buffer
 198  *
 199  * Returns:
 200  *      ISC_R_SUCCESS
 201  *      any other result indicates failure
 202  *
 203  * Ensures:
 204  *      If successful, secret will contain the derived shared secret.
 205  */
 206
 207 isc_result_t
 208 dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
 209                  const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
 210 /*
 211  * Reads a key from permanent storage.  The key can either be a public or
 212  * private key, and is specified by name, algorithm, and id.  If a private key
 213  * is specified, the public key must also be present.  If directory is NULL,
 214  * the current directory is assumed.
 215  *
 216  * Requires:
 217  *      "name" is a valid absolute dns name.
 218  *      "id" is a valid key tag identifier.
 219  *      "alg" is a supported key algorithm.
 220  *      "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
 221  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 222  *      "mctx" is a valid memory context.
 223  *      "keyp" is not NULL and "*keyp" is NULL.
 224  *
 225  * Returns:
 226  *      ISC_R_SUCCESS
 227  *      any other result indicates failure
 228  *
 229  * Ensures:
 230  *      If successful, *keyp will contain a valid key.
 231  */
 232
 233 isc_result_t
 234 dst_key_fromnamedfile(const char *filename, int type, isc_mem_t *mctx,
 235                       dst_key_t **keyp);
 236 /*
 237  * Reads a key from permanent storage.  The key can either be a public or
 238  * key, and is specified by filename.  If a private key is specified, the
 239  * public key must also be present.
 240  *
 241  * Requires:
 242  *      "filename" is not NULL
 243  *      "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 244  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 245  *      "mctx" is a valid memory context
 246  *      "keyp" is not NULL and "*keyp" is NULL.
 247  *
 248  * Returns:
 249  *      ISC_R_SUCCESS
 250  *      any other result indicates failure
 251  *
 252  * Ensures:
 253  *      If successful, *keyp will contain a valid key.
 254  */
 255
 256 isc_result_t
 257 dst_key_tofile(const dst_key_t *key, int type, const char *directory);
 258 /*
 259  * Writes a key to permanent storage.  The key can either be a public or
 260  * private key.  Public keys are written in DNS format and private keys
 261  * are written as a set of base64 encoded values.  If directory is NULL,
 262  * the current directory is assumed.
 263  *
 264  * Requires:
 265  *      "key" is a valid key.
 266  *      "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 267  *
 268  * Returns:
 269  *      ISC_R_SUCCESS
 270  *      any other result indicates failure
 271  */
 272
 273 isc_result_t
 274 dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass,
 275                 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 276 /*
 277  * Converts a DNS KEY record into a DST key.
 278  *
 279  * Requires:
 280  *      "name" is a valid absolute dns name.
 281  *      "source" is a valid buffer.  There must be at least 4 bytes available.
 282  *      "mctx" is a valid memory context.
 283  *      "keyp" is not NULL and "*keyp" is NULL.
 284  *
 285  * Returns:
 286  *      ISC_R_SUCCESS
 287  *      any other result indicates failure
 288  *
 289  * Ensures:
 290  *      If successful, *keyp will contain a valid key, and the consumed
 291  *      pointer in data will be advanced.
 292  */
 293
 294 isc_result_t
 295 dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
 296 /*
 297  * Converts a DST key into a DNS KEY record.
 298  *
 299  * Requires:
 300  *      "key" is a valid key.
 301  *      "target" is a valid buffer.  There must be at least 4 bytes unused.
 302  *
 303  * Returns:
 304  *      ISC_R_SUCCESS
 305  *      any other result indicates failure
 306  *
 307  * Ensures:
 308  *      If successful, the used pointer in 'target' is advanced by at least 4.
 309  */
 310
 311 isc_result_t
 312 dst_key_frombuffer(dns_name_t *name, unsigned int alg,
 313                    unsigned int flags, unsigned int protocol,
 314                    dns_rdataclass_t rdclass,
 315                    isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 316 /*
 317  * Converts a buffer containing DNS KEY RDATA into a DST key.
 318  *
 319  * Requires:
 320  *      "name" is a valid absolute dns name.
 321  *      "alg" is a supported key algorithm.
 322  *      "source" is a valid buffer.
 323  *      "mctx" is a valid memory context.
 324  *      "keyp" is not NULL and "*keyp" is NULL.
 325  *
 326  * Returns:
 327  *      ISC_R_SUCCESS
 328  *      any other result indicates failure
 329  *
 330  * Ensures:
 331  *      If successful, *keyp will contain a valid key, and the consumed
 332  *      pointer in source will be advanced.
 333  */
 334
 335 isc_result_t
 336 dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
 337 /*
 338  * Converts a DST key into DNS KEY RDATA format.
 339  *
 340  * Requires:
 341  *      "key" is a valid key.
 342  *      "target" is a valid buffer.
 343  *
 344  * Returns:
 345  *      ISC_R_SUCCESS
 346  *      any other result indicates failure
 347  *
 348  * Ensures:
 349  *      If successful, the used pointer in 'target' is advanced.
 350  */
 351
 352 isc_result_t
 353 dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
 354 /*
 355  * Converts a public key into a private key, reading the private key
 356  * information from the buffer.  The buffer should contain the same data
 357  * as the .private key file would.
 358  *
 359  * Requires:
 360  *      "key" is a valid public key.
 361  *      "buffer" is not NULL.
 362  *
 363  * Returns:
 364  *      ISC_R_SUCCESS
 365  *      any other result indicates failure
 366  *
 367  * Ensures:
 368  *      If successful, key will contain a valid private key.
 369  */
 370
 371
 372 isc_result_t
 373 dst_key_fromgssapi(dns_name_t *name, void *opaque, isc_mem_t *mctx,
 374                                    dst_key_t **keyp);
 375 /*
 376  * Converts a GSSAPI opaque context id into a DST key.
 377  *
 378  * Requires:
 379  *      "name" is a valid absolute dns name.
 380  *      "opaque" is a GSSAPI context id.
 381  *      "mctx" is a valid memory context.
 382  *      "keyp" is not NULL and "*keyp" is NULL.
 383  *
 384  * Returns:
 385  *      ISC_R_SUCCESS
 386  *      any other result indicates failure
 387  *
 388  * Ensures:
 389  *      If successful, *keyp will contain a valid key and be responsible for
 390  *      the context id.
 391  */
 392
 393 isc_result_t
 394 dst_key_generate(dns_name_t *name, unsigned int alg,
 395                  unsigned int bits, unsigned int param,
 396                  unsigned int flags, unsigned int protocol,
 397                  dns_rdataclass_t rdclass,
 398                  isc_mem_t *mctx, dst_key_t **keyp);
 399 /*
 400  * Generate a DST key (or keypair) with the supplied parameters.  The
 401  * interpretation of the "param" field depends on the algorithm:
 402  *      RSA:    exponent
 403  *              0       use exponent 3
 404  *              !0      use Fermat4 (2^16 + 1)
 405  *      DH:     generator
 406  *              0       default - use well known prime if bits == 768 or 1024,
 407  *                      otherwise use 2 as the generator.
 408  *              !0      use this value as the generator.
 409  *      DSA:    unused
 410  *      HMACMD5: entropy
 411  *              0       default - require good entropy
 412  *              !0      lack of good entropy is ok
 413  *
 414  * Requires:
 415  *      "name" is a valid absolute dns name.
 416  *      "keyp" is not NULL and "*keyp" is NULL.
 417  *
 418  * Returns:
 419  *      ISC_R_SUCCESS
 420  *      any other result indicates failure
 421  *
 422  * Ensures:
 423  *      If successful, *keyp will contain a valid key.
 424  */
 425
 426 isc_boolean_t
 427 dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
 428 /*
 429  * Compares two DST keys.
 430  *
 431  * Requires:
 432  *      "key1" is a valid key.
 433  *      "key2" is a valid key.
 434  *
 435  * Returns:
 436  *      ISC_TRUE
 437  *      ISC_FALSE
 438  */
 439
 440 isc_boolean_t
 441 dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
 442 /*
 443  * Compares the parameters of two DST keys.  This is used to determine if
 444  * two (Diffie-Hellman) keys can be used to derive a shared secret.
 445  *
 446  * Requires:
 447  *      "key1" is a valid key.
 448  *      "key2" is a valid key.
 449  *
 450  * Returns:
 451  *      ISC_TRUE
 452  *      ISC_FALSE
 453  */
 454
 455 void
 456 dst_key_free(dst_key_t **keyp);
 457 /*
 458  * Release all memory associated with the key.
 459  *
 460  * Requires:
 461  *      "keyp" is not NULL and "*keyp" is a valid key.
 462  *
 463  * Ensures:
 464  *      All memory associated with "*keyp" will be freed.
 465  *      *keyp == NULL
 466  */
 467
 468 /*
 469  * Accessor functions to obtain key fields.
 470  *
 471  * Require:
 472  *      "key" is a valid key.
 473  */
 474 dns_name_t *
 475 dst_key_name(const dst_key_t *key);
 476
 477 unsigned int
 478 dst_key_size(const dst_key_t *key);
 479
 480 unsigned int
 481 dst_key_proto(const dst_key_t *key);
 482
 483 unsigned int
 484 dst_key_alg(const dst_key_t *key);
 485
 486 isc_uint32_t
 487 dst_key_flags(const dst_key_t *key);
 488
 489 dns_keytag_t
 490 dst_key_id(const dst_key_t *key);
 491
 492 dns_rdataclass_t
 493 dst_key_class(const dst_key_t *key);
 494
 495 isc_boolean_t
 496 dst_key_isprivate(const dst_key_t *key);
 497
 498 isc_boolean_t
 499 dst_key_iszonekey(const dst_key_t *key);
 500
 501 isc_boolean_t
 502 dst_key_isnullkey(const dst_key_t *key);
 503
 504 isc_result_t
 505 dst_key_buildfilename(const dst_key_t *key, int type,
 506                       const char *directory, isc_buffer_t *out);
 507 /*
 508  * Generates the filename used by dst to store the specified key.
 509  * If directory is NULL, the current directory is assumed.
 510  *
 511  * Requires:
 512  *      "key" is a valid key
 513  *      "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
 514  *      "out" is a valid buffer
 515  *
 516  * Ensures:
 517  *      the file name will be written to "out", and the used pointer will
 518  *              be advanced.
 519  */
 520
 521 isc_result_t
 522 dst_key_sigsize(const dst_key_t *key, unsigned int *n);
 523 /*
 524  * Computes the size of a signature generated by the given key.
 525  *
 526  * Requires:
 527  *      "key" is a valid key.
 528  *      "n" is not NULL
 529  *
 530  * Returns:
 531  *      ISC_R_SUCCESS
 532  *      DST_R_UNSUPPORTEDALG
 533  *
 534  * Ensures:
 535  *      "n" stores the size of a generated signature
 536  */
 537
 538 isc_result_t
 539 dst_key_secretsize(const dst_key_t *key, unsigned int *n);
 540 /*
 541  * Computes the size of a shared secret generated by the given key.
 542  *
 543  * Requires:
 544  *      "key" is a valid key.
 545  *      "n" is not NULL
 546  *
 547  * Returns:
 548  *      ISC_R_SUCCESS
 549  *      DST_R_UNSUPPORTEDALG
 550  *
 551  * Ensures:
 552  *      "n" stores the size of a generated shared secret
 553  */
 554
 555 isc_uint16_t
 556 dst_region_computeid(const isc_region_t *source, unsigned int alg);
 557 /*
 558  * Computes the key id of the key stored in the provided region with the
 559  * given algorithm.
 560  *
 561  * Requires:
 562  *      "source" contains a valid, non-NULL region.
 563  *
 564  * Returns:
 565  *      the key id
 566  */
 567
 568 ISC_LANG_ENDDECLS
 569
 570 #endif /* DST_DST_H */