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: dst.h,v 1.34 2011/10/20 21:20:02 marka Exp $ */
  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 isc_result_t
 244 dst_context_verify2(dst_context_t *dctx, unsigned int maxbits,
 245                     isc_region_t *sig);
 246 /*%<
 247  * Verifies the signature using the data and key stored in the context.
 248  *
 249  * 'maxbits' specifies the maximum number of bits permitted in the RSA
 250  * exponent.
 251  *
 252  * Requires:
 253  * \li  "dctx" is a valid context.
 254  * \li  "sig" is a valid region.
 255  *
 256  * Returns:
 257  * \li  ISC_R_SUCCESS
 258  * \li  all other errors indicate failure
 259  *
 260  * Ensures:
 261  * \li  "sig" will contain the signature
 262  */
 263
 264 isc_result_t
 265 dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
 266                       isc_buffer_t *secret);
 267 /*%<
 268  * Computes a shared secret from two (Diffie-Hellman) keys.
 269  *
 270  * Requires:
 271  * \li  "pub" is a valid key that can be used to derive a shared secret
 272  * \li  "priv" is a valid private key that can be used to derive a shared secret
 273  * \li  "secret" is a valid buffer
 274  *
 275  * Returns:
 276  * \li  ISC_R_SUCCESS
 277  * \li  any other result indicates failure
 278  *
 279  * Ensures:
 280  * \li  If successful, secret will contain the derived shared secret.
 281  */
 282
 283 isc_result_t
 284 dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
 285                  const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
 286 /*%<
 287  * Reads a key from permanent storage.  The key can either be a public or
 288  * private key, and is specified by name, algorithm, and id.  If a private key
 289  * is specified, the public key must also be present.  If directory is NULL,
 290  * the current directory is assumed.
 291  *
 292  * Requires:
 293  * \li  "name" is a valid absolute dns name.
 294  * \li  "id" is a valid key tag identifier.
 295  * \li  "alg" is a supported key algorithm.
 296  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
 297  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 298  * \li  "mctx" is a valid memory context.
 299  * \li  "keyp" is not NULL and "*keyp" is NULL.
 300  *
 301  * Returns:
 302  * \li  ISC_R_SUCCESS
 303  * \li  any other result indicates failure
 304  *
 305  * Ensures:
 306  * \li  If successful, *keyp will contain a valid key.
 307  */
 308
 309 isc_result_t
 310 dst_key_fromnamedfile(const char *filename, const char *dirname,
 311                       int type, isc_mem_t *mctx, dst_key_t **keyp);
 312 /*%<
 313  * Reads a key from permanent storage.  The key can either be a public or
 314  * key, and is specified by filename.  If a private key is specified, the
 315  * public key must also be present.
 316  *
 317  * If 'dirname' is not NULL, and 'filename' is a relative path,
 318  * then the file is looked up relative to the given directory.
 319  * If 'filename' is an absolute path, 'dirname' is ignored.
 320  *
 321  * Requires:
 322  * \li  "filename" is not NULL
 323  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 324  *                DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 325  * \li  "mctx" is a valid memory context
 326  * \li  "keyp" is not NULL and "*keyp" is NULL.
 327  *
 328  * Returns:
 329  * \li  ISC_R_SUCCESS
 330  * \li  any other result indicates failure
 331  *
 332  * Ensures:
 333  * \li  If successful, *keyp will contain a valid key.
 334  */
 335
 336
 337 isc_result_t
 338 dst_key_read_public(const char *filename, int type,
 339                     isc_mem_t *mctx, dst_key_t **keyp);
 340 /*%<
 341  * Reads a public key from permanent storage.  The key must be a public key.
 342  *
 343  * Requires:
 344  * \li  "filename" is not NULL
 345  * \li  "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY
 346  * \li  "mctx" is a valid memory context
 347  * \li  "keyp" is not NULL and "*keyp" is NULL.
 348  *
 349  * Returns:
 350  * \li  ISC_R_SUCCESS
 351  * \li  DST_R_BADKEYTYPE if the key type is not the expected one
 352  * \li  ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
 353  * \li  any other result indicates failure
 354  *
 355  * Ensures:
 356  * \li  If successful, *keyp will contain a valid key.
 357  */
 358
 359 isc_result_t
 360 dst_key_tofile(const dst_key_t *key, int type, const char *directory);
 361 /*%<
 362  * Writes a key to permanent storage.  The key can either be a public or
 363  * private key.  Public keys are written in DNS format and private keys
 364  * are written as a set of base64 encoded values.  If directory is NULL,
 365  * the current directory is assumed.
 366  *
 367  * Requires:
 368  * \li  "key" is a valid key.
 369  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
 370  *
 371  * Returns:
 372  * \li  ISC_R_SUCCESS
 373  * \li  any other result indicates failure
 374  */
 375
 376 isc_result_t
 377 dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass,
 378                 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 379 /*%<
 380  * Converts a DNS KEY record into a DST key.
 381  *
 382  * Requires:
 383  * \li  "name" is a valid absolute dns name.
 384  * \li  "source" is a valid buffer.  There must be at least 4 bytes available.
 385  * \li  "mctx" is a valid memory context.
 386  * \li  "keyp" is not NULL and "*keyp" is NULL.
 387  *
 388  * Returns:
 389  * \li  ISC_R_SUCCESS
 390  * \li  any other result indicates failure
 391  *
 392  * Ensures:
 393  * \li  If successful, *keyp will contain a valid key, and the consumed
 394  *      pointer in data will be advanced.
 395  */
 396
 397 isc_result_t
 398 dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
 399 /*%<
 400  * Converts a DST key into a DNS KEY record.
 401  *
 402  * Requires:
 403  * \li  "key" is a valid key.
 404  * \li  "target" is a valid buffer.  There must be at least 4 bytes unused.
 405  *
 406  * Returns:
 407  * \li  ISC_R_SUCCESS
 408  * \li  any other result indicates failure
 409  *
 410  * Ensures:
 411  * \li  If successful, the used pointer in 'target' is advanced by at least 4.
 412  */
 413
 414 isc_result_t
 415 dst_key_frombuffer(dns_name_t *name, unsigned int alg,
 416                    unsigned int flags, unsigned int protocol,
 417                    dns_rdataclass_t rdclass,
 418                    isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
 419 /*%<
 420  * Converts a buffer containing DNS KEY RDATA into a DST key.
 421  *
 422  * Requires:
 423  *\li   "name" is a valid absolute dns name.
 424  *\li   "alg" is a supported key algorithm.
 425  *\li   "source" is a valid buffer.
 426  *\li   "mctx" is a valid memory context.
 427  *\li   "keyp" is not NULL and "*keyp" is NULL.
 428  *
 429  * Returns:
 430  *\li   ISC_R_SUCCESS
 431  * \li  any other result indicates failure
 432  *
 433  * Ensures:
 434  *\li   If successful, *keyp will contain a valid key, and the consumed
 435  *      pointer in source will be advanced.
 436  */
 437
 438 isc_result_t
 439 dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
 440 /*%<
 441  * Converts a DST key into DNS KEY RDATA format.
 442  *
 443  * Requires:
 444  *\li   "key" is a valid key.
 445  *\li   "target" is a valid buffer.
 446  *
 447  * Returns:
 448  *\li   ISC_R_SUCCESS
 449  * \li  any other result indicates failure
 450  *
 451  * Ensures:
 452  *\li   If successful, the used pointer in 'target' is advanced.
 453  */
 454
 455 isc_result_t
 456 dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
 457 /*%<
 458  * Converts a public key into a private key, reading the private key
 459  * information from the buffer.  The buffer should contain the same data
 460  * as the .private key file would.
 461  *
 462  * Requires:
 463  *\li   "key" is a valid public key.
 464  *\li   "buffer" is not NULL.
 465  *
 466  * Returns:
 467  *\li   ISC_R_SUCCESS
 468  * \li  any other result indicates failure
 469  *
 470  * Ensures:
 471  *\li   If successful, key will contain a valid private key.
 472  */
 473
 474 gss_ctx_id_t
 475 dst_key_getgssctx(const dst_key_t *key);
 476 /*%<
 477  * Returns the opaque key data.
 478  * Be cautions when using this value unless you know what you are doing.
 479  *
 480  * Requires:
 481  *\li   "key" is not NULL.
 482  *
 483  * Returns:
 484  *\li   gssctx key data, possibly NULL.
 485  */
 486
 487 isc_result_t
 488 dst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx,
 489                    dst_key_t **keyp, isc_region_t *intoken);
 490 /*%<
 491  * Converts a GSSAPI opaque context id into a DST key.
 492  *
 493  * Requires:
 494  *\li   "name" is a valid absolute dns name.
 495  *\li   "gssctx" is a GSSAPI context id.
 496  *\li   "mctx" is a valid memory context.
 497  *\li   "keyp" is not NULL and "*keyp" is NULL.
 498  *
 499  * Returns:
 500  *\li   ISC_R_SUCCESS
 501  * \li  any other result indicates failure
 502  *
 503  * Ensures:
 504  *\li   If successful, *keyp will contain a valid key and be responsible for
 505  *      the context id.
 506  */
 507
 508 #ifdef DST_KEY_INTERNAL
 509 isc_result_t
 510 dst_key_buildinternal(dns_name_t *name, unsigned int alg,
 511                       unsigned int bits, unsigned int flags,
 512                       unsigned int protocol, dns_rdataclass_t rdclass,
 513                       void *data, isc_mem_t *mctx, dst_key_t **keyp);
 514 #endif
 515
 516 isc_result_t
 517 dst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags,
 518                   unsigned int protocol, dns_rdataclass_t rdclass,
 519                   const char *engine, const char *label, const char *pin,
 520                   isc_mem_t *mctx, dst_key_t **keyp);
 521
 522 isc_result_t
 523 dst_key_generate(dns_name_t *name, unsigned int alg,
 524                  unsigned int bits, unsigned int param,
 525                  unsigned int flags, unsigned int protocol,
 526                  dns_rdataclass_t rdclass,
 527                  isc_mem_t *mctx, dst_key_t **keyp);
 528
 529 isc_result_t
 530 dst_key_generate2(dns_name_t *name, unsigned int alg,
 531                   unsigned int bits, unsigned int param,
 532                   unsigned int flags, unsigned int protocol,
 533                   dns_rdataclass_t rdclass,
 534                   isc_mem_t *mctx, dst_key_t **keyp,
 535                   void (*callback)(int));
 536
 537 /*%<
 538  * Generate a DST key (or keypair) with the supplied parameters.  The
 539  * interpretation of the "param" field depends on the algorithm:
 540  * \code
 541  *      RSA:    exponent
 542  *              0       use exponent 3
 543  *              !0      use Fermat4 (2^16 + 1)
 544  *      DH:     generator
 545  *              0       default - use well known prime if bits == 768 or 1024,
 546  *                      otherwise use 2 as the generator.
 547  *              !0      use this value as the generator.
 548  *      DSA:    unused
 549  *      HMACMD5: entropy
 550  *              0       default - require good entropy
 551  *              !0      lack of good entropy is ok
 552  *\endcode
 553  *
 554  * Requires:
 555  *\li   "name" is a valid absolute dns name.
 556  *\li   "keyp" is not NULL and "*keyp" is NULL.
 557  *
 558  * Returns:
 559  *\li   ISC_R_SUCCESS
 560  * \li  any other result indicates failure
 561  *
 562  * Ensures:
 563  *\li   If successful, *keyp will contain a valid key.
 564  */
 565
 566 isc_boolean_t
 567 dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
 568 /*%<
 569  * Compares two DST keys.  Returns true if they match, false otherwise.
 570  *
 571  * Keys ARE NOT considered to match if one of them is the revoked version
 572  * of the other.
 573  *
 574  * Requires:
 575  *\li   "key1" is a valid key.
 576  *\li   "key2" is a valid key.
 577  *
 578  * Returns:
 579  *\li   ISC_TRUE
 580  * \li  ISC_FALSE
 581  */
 582
 583 isc_boolean_t
 584 dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2,
 585                    isc_boolean_t match_revoked_key);
 586 /*%<
 587  * Compares only the public portions of two DST keys.  Returns true
 588  * if they match, false otherwise.  This allows us, for example, to
 589  * determine whether a public key found in a zone matches up with a
 590  * key pair found on disk.
 591  *
 592  * If match_revoked_key is TRUE, then keys ARE considered to match if one
 593  * of them is the revoked version of the other. Otherwise, they are not.
 594  *
 595  * Requires:
 596  *\li   "key1" is a valid key.
 597  *\li   "key2" is a valid key.
 598  *
 599  * Returns:
 600  *\li   ISC_TRUE
 601  * \li  ISC_FALSE
 602  */
 603
 604 isc_boolean_t
 605 dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
 606 /*%<
 607  * Compares the parameters of two DST keys.  This is used to determine if
 608  * two (Diffie-Hellman) keys can be used to derive a shared secret.
 609  *
 610  * Requires:
 611  *\li   "key1" is a valid key.
 612  *\li   "key2" is a valid key.
 613  *
 614  * Returns:
 615  *\li   ISC_TRUE
 616  * \li  ISC_FALSE
 617  */
 618
 619 void
 620 dst_key_attach(dst_key_t *source, dst_key_t **target);
 621 /*
 622  * Attach to a existing key increasing the reference count.
 623  *
 624  * Requires:
 625  *\li 'source' to be a valid key.
 626  *\li 'target' to be non-NULL and '*target' to be NULL.
 627  */
 628
 629 void
 630 dst_key_free(dst_key_t **keyp);
 631 /*%<
 632  * Decrement the key's reference counter and, when it reaches zero,
 633  * release all memory associated with the key.
 634  *
 635  * Requires:
 636  *\li   "keyp" is not NULL and "*keyp" is a valid key.
 637  *\li   reference counter greater than zero.
 638  *
 639  * Ensures:
 640  *\li   All memory associated with "*keyp" will be freed.
 641  *\li   *keyp == NULL
 642  */
 643
 644 /*%<
 645  * Accessor functions to obtain key fields.
 646  *
 647  * Require:
 648  *\li   "key" is a valid key.
 649  */
 650 dns_name_t *
 651 dst_key_name(const dst_key_t *key);
 652
 653 unsigned int
 654 dst_key_size(const dst_key_t *key);
 655
 656 unsigned int
 657 dst_key_proto(const dst_key_t *key);
 658
 659 unsigned int
 660 dst_key_alg(const dst_key_t *key);
 661
 662 isc_uint32_t
 663 dst_key_flags(const dst_key_t *key);
 664
 665 dns_keytag_t
 666 dst_key_id(const dst_key_t *key);
 667
 668 dns_keytag_t
 669 dst_key_rid(const dst_key_t *key);
 670
 671 dns_rdataclass_t
 672 dst_key_class(const dst_key_t *key);
 673
 674 isc_boolean_t
 675 dst_key_isprivate(const dst_key_t *key);
 676
 677 isc_boolean_t
 678 dst_key_iszonekey(const dst_key_t *key);
 679
 680 isc_boolean_t
 681 dst_key_isnullkey(const dst_key_t *key);
 682
 683 isc_result_t
 684 dst_key_buildfilename(const dst_key_t *key, int type,
 685                       const char *directory, isc_buffer_t *out);
 686 /*%<
 687  * Generates the filename used by dst to store the specified key.
 688  * If directory is NULL, the current directory is assumed.
 689  *
 690  * Requires:
 691  *\li   "key" is a valid key
 692  *\li   "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
 693  *\li   "out" is a valid buffer
 694  *
 695  * Ensures:
 696  *\li   the file name will be written to "out", and the used pointer will
 697  *              be advanced.
 698  */
 699
 700 isc_result_t
 701 dst_key_sigsize(const dst_key_t *key, unsigned int *n);
 702 /*%<
 703  * Computes the size of a signature generated by the given key.
 704  *
 705  * Requires:
 706  *\li   "key" is a valid key.
 707  *\li   "n" is not NULL
 708  *
 709  * Returns:
 710  *\li   #ISC_R_SUCCESS
 711  *\li   DST_R_UNSUPPORTEDALG
 712  *
 713  * Ensures:
 714  *\li   "n" stores the size of a generated signature
 715  */
 716
 717 isc_result_t
 718 dst_key_secretsize(const dst_key_t *key, unsigned int *n);
 719 /*%<
 720  * Computes the size of a shared secret generated by the given key.
 721  *
 722  * Requires:
 723  *\li   "key" is a valid key.
 724  *\li   "n" is not NULL
 725  *
 726  * Returns:
 727  *\li   #ISC_R_SUCCESS
 728  *\li   DST_R_UNSUPPORTEDALG
 729  *
 730  * Ensures:
 731  *\li   "n" stores the size of a generated shared secret
 732  */
 733
 734 isc_uint16_t
 735 dst_region_computeid(const isc_region_t *source, unsigned int alg);
 736 isc_uint16_t
 737 dst_region_computerid(const isc_region_t *source, unsigned int alg);
 738 /*%<
 739  * Computes the (revoked) key id of the key stored in the provided
 740  * region with the given algorithm.
 741  *
 742  * Requires:
 743  *\li   "source" contains a valid, non-NULL region.
 744  *
 745  * Returns:
 746  *\li   the key id
 747  */
 748
 749 isc_uint16_t
 750 dst_key_getbits(const dst_key_t *key);
 751 /*%<
 752  * Get the number of digest bits required (0 == MAX).
 753  *
 754  * Requires:
 755  *      "key" is a valid key.
 756  */
 757
 758 void
 759 dst_key_setbits(dst_key_t *key, isc_uint16_t bits);
 760 /*%<
 761  * Set the number of digest bits required (0 == MAX).
 762  *
 763  * Requires:
 764  *      "key" is a valid key.
 765  */
 766
 767 void
 768 dst_key_setttl(dst_key_t *key, dns_ttl_t ttl);
 769 /*%<
 770  * Set the default TTL to use when converting the key
 771  * to a KEY or DNSKEY RR.
 772  *
 773  * Requires:
 774  *      "key" is a valid key.
 775  */
 776
 777 dns_ttl_t
 778 dst_key_getttl(const dst_key_t *key);
 779 /*%<
 780  * Get the default TTL to use when converting the key
 781  * to a KEY or DNSKEY RR.
 782  *
 783  * Requires:
 784  *      "key" is a valid key.
 785  */
 786
 787 isc_result_t
 788 dst_key_setflags(dst_key_t *key, isc_uint32_t flags);
 789 /*
 790  * Set the key flags, and recompute the key ID.
 791  *
 792  * Requires:
 793  *      "key" is a valid key.
 794  */
 795
 796 isc_result_t
 797 dst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep);
 798 /*%<
 799  * Get a member of the numeric metadata array and place it in '*valuep'.
 800  *
 801  * Requires:
 802  *      "key" is a valid key.
 803  *      "type" is no larger than DST_MAX_NUMERIC
 804  *      "timep" is not null.
 805  */
 806
 807 void
 808 dst_key_setnum(dst_key_t *key, int type, isc_uint32_t value);
 809 /*%<
 810  * Set a member of the numeric metadata array.
 811  *
 812  * Requires:
 813  *      "key" is a valid key.
 814  *      "type" is no larger than DST_MAX_NUMERIC
 815  */
 816
 817 void
 818 dst_key_unsetnum(dst_key_t *key, int type);
 819 /*%<
 820  * Flag a member of the numeric metadata array as "not set".
 821  *
 822  * Requires:
 823  *      "key" is a valid key.
 824  *      "type" is no larger than DST_MAX_NUMERIC
 825  */
 826
 827 isc_result_t
 828 dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep);
 829 /*%<
 830  * Get a member of the timing metadata array and place it in '*timep'.
 831  *
 832  * Requires:
 833  *      "key" is a valid key.
 834  *      "type" is no larger than DST_MAX_TIMES
 835  *      "timep" is not null.
 836  */
 837
 838 void
 839 dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when);
 840 /*%<
 841  * Set a member of the timing metadata array.
 842  *
 843  * Requires:
 844  *      "key" is a valid key.
 845  *      "type" is no larger than DST_MAX_TIMES
 846  */
 847
 848 void
 849 dst_key_unsettime(dst_key_t *key, int type);
 850 /*%<
 851  * Flag a member of the timing metadata array as "not set".
 852  *
 853  * Requires:
 854  *      "key" is a valid key.
 855  *      "type" is no larger than DST_MAX_TIMES
 856  */
 857
 858 isc_result_t
 859 dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp);
 860 /*%<
 861  * Get the private key format version number.  (If the key does not have
 862  * a private key associated with it, the version will be 0.0.)  The major
 863  * version number is placed in '*majorp', and the minor version number in
 864  * '*minorp'.
 865  *
 866  * Requires:
 867  *      "key" is a valid key.
 868  *      "majorp" is not NULL.
 869  *      "minorp" is not NULL.
 870  */
 871
 872 void
 873 dst_key_setprivateformat(dst_key_t *key, int major, int minor);
 874 /*%<
 875  * Set the private key format version number.
 876  *
 877  * Requires:
 878  *      "key" is a valid key.
 879  */
 880
 881 #define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7)
 882
 883 void
 884 dst_key_format(const dst_key_t *key, char *cp, unsigned int size);
 885 /*%<
 886  * Write the uniquely identifying information about the key (name,
 887  * algorithm, key ID) into a string 'cp' of size 'size'.
 888  */
 889
 890
 891 isc_buffer_t *
 892 dst_key_tkeytoken(const dst_key_t *key);
 893 /*%<
 894  * Return the token from the TKEY request, if any.  If this key was
 895  * not negotiated via TKEY, return NULL.
 896  *
 897  * Requires:
 898  *      "key" is a valid key.
 899  */
 900
 901
 902 isc_result_t
 903 dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length);
 904 /*%<
 905  * Allocate 'buffer' and dump the key into it in base64 format. The buffer
 906  * is not NUL terminated. The length of the buffer is returned in *length.
 907  *
 908  * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length);
 909  *
 910  * Requires:
 911  *      'buffer' to be non NULL and *buffer to be NULL.
 912  *      'length' to be non NULL and *length to be zero.
 913  *
 914  * Returns:
 915  *      ISC_R_SUCCESS
 916  *      ISC_R_NOMEMORY
 917  *      ISC_R_NOTIMPLEMENTED
 918  *      others.
 919  */
 920
 921 isc_result_t
 922 dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags,
 923                 unsigned int protocol, dns_rdataclass_t rdclass,
 924                 isc_mem_t *mctx, const char *keystr, dst_key_t **keyp);
 925
 926 isc_boolean_t
 927 dst_key_inactive(const dst_key_t *key);
 928 /*%<
 929  * Determines if the private key is missing due the key being deemed inactive.
 930  *
 931  * Requires:
 932  *      'key' to be valid.
 933  */
 934
 935 void
 936 dst_key_setinactive(dst_key_t *key, isc_boolean_t inactive);
 937 /*%<
 938  * Set key inactive state.
 939  *
 940  * Requires:
 941  *      'key' to be valid.
 942  */
 943
 944 void
 945 dst_key_setexternal(dst_key_t *key, isc_boolean_t value);
 946
 947 isc_boolean_t
 948 dst_key_isexternal(dst_key_t *key);
 949
 950 ISC_LANG_ENDDECLS
 951
 952 #endif /* DST_DST_H */