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

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