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