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