contrib/bind9/lib/dns/include/dst/dst.h

   1 /*
   2  * Copyright (C) 2004-2012  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or 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$ */
  19
  20 #ifndef DST_DST_H
  21 #define DST_DST_H 1
  22
  23 /*! \file dst/dst.h */
  24
  25 #include <isc/lang.h>
  26 #include <isc/stdtime.h>
  27
  28 #include <dns/types.h>
  29 #include <dns/name.h>
  30 #include <dns/secalg.h>
  31
  32 #include <dst/gssapi.h>
  33
  34 ISC_LANG_BEGINDECLS
  35
  36 /***
  37  *** Types
  38  ***/
  39
  40 /*%
  41  * The dst_key structure is opaque.  Applications should use the accessor
  42  * functions provided to retrieve key attributes.  If an application needs
  43  * to set attributes, new accessor functions will be written.
  44  */
  45
  46 typedef struct dst_key          dst_key_t;
  47 typedef struct dst_context      dst_context_t;
  48
  49 /* DST algorithm codes */
  50 #define DST_ALG_UNKNOWN         0
  51 #define DST_ALG_RSAMD5          1
  52 #define DST_ALG_RSA             DST_ALG_RSAMD5  /*%< backwards compatibility */
  53 #define DST_ALG_DH              2
  54 #define DST_ALG_DSA             3
  55 #define DST_ALG_ECC             4
  56 #define DST_ALG_RSASHA1         5
  57 #define DST_ALG_NSEC3DSA        6
  58 #define DST_ALG_NSEC3RSASHA1    7
  59 #define DST_ALG_RSASHA256       8
  60 #define DST_ALG_RSASHA512       10
  61 #define DST_ALG_ECCGOST         12
  62 #define DST_ALG_ECDSA256        13
  63 #define DST_ALG_ECDSA384        14
  64 #define DST_ALG_HMACMD5         157
  65 #define DST_ALG_GSSAPI          160
  66 #define DST_ALG_HMACSHA1        161     /* XXXMPA */
  67 #define DST_ALG_HMACSHA224      162     /* XXXMPA */
  68 #define DST_ALG_HMACSHA256      163     /* XXXMPA */
  69 #define DST_ALG_HMACSHA384      164     /* XXXMPA */
  70 #define DST_ALG_HMACSHA512      165     /* XXXMPA */
  71 #define DST_ALG_PRIVATE         254
  72 #define DST_ALG_EXPAND          255
  73 #define DST_MAX_ALGS            255
  74
  75 /*% A buffer of this size is large enough to hold any key */
  76 #define DST_KEY_MAXSIZE         1280
  77
  78 /*%
  79  * A buffer of this size is large enough to hold the textual representation
  80  * of any key
  81  */
  82 #define DST_KEY_MAXTEXTSIZE     2048
  83
  84 /*% 'Type' for dst_read_key() */
  85 #define DST_TYPE_KEY            0x1000000       /* KEY key */
  86 #define DST_TYPE_PRIVATE        0x2000000
  87 #define DST_TYPE_PUBLIC         0x4000000
  88
  89 /* Key timing metadata definitions */
  90 #define DST_TIME_CREATED        0
  91 #define DST_TIME_PUBLISH        1
  92 #define DST_TIME_ACTIVATE       2
  93 #define DST_TIME_REVOKE         3
  94 #define DST_TIME_INACTIVE       4
  95 #define DST_TIME_DELETE         5
  96 #define DST_TIME_DSPUBLISH      6
  97 #define DST_MAX_TIMES           6
  98
  99 /* Numeric metadata definitions */
 100 #define DST_NUM_PREDECESSOR     0
 101 #define DST_NUM_SUCCESSOR       1
 102 #define DST_NUM_MAXTTL          2
 103 #define DST_NUM_ROLLPERIOD      3
 104 #define DST_MAX_NUMERIC         3
 105
 106 /*
 107  * Current format version number of the private key parser.
 108  *
 109  * When parsing a key file with the same major number but a higher minor
 110  * number, the key parser will ignore any fields it does not recognize.
 111  * Thus, DST_MINOR_VERSION should be incremented whenever new
 112  * fields are added to the private key file (such as new metadata).
 113  *
 114  * When rewriting these keys, those fields will be dropped, and the
 115  * format version set back to the current one..
 116  *
 117  * When a key is seen with a higher major number, the key parser will
 118  * reject it as invalid.  Thus, DST_MAJOR_VERSION should be incremented
 119  * and DST_MINOR_VERSION set to zero whenever there is a format change
 120  * which is not backward compatible to previous versions of the dst_key
 121  * parser, such as change in the syntax of an existing field, the removal
 122  * of a currently mandatory field, or a new field added which would
 123  * alter the functioning of the key if it were absent.
 124  */
 125 #define DST_MAJOR_VERSION       1
 126 #define DST_MINOR_VERSION       3
 127
 128 /***
 129  *** Functions
 130  ***/
 131
 132 isc_result_t
 133 dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags);
 134
 135 isc_result_t
 136 dst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx,
 137               const char *engine, unsigned int eflags);
 138 /*%<
 139  * Initializes the DST subsystem.
 140  *
 141  * Requires:
 142  * \li  "mctx" is a valid memory context
 143  * \li  "ectx" is a valid entropy context
 144  *
 145  * Returns:
 146  * \li  ISC_R_SUCCESS
 147  * \li  ISC_R_NOMEMORY
 148  * \li  DST_R_NOENGINE
 149  *
 150  * Ensures:
 151  * \li  DST is properly initialized.
 152  */
 153
 154 void
 155 dst_lib_destroy(void);
 156 /*%<
 157  * Releases all resources allocated by DST.
 158  */
 159
 160 isc_boolean_t
 161 dst_algorithm_supported(unsigned int alg);
 162 /*%<
 163  * Checks that a given algorithm is supported by DST.
 164  *
 165  * Returns:
 166  * \li  ISC_TRUE
 167  * \li  ISC_FALSE
 168  */
 169
 170 isc_result_t
 171 dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp);
 172 /*%<
 173  * Creates a context to be used for a sign or verify operation.
 174  *
 175  * Requires:
 176  * \li  "key" is a valid key.
 177  * \li  "mctx" is a valid memory context.
 178  * \li  dctxp != NULL && *dctxp == NULL
 179  *
 180  * Returns:
 181  * \li  ISC_R_SUCCESS
 182  * \li  ISC_R_NOMEMORY
 183  *
 184  * Ensures:
 185  * \li  *dctxp will contain a usable context.
 186  */
 187
 188 void
 189 dst_context_destroy(dst_context_t **dctxp);
 190 /*%<
 191  * Destroys all memory associated with a context.
 192  *
 193  * Requires:
 194  * \li  *dctxp != NULL && *dctxp == NULL
 195  *
 196  * Ensures:
 197  * \li  *dctxp == NULL
 198  */
 199
 200 isc_result_t
 201 dst_context_adddata(dst_context_t *dctx, const isc_region_t *data);
 202 /*%<
 203  * Incrementally adds data to the context to be used in a sign or verify
 204  * operation.
 205  *
 206  * Requires:
 207  * \li  "dctx" is a valid context
 208  * \li  "data" is a valid region
 209  *
 210  * Returns:
 211  * \li  ISC_R_SUCCESS
 212  * \li  DST_R_SIGNFAILURE
 213  * \li  all other errors indicate failure
 214  */
 215
 216 isc_result_t
 217 dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig);
 218 /*%<
 219  * Computes a signature using the data and key stored in the context.
 220  *
 221  * Requires:
 222  * \li  "dctx" is a valid context.
 223  * \li  "sig" is a valid buffer.
 224  *
 225  * Returns:
 226  * \li  ISC_R_SUCCESS
 227  * \li  DST_R_VERIFYFAILURE
 228  * \li  all other errors indicate failure
 229  *
 230  * Ensures:
 231  * \li  "sig" will contain the signature
 232  */
 233
 234 isc_result_t
 235 dst_context_verify(dst_context_t *dctx, isc_region_t *sig);
 236 /*%<
 237  * Verifies the signature using the data and key stored in the context.
 238  *
 239  * Requires:
 240  * \li  "dctx" is a valid context.
 241  * \li  "sig" is a valid region.
 242  *
 243  * Returns:
 244  * \li  ISC_R_SUCCESS
 245  * \li  all other errors indicate failure
 246  *
 247  * Ensures:
 248  * \li  "sig" will contain the signature
 249  */
 250
 251 isc_result_t
 252 dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
 253                       isc_buffer_t *secret);
 254 /*%<
 255  * Computes a shared secret from two (Diffie-Hellman) keys.
 256  *
 257  * Requires:
 258  * \li  "pub" is a valid key that can be used to derive a shared secret
 259  * \li  "priv" is a valid private key that can be used to derive a shared secret
 260  * \li  "secret" is a valid buffer
 261  *
 262  * Returns:
 263  * \li  ISC_R_SUCCESS
 264  * \li  any other result indicates failure
 265  *
 266  * Ensures:
 267  * \li  If successful, secret will contain the derived shared secret.
 268  */
 269
 270 isc_result_t
 271 dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
 272                  const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
 273 /*%<
 274  * Reads a key from permanent storage.  The key can either be a public or
 275  * private key, and is specified by name, algorithm, and id.  If a private key
 276  * is specified, the public key must also be present.  If directory is NULL,
 277  * the current directory is assumed.
 278  *
 279  * Requires:
 280  * \li  "name" is a valid absolute dns name.
 281  * \li  "id" is a valid key tag identifier.
 282  * \li  "alg" is a supported key algorithm.
 283  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
 284  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 285  * \li  "mctx" is a valid memory context.
 286  * \li  "keyp" is not NULL and "*keyp" is NULL.
 287  *
 288  * Returns:
 289  * \li  ISC_R_SUCCESS
 290  * \li  any other result indicates failure
 291  *
 292  * Ensures:
 293  * \li  If successful, *keyp will contain a valid key.
 294  */
 295
 296 isc_result_t
 297 dst_key_fromnamedfile(const char *filename, const char *dirname,
 298                       int type, isc_mem_t *mctx, dst_key_t **keyp);
 299 /*%<
 300  * Reads a key from permanent storage.  The key can either be a public or
 301  * key, and is specified by filename.  If a private key is specified, the
 302  * public key must also be present.
 303  *
 304  * If 'dirname' is not NULL, and 'filename' is a relative path,
 305  * then the file is looked up relative to the given directory.
 306  * If 'filename' is an absolute path, 'dirname' is ignored.
 307  *
 308  * Requires:
 309  * \li  "filename" is not NULL
 310  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 311  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 312  * \li  "mctx" is a valid memory context
 313  * \li  "keyp" is not NULL and "*keyp" is NULL.
 314  *
 315  * Returns:
 316  * \li  ISC_R_SUCCESS
 317  * \li  any other result indicates failure
 318  *
 319  * Ensures:
 320  * \li  If successful, *keyp will contain a valid key.
 321  */
 322
 323
 324 isc_result_t
 325 dst_key_read_public(const char *filename, int type,
 326                     isc_mem_t *mctx, dst_key_t **keyp);
 327 /*%<
 328  * Reads a public key from permanent storage.  The key must be a public key.
 329  *
 330  * Requires:
 331  * \li  "filename" is not NULL
 332  * \li  "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 333  * \li  "mctx" is a valid memory context
 334  * \li  "keyp" is not NULL and "*keyp" is NULL.
 335  *
 336  * Returns:
 337  * \li  ISC_R_SUCCESS
 338  * \li  DST_R_BADKEYTYPE if the key type is not the expected one
 339  * \li  ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
 340  * \li  any other result indicates failure
 341  *
 342  * Ensures:
 343  * \li  If successful, *keyp will contain a valid key.
 344  */
 345
 346 isc_result_t
 347 dst_key_tofile(const dst_key_t *key, int type, const char *directory);
 348 /*%<
 349  * Writes a key to permanent storage.  The key can either be a public or
 350  * private key.  Public keys are written in DNS format and private keys
 351  * are written as a set of base64 encoded values.  If directory is NULL,
 352  * the current directory is assumed.
 353  *
 354  * Requires:
 355  * \li  "key" is a valid key.
 356  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 357  *
 358  * Returns:
 359  * \li  ISC_R_SUCCESS
 360  * \li  any other result indicates failure
 361  */
 362
 363 isc_result_t
 364 dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass,
 365                 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 366 /*%<
 367  * Converts a DNS KEY record into a DST key.
 368  *
 369  * Requires:
 370  * \li  "name" is a valid absolute dns name.
 371  * \li  "source" is a valid buffer.  There must be at least 4 bytes available.
 372  * \li  "mctx" is a valid memory context.
 373  * \li  "keyp" is not NULL and "*keyp" is NULL.
 374  *
 375  * Returns:
 376  * \li  ISC_R_SUCCESS
 377  * \li  any other result indicates failure
 378  *
 379  * Ensures:
 380  * \li  If successful, *keyp will contain a valid key, and the consumed
 381  *      pointer in data will be advanced.
 382  */
 383
 384 isc_result_t
 385 dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
 386 /*%<
 387  * Converts a DST key into a DNS KEY record.
 388  *
 389  * Requires:
 390  * \li  "key" is a valid key.
 391  * \li  "target" is a valid buffer.  There must be at least 4 bytes unused.
 392  *
 393  * Returns:
 394  * \li  ISC_R_SUCCESS
 395  * \li  any other result indicates failure
 396  *
 397  * Ensures:
 398  * \li  If successful, the used pointer in 'target' is advanced by at least 4.
 399  */
 400
 401 isc_result_t
 402 dst_key_frombuffer(dns_name_t *name, unsigned int alg,
 403                    unsigned int flags, unsigned int protocol,
 404                    dns_rdataclass_t rdclass,
 405                    isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 406 /*%<
 407  * Converts a buffer containing DNS KEY RDATA into a DST key.
 408  *
 409  * Requires:
 410  *\li   "name" is a valid absolute dns name.
 411  *\li   "alg" is a supported key algorithm.
 412  *\li   "source" is a valid buffer.
 413  *\li   "mctx" is a valid memory context.
 414  *\li   "keyp" is not NULL and "*keyp" is NULL.
 415  *
 416  * Returns:
 417  *\li   ISC_R_SUCCESS
 418  * \li  any other result indicates failure
 419  *
 420  * Ensures:
 421  *\li   If successful, *keyp will contain a valid key, and the consumed
 422  *      pointer in source will be advanced.
 423  */
 424
 425 isc_result_t
 426 dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
 427 /*%<
 428  * Converts a DST key into DNS KEY RDATA format.
 429  *
 430  * Requires:
 431  *\li   "key" is a valid key.
 432  *\li   "target" is a valid buffer.
 433  *
 434  * Returns:
 435  *\li   ISC_R_SUCCESS
 436  * \li  any other result indicates failure
 437  *
 438  * Ensures:
 439  *\li   If successful, the used pointer in 'target' is advanced.
 440  */
 441
 442 isc_result_t
 443 dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
 444 /*%<
 445  * Converts a public key into a private key, reading the private key
 446  * information from the buffer.  The buffer should contain the same data
 447  * as the .private key file would.
 448  *
 449  * Requires:
 450  *\li   "key" is a valid public key.
 451  *\li   "buffer" is not NULL.
 452  *
 453  * Returns:
 454  *\li   ISC_R_SUCCESS
 455  * \li  any other result indicates failure
 456  *
 457  * Ensures:
 458  *\li   If successful, key will contain a valid private key.
 459  */
 460
 461 gss_ctx_id_t
 462 dst_key_getgssctx(const dst_key_t *key);
 463 /*%<
 464  * Returns the opaque key data.
 465  * Be cautions when using this value unless you know what you are doing.
 466  *
 467  * Requires:
 468  *\li   "key" is not NULL.
 469  *
 470  * Returns:
 471  *\li   gssctx key data, possibly NULL.
 472  */
 473
 474 isc_result_t
 475 dst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx,
 476                    dst_key_t **keyp, isc_region_t *intoken);
 477 /*%<
 478  * Converts a GSSAPI opaque context id into a DST key.
 479  *
 480  * Requires:
 481  *\li   "name" is a valid absolute dns name.
 482  *\li   "gssctx" is a GSSAPI context id.
 483  *\li   "mctx" is a valid memory context.
 484  *\li   "keyp" is not NULL and "*keyp" is NULL.
 485  *
 486  * Returns:
 487  *\li   ISC_R_SUCCESS
 488  * \li  any other result indicates failure
 489  *
 490  * Ensures:
 491  *\li   If successful, *keyp will contain a valid key and be responsible for
 492  *      the context id.
 493  */
 494
 495 isc_result_t
 496 dst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags,
 497                   unsigned int protocol, dns_rdataclass_t rdclass,
 498                   const char *engine, const char *label, const char *pin,
 499                   isc_mem_t *mctx, dst_key_t **keyp);
 500
 501 isc_result_t
 502 dst_key_generate(dns_name_t *name, unsigned int alg,
 503                  unsigned int bits, unsigned int param,
 504                  unsigned int flags, unsigned int protocol,
 505                  dns_rdataclass_t rdclass,
 506                  isc_mem_t *mctx, dst_key_t **keyp);
 507
 508 isc_result_t
 509 dst_key_generate2(dns_name_t *name, unsigned int alg,
 510                   unsigned int bits, unsigned int param,
 511                   unsigned int flags, unsigned int protocol,
 512                   dns_rdataclass_t rdclass,
 513                   isc_mem_t *mctx, dst_key_t **keyp,
 514                   void (*callback)(int));
 515 /*%<
 516  * Generate a DST key (or keypair) with the supplied parameters.  The
 517  * interpretation of the "param" field depends on the algorithm:
 518  * \code
 519  *      RSA:    exponent
 520  *              0       use exponent 3
 521  *              !0      use Fermat4 (2^16 + 1)
 522  *      DH:     generator
 523  *              0       default - use well known prime if bits == 768 or 1024,
 524  *                      otherwise use 2 as the generator.
 525  *              !0      use this value as the generator.
 526  *      DSA:    unused
 527  *      HMACMD5: entropy
 528  *              0       default - require good entropy
 529  *              !0      lack of good entropy is ok
 530  *\endcode
 531  *
 532  * Requires:
 533  *\li   "name" is a valid absolute dns name.
 534  *\li   "keyp" is not NULL and "*keyp" is NULL.
 535  *
 536  * Returns:
 537  *\li   ISC_R_SUCCESS
 538  * \li  any other result indicates failure
 539  *
 540  * Ensures:
 541  *\li   If successful, *keyp will contain a valid key.
 542  */
 543
 544 isc_boolean_t
 545 dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
 546 /*%<
 547  * Compares two DST keys.  Returns true if they match, false otherwise.
 548  *
 549  * Keys ARE NOT considered to match if one of them is the revoked version
 550  * of the other.
 551  *
 552  * Requires:
 553  *\li   "key1" is a valid key.
 554  *\li   "key2" is a valid key.
 555  *
 556  * Returns:
 557  *\li   ISC_TRUE
 558  * \li  ISC_FALSE
 559  */
 560
 561 isc_boolean_t
 562 dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2,
 563                    isc_boolean_t match_revoked_key);
 564 /*%<
 565  * Compares only the public portions of two DST keys.  Returns true
 566  * if they match, false otherwise.  This allows us, for example, to
 567  * determine whether a public key found in a zone matches up with a
 568  * key pair found on disk.
 569  *
 570  * If match_revoked_key is TRUE, then keys ARE considered to match if one
 571  * of them is the revoked version of the other. Otherwise, they are not.
 572  *
 573  * Requires:
 574  *\li   "key1" is a valid key.
 575  *\li   "key2" is a valid key.
 576  *
 577  * Returns:
 578  *\li   ISC_TRUE
 579  * \li  ISC_FALSE
 580  */
 581
 582 isc_boolean_t
 583 dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
 584 /*%<
 585  * Compares the parameters of two DST keys.  This is used to determine if
 586  * two (Diffie-Hellman) keys can be used to derive a shared secret.
 587  *
 588  * Requires:
 589  *\li   "key1" is a valid key.
 590  *\li   "key2" is a valid key.
 591  *
 592  * Returns:
 593  *\li   ISC_TRUE
 594  * \li  ISC_FALSE
 595  */
 596
 597 void
 598 dst_key_attach(dst_key_t *source, dst_key_t **target);
 599 /*
 600  * Attach to a existing key increasing the reference count.
 601  *
 602  * Requires:
 603  *\li 'source' to be a valid key.
 604  *\li 'target' to be non-NULL and '*target' to be NULL.
 605  */
 606
 607 void
 608 dst_key_free(dst_key_t **keyp);
 609 /*%<
 610  * Decrement the key's reference counter and, when it reaches zero,
 611  * release all memory associated with the key.
 612  *
 613  * Requires:
 614  *\li   "keyp" is not NULL and "*keyp" is a valid key.
 615  *\li   reference counter greater than zero.
 616  *
 617  * Ensures:
 618  *\li   All memory associated with "*keyp" will be freed.
 619  *\li   *keyp == NULL
 620  */
 621
 622 /*%<
 623  * Accessor functions to obtain key fields.
 624  *
 625  * Require:
 626  *\li   "key" is a valid key.
 627  */
 628 dns_name_t *
 629 dst_key_name(const dst_key_t *key);
 630
 631 unsigned int
 632 dst_key_size(const dst_key_t *key);
 633
 634 unsigned int
 635 dst_key_proto(const dst_key_t *key);
 636
 637 unsigned int
 638 dst_key_alg(const dst_key_t *key);
 639
 640 isc_uint32_t
 641 dst_key_flags(const dst_key_t *key);
 642
 643 dns_keytag_t
 644 dst_key_id(const dst_key_t *key);
 645
 646 dns_keytag_t
 647 dst_key_rid(const dst_key_t *key);
 648
 649 dns_rdataclass_t
 650 dst_key_class(const dst_key_t *key);
 651
 652 isc_boolean_t
 653 dst_key_isprivate(const dst_key_t *key);
 654
 655 isc_boolean_t
 656 dst_key_iszonekey(const dst_key_t *key);
 657
 658 isc_boolean_t
 659 dst_key_isnullkey(const dst_key_t *key);
 660
 661 isc_result_t
 662 dst_key_buildfilename(const dst_key_t *key, int type,
 663                       const char *directory, isc_buffer_t *out);
 664 /*%<
 665  * Generates the filename used by dst to store the specified key.
 666  * If directory is NULL, the current directory is assumed.
 667  *
 668  * Requires:
 669  *\li   "key" is a valid key
 670  *\li   "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
 671  *\li   "out" is a valid buffer
 672  *
 673  * Ensures:
 674  *\li   the file name will be written to "out", and the used pointer will
 675  *              be advanced.
 676  */
 677
 678 isc_result_t
 679 dst_key_sigsize(const dst_key_t *key, unsigned int *n);
 680 /*%<
 681  * Computes the size of a signature generated by the given key.
 682  *
 683  * Requires:
 684  *\li   "key" is a valid key.
 685  *\li   "n" is not NULL
 686  *
 687  * Returns:
 688  *\li   #ISC_R_SUCCESS
 689  *\li   DST_R_UNSUPPORTEDALG
 690  *
 691  * Ensures:
 692  *\li   "n" stores the size of a generated signature
 693  */
 694
 695 isc_result_t
 696 dst_key_secretsize(const dst_key_t *key, unsigned int *n);
 697 /*%<
 698  * Computes the size of a shared secret generated by the given key.
 699  *
 700  * Requires:
 701  *\li   "key" is a valid key.
 702  *\li   "n" is not NULL
 703  *
 704  * Returns:
 705  *\li   #ISC_R_SUCCESS
 706  *\li   DST_R_UNSUPPORTEDALG
 707  *
 708  * Ensures:
 709  *\li   "n" stores the size of a generated shared secret
 710  */
 711
 712 isc_uint16_t
 713 dst_region_computeid(const isc_region_t *source, unsigned int alg);
 714 isc_uint16_t
 715 dst_region_computerid(const isc_region_t *source, unsigned int alg);
 716 /*%<
 717  * Computes the (revoked) key id of the key stored in the provided
 718  * region with the given algorithm.
 719  *
 720  * Requires:
 721  *\li   "source" contains a valid, non-NULL region.
 722  *
 723  * Returns:
 724  *\li   the key id
 725  */
 726
 727 isc_uint16_t
 728 dst_key_getbits(const dst_key_t *key);
 729 /*%<
 730  * Get the number of digest bits required (0 == MAX).
 731  *
 732  * Requires:
 733  *      "key" is a valid key.
 734  */
 735
 736 void
 737 dst_key_setbits(dst_key_t *key, isc_uint16_t bits);
 738 /*%<
 739  * Set the number of digest bits required (0 == MAX).
 740  *
 741  * Requires:
 742  *      "key" is a valid key.
 743  */
 744
 745 isc_result_t
 746 dst_key_setflags(dst_key_t *key, isc_uint32_t flags);
 747 /*
 748  * Set the key flags, and recompute the key ID.
 749  *
 750  * Requires:
 751  *      "key" is a valid key.
 752  */
 753
 754 isc_result_t
 755 dst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep);
 756 /*%<
 757  * Get a member of the numeric metadata array and place it in '*valuep'.
 758  *
 759  * Requires:
 760  *      "key" is a valid key.
 761  *      "type" is no larger than DST_MAX_NUMERIC
 762  *      "timep" is not null.
 763  */
 764
 765 void
 766 dst_key_setnum(dst_key_t *key, int type, isc_uint32_t value);
 767 /*%<
 768  * Set a member of the numeric metadata array.
 769  *
 770  * Requires:
 771  *      "key" is a valid key.
 772  *      "type" is no larger than DST_MAX_NUMERIC
 773  */
 774
 775 void
 776 dst_key_unsetnum(dst_key_t *key, int type);
 777 /*%<
 778  * Flag a member of the numeric metadata array as "not set".
 779  *
 780  * Requires:
 781  *      "key" is a valid key.
 782  *      "type" is no larger than DST_MAX_NUMERIC
 783  */
 784
 785 isc_result_t
 786 dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep);
 787 /*%<
 788  * Get a member of the timing metadata array and place it in '*timep'.
 789  *
 790  * Requires:
 791  *      "key" is a valid key.
 792  *      "type" is no larger than DST_MAX_TIMES
 793  *      "timep" is not null.
 794  */
 795
 796 void
 797 dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when);
 798 /*%<
 799  * Set a member of the timing metadata array.
 800  *
 801  * Requires:
 802  *      "key" is a valid key.
 803  *      "type" is no larger than DST_MAX_TIMES
 804  */
 805
 806 void
 807 dst_key_unsettime(dst_key_t *key, int type);
 808 /*%<
 809  * Flag a member of the timing metadata array as "not set".
 810  *
 811  * Requires:
 812  *      "key" is a valid key.
 813  *      "type" is no larger than DST_MAX_TIMES
 814  */
 815
 816 isc_result_t
 817 dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp);
 818 /*%<
 819  * Get the private key format version number.  (If the key does not have
 820  * a private key associated with it, the version will be 0.0.)  The major
 821  * version number is placed in '*majorp', and the minor version number in
 822  * '*minorp'.
 823  *
 824  * Requires:
 825  *      "key" is a valid key.
 826  *      "majorp" is not NULL.
 827  *      "minorp" is not NULL.
 828  */
 829
 830 void
 831 dst_key_setprivateformat(dst_key_t *key, int major, int minor);
 832 /*%<
 833  * Set the private key format version number.
 834  *
 835  * Requires:
 836  *      "key" is a valid key.
 837  */
 838
 839 #define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7)
 840
 841 void
 842 dst_key_format(const dst_key_t *key, char *cp, unsigned int size);
 843 /*%<
 844  * Write the uniquely identifying information about the key (name,
 845  * algorithm, key ID) into a string 'cp' of size 'size'.
 846  */
 847
 848
 849 isc_buffer_t *
 850 dst_key_tkeytoken(const dst_key_t *key);
 851 /*%<
 852  * Return the token from the TKEY request, if any.  If this key was
 853  * not negotiated via TKEY, return NULL.
 854  *
 855  * Requires:
 856  *      "key" is a valid key.
 857  */
 858
 859
 860 isc_result_t
 861 dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length);
 862 /*%<
 863  * Allocate 'buffer' and dump the key into it in base64 format. The buffer
 864  * is not NUL terminated. The length of the buffer is returned in *length.
 865  *
 866  * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length);
 867  *
 868  * Requires:
 869  *      'buffer' to be non NULL and *buffer to be NULL.
 870  *      'length' to be non NULL and *length to be zero.
 871  *
 872  * Returns:
 873  *      ISC_R_SUCCESS
 874  *      ISC_R_NOMEMORY
 875  *      ISC_R_NOTIMPLEMENTED
 876  *      others.
 877  */
 878
 879 isc_result_t
 880 dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags,
 881                 unsigned int protocol, dns_rdataclass_t rdclass,
 882                 isc_mem_t *mctx, const char *keystr, dst_key_t **keyp);
 883
 884
 885 ISC_LANG_ENDDECLS
 886
 887 #endif /* DST_DST_H */