1 /* $NetBSD: dst.h,v 1.7 2021/04/29 17:26:11 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 #ifndef DST_DST_H 15 #define DST_DST_H 1 16 17 /*! \file dst/dst.h */ 18 19 #include <inttypes.h> 20 #include <stdbool.h> 21 22 #include <isc/lang.h> 23 #include <isc/stdtime.h> 24 25 #include <dns/ds.h> 26 #include <dns/dsdigest.h> 27 #include <dns/log.h> 28 #include <dns/name.h> 29 #include <dns/secalg.h> 30 #include <dns/types.h> 31 32 #include <dst/gssapi.h> 33 34 ISC_LANG_BEGINDECLS 35 36 /*** 37 *** Types 38 ***/ 39 40 /*% 41 * The dst_key structure is opaque. Applications should use the accessor 42 * functions provided to retrieve key attributes. If an application needs 43 * to set attributes, new accessor functions will be written. 44 */ 45 46 typedef struct dst_key dst_key_t; 47 typedef struct dst_context dst_context_t; 48 49 /*% 50 * Key states for the DNSSEC records related to a key: DNSKEY, RRSIG (ksk), 51 * RRSIG (zsk), and DS. 52 * 53 * DST_KEY_STATE_HIDDEN: Records of this type are not published in zone. 54 * This may be because the key parts were never 55 * introduced in the zone, or because the key has 56 * retired and has no records of this type left in 57 * the zone. 58 * DST_KEY_STATE_RUMOURED: Records of this type are published in zone, but 59 * not long enough to ensure all resolvers know 60 * about it. 61 * DST_KEY_STATE_OMNIPRESENT: Records of this type are published in zone long 62 * enough so that all resolvers that know about 63 * these records, no longer have outdated data. 64 * DST_KEY_STATE_UNRETENTIVE: Records of this type have been removed from the 65 * zone, but there may be resolvers that still have 66 * have predecessor records cached. Note that RRSIG 67 * records in this state may actually still be in the 68 * zone because they are reused, but retired RRSIG 69 * records will never be refreshed: A successor key 70 * is used to create signatures. 71 * DST_KEY_STATE_NA: The state is not applicable for this record type. 72 */ 73 typedef enum dst_key_state { 74 DST_KEY_STATE_HIDDEN = 0, 75 DST_KEY_STATE_RUMOURED = 1, 76 DST_KEY_STATE_OMNIPRESENT = 2, 77 DST_KEY_STATE_UNRETENTIVE = 3, 78 DST_KEY_STATE_NA = 4 79 } dst_key_state_t; 80 81 /* DST algorithm codes */ 82 #define DST_ALG_UNKNOWN 0 83 #define DST_ALG_RSA 1 /* Used for parsing RSASHA1, RSASHA256 and RSASHA512 */ 84 #define DST_ALG_RSAMD5 1 85 #define DST_ALG_DH 2 86 #define DST_ALG_DSA 3 87 #define DST_ALG_ECC 4 88 #define DST_ALG_RSASHA1 5 89 #define DST_ALG_NSEC3DSA 6 90 #define DST_ALG_NSEC3RSASHA1 7 91 #define DST_ALG_RSASHA256 8 92 #define DST_ALG_RSASHA512 10 93 #define DST_ALG_ECCGOST 12 94 #define DST_ALG_ECDSA256 13 95 #define DST_ALG_ECDSA384 14 96 #define DST_ALG_ED25519 15 97 #define DST_ALG_ED448 16 98 #define DST_ALG_HMACMD5 157 99 #define DST_ALG_GSSAPI 160 100 #define DST_ALG_HMACSHA1 161 /* XXXMPA */ 101 #define DST_ALG_HMACSHA224 162 /* XXXMPA */ 102 #define DST_ALG_HMACSHA256 163 /* XXXMPA */ 103 #define DST_ALG_HMACSHA384 164 /* XXXMPA */ 104 #define DST_ALG_HMACSHA512 165 /* XXXMPA */ 105 #define DST_ALG_INDIRECT 252 106 #define DST_ALG_PRIVATE 254 107 #define DST_MAX_ALGS 256 108 109 /*% A buffer of this size is large enough to hold any key */ 110 #define DST_KEY_MAXSIZE 1280 111 112 /*% 113 * A buffer of this size is large enough to hold the textual representation 114 * of any key 115 */ 116 #define DST_KEY_MAXTEXTSIZE 2048 117 118 /*% 'Type' for dst_read_key() */ 119 #define DST_TYPE_KEY 0x1000000 /* KEY key */ 120 #define DST_TYPE_PRIVATE 0x2000000 121 #define DST_TYPE_PUBLIC 0x4000000 122 #define DST_TYPE_STATE 0x8000000 123 124 /* Key timing metadata definitions */ 125 #define DST_TIME_CREATED 0 126 #define DST_TIME_PUBLISH 1 127 #define DST_TIME_ACTIVATE 2 128 #define DST_TIME_REVOKE 3 129 #define DST_TIME_INACTIVE 4 130 #define DST_TIME_DELETE 5 131 #define DST_TIME_DSPUBLISH 6 132 #define DST_TIME_SYNCPUBLISH 7 133 #define DST_TIME_SYNCDELETE 8 134 #define DST_TIME_DNSKEY 9 135 #define DST_TIME_ZRRSIG 10 136 #define DST_TIME_KRRSIG 11 137 #define DST_TIME_DS 12 138 #define DST_TIME_DSDELETE 13 139 #define DST_MAX_TIMES 13 140 141 /* Numeric metadata definitions */ 142 #define DST_NUM_PREDECESSOR 0 143 #define DST_NUM_SUCCESSOR 1 144 #define DST_NUM_MAXTTL 2 145 #define DST_NUM_ROLLPERIOD 3 146 #define DST_NUM_LIFETIME 4 147 #define DST_MAX_NUMERIC 4 148 149 /* Boolean metadata definitions */ 150 #define DST_BOOL_KSK 0 151 #define DST_BOOL_ZSK 1 152 #define DST_MAX_BOOLEAN 1 153 154 /* Key state metadata definitions */ 155 #define DST_KEY_DNSKEY 0 156 #define DST_KEY_ZRRSIG 1 157 #define DST_KEY_KRRSIG 2 158 #define DST_KEY_DS 3 159 #define DST_KEY_GOAL 4 160 #define DST_MAX_KEYSTATES 4 161 162 /* 163 * Current format version number of the private key parser. 164 * 165 * When parsing a key file with the same major number but a higher minor 166 * number, the key parser will ignore any fields it does not recognize. 167 * Thus, DST_MINOR_VERSION should be incremented whenever new 168 * fields are added to the private key file (such as new metadata). 169 * 170 * When rewriting these keys, those fields will be dropped, and the 171 * format version set back to the current one.. 172 * 173 * When a key is seen with a higher major number, the key parser will 174 * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented 175 * and DST_MINOR_VERSION set to zero whenever there is a format change 176 * which is not backward compatible to previous versions of the dst_key 177 * parser, such as change in the syntax of an existing field, the removal 178 * of a currently mandatory field, or a new field added which would 179 * alter the functioning of the key if it were absent. 180 */ 181 #define DST_MAJOR_VERSION 1 182 #define DST_MINOR_VERSION 3 183 184 /*** 185 *** Functions 186 ***/ 187 isc_result_t 188 dst_lib_init(isc_mem_t *mctx, const char *engine); 189 /*%< 190 * Initializes the DST subsystem. 191 * 192 * Requires: 193 * \li "mctx" is a valid memory context 194 * 195 * Returns: 196 * \li ISC_R_SUCCESS 197 * \li ISC_R_NOMEMORY 198 * \li DST_R_NOENGINE 199 * 200 * Ensures: 201 * \li DST is properly initialized. 202 */ 203 204 void 205 dst_lib_destroy(void); 206 /*%< 207 * Releases all resources allocated by DST. 208 */ 209 210 bool 211 dst_algorithm_supported(unsigned int alg); 212 /*%< 213 * Checks that a given algorithm is supported by DST. 214 * 215 * Returns: 216 * \li true 217 * \li false 218 */ 219 220 bool 221 dst_ds_digest_supported(unsigned int digest_type); 222 /*%< 223 * Checks that a given digest algorithm is supported by DST. 224 * 225 * Returns: 226 * \li true 227 * \li false 228 */ 229 230 isc_result_t 231 dst_context_create(dst_key_t *key, isc_mem_t *mctx, isc_logcategory_t *category, 232 bool useforsigning, int maxbits, dst_context_t **dctxp); 233 /*%< 234 * Creates a context to be used for a sign or verify operation. 235 * 236 * Requires: 237 * \li "key" is a valid key. 238 * \li "mctx" is a valid memory context. 239 * \li dctxp != NULL && *dctxp == NULL 240 * 241 * Returns: 242 * \li ISC_R_SUCCESS 243 * \li ISC_R_NOMEMORY 244 * 245 * Ensures: 246 * \li *dctxp will contain a usable context. 247 */ 248 249 void 250 dst_context_destroy(dst_context_t **dctxp); 251 /*%< 252 * Destroys all memory associated with a context. 253 * 254 * Requires: 255 * \li *dctxp != NULL && *dctxp == NULL 256 * 257 * Ensures: 258 * \li *dctxp == NULL 259 */ 260 261 isc_result_t 262 dst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 263 /*%< 264 * Incrementally adds data to the context to be used in a sign or verify 265 * operation. 266 * 267 * Requires: 268 * \li "dctx" is a valid context 269 * \li "data" is a valid region 270 * 271 * Returns: 272 * \li ISC_R_SUCCESS 273 * \li DST_R_SIGNFAILURE 274 * \li all other errors indicate failure 275 */ 276 277 isc_result_t 278 dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 279 /*%< 280 * Computes a signature using the data and key stored in the context. 281 * 282 * Requires: 283 * \li "dctx" is a valid context. 284 * \li "sig" is a valid buffer. 285 * 286 * Returns: 287 * \li ISC_R_SUCCESS 288 * \li DST_R_VERIFYFAILURE 289 * \li all other errors indicate failure 290 * 291 * Ensures: 292 * \li "sig" will contain the signature 293 */ 294 295 isc_result_t 296 dst_context_verify(dst_context_t *dctx, isc_region_t *sig); 297 298 isc_result_t 299 dst_context_verify2(dst_context_t *dctx, unsigned int maxbits, 300 isc_region_t *sig); 301 /*%< 302 * Verifies the signature using the data and key stored in the context. 303 * 304 * 'maxbits' specifies the maximum number of bits permitted in the RSA 305 * exponent. 306 * 307 * Requires: 308 * \li "dctx" is a valid context. 309 * \li "sig" is a valid region. 310 * 311 * Returns: 312 * \li ISC_R_SUCCESS 313 * \li all other errors indicate failure 314 * 315 * Ensures: 316 * \li "sig" will contain the signature 317 */ 318 319 isc_result_t 320 dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 321 isc_buffer_t *secret); 322 /*%< 323 * Computes a shared secret from two (Diffie-Hellman) keys. 324 * 325 * Requires: 326 * \li "pub" is a valid key that can be used to derive a shared secret 327 * \li "priv" is a valid private key that can be used to derive a shared secret 328 * \li "secret" is a valid buffer 329 * 330 * Returns: 331 * \li ISC_R_SUCCESS 332 * \li any other result indicates failure 333 * 334 * Ensures: 335 * \li If successful, secret will contain the derived shared secret. 336 */ 337 338 isc_result_t 339 dst_key_getfilename(dns_name_t *name, dns_keytag_t id, unsigned int alg, 340 int type, const char *directory, isc_mem_t *mctx, 341 isc_buffer_t *buf); 342 /*%< 343 * Generates a key filename for the name, algorithm, and 344 * id, and places it in the buffer 'buf'. If directory is NULL, the 345 * current directory is assumed. 346 * 347 * Requires: 348 * \li "name" is a valid absolute dns name. 349 * \li "id" is a valid key tag identifier. 350 * \li "alg" is a supported key algorithm. 351 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 352 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 353 * \li "mctx" is a valid memory context. 354 * \li "buf" is not NULL. 355 * 356 * Returns: 357 * \li ISC_R_SUCCESS 358 * \li any other result indicates failure 359 */ 360 361 isc_result_t 362 dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 363 const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 364 /*%< 365 * Reads a key from permanent storage. The key can either be a public or 366 * private key, or a key state. It specified by name, algorithm, and id. If 367 * a private key or key state is specified, the public key must also be 368 * present. If directory is NULL, the current directory is assumed. 369 * 370 * Requires: 371 * \li "name" is a valid absolute dns name. 372 * \li "id" is a valid key tag identifier. 373 * \li "alg" is a supported key algorithm. 374 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE or the bitwise union. 375 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY. 376 * DST_TYPE_STATE to also read the key state. 377 * \li "mctx" is a valid memory context. 378 * \li "keyp" is not NULL and "*keyp" is NULL. 379 * 380 * Returns: 381 * \li ISC_R_SUCCESS 382 * \li any other result indicates failure 383 * 384 * Ensures: 385 * \li If successful, *keyp will contain a valid key. 386 */ 387 388 isc_result_t 389 dst_key_fromnamedfile(const char *filename, const char *dirname, int type, 390 isc_mem_t *mctx, dst_key_t **keyp); 391 /*%< 392 * Reads a key from permanent storage. The key can either be a public or 393 * private key, or a key state. It is specified by filename. If a private key 394 * or key state is specified, the public key must also be present. 395 * 396 * If 'dirname' is not NULL, and 'filename' is a relative path, 397 * then the file is looked up relative to the given directory. 398 * If 'filename' is an absolute path, 'dirname' is ignored. 399 * 400 * Requires: 401 * \li "filename" is not NULL 402 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 403 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY. 404 * DST_TYPE_STATE to also read the key state. 405 * \li "mctx" is a valid memory context 406 * \li "keyp" is not NULL and "*keyp" is NULL. 407 * 408 * Returns: 409 * \li ISC_R_SUCCESS 410 * \li any other result indicates failure 411 * 412 * Ensures: 413 * \li If successful, *keyp will contain a valid key. 414 */ 415 416 isc_result_t 417 dst_key_read_public(const char *filename, int type, isc_mem_t *mctx, 418 dst_key_t **keyp); 419 /*%< 420 * Reads a public key from permanent storage. The key must be a public key. 421 * 422 * Requires: 423 * \li "filename" is not NULL. 424 * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY. 425 * \li "mctx" is a valid memory context. 426 * \li "keyp" is not NULL and "*keyp" is NULL. 427 * 428 * Returns: 429 * \li ISC_R_SUCCESS 430 * \li DST_R_BADKEYTYPE if the key type is not the expected one 431 * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 432 * \li any other result indicates failure 433 * 434 * Ensures: 435 * \li If successful, *keyp will contain a valid key. 436 */ 437 438 isc_result_t 439 dst_key_read_state(const char *filename, isc_mem_t *mctx, dst_key_t **keyp); 440 /*%< 441 * Reads a key state from permanent storage. 442 * 443 * Requires: 444 * \li "filename" is not NULL. 445 * \li "mctx" is a valid memory context. 446 * \li "keyp" is not NULL and "*keyp" is NULL. 447 * 448 * Returns: 449 * \li ISC_R_SUCCESS 450 * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 451 * \li any other result indicates failure 452 */ 453 454 isc_result_t 455 dst_key_tofile(const dst_key_t *key, int type, const char *directory); 456 /*%< 457 * Writes a key to permanent storage. The key can either be a public or 458 * private key. Public keys are written in DNS format and private keys 459 * are written as a set of base64 encoded values. If directory is NULL, 460 * the current directory is assumed. 461 * 462 * Requires: 463 * \li "key" is a valid key. 464 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 465 * 466 * Returns: 467 * \li ISC_R_SUCCESS 468 * \li any other result indicates failure 469 */ 470 471 isc_result_t 472 dst_key_fromdns(const dns_name_t *name, dns_rdataclass_t rdclass, 473 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 474 /*%< 475 * Converts a DNS KEY record into a DST key. 476 * 477 * Requires: 478 * \li "name" is a valid absolute dns name. 479 * \li "source" is a valid buffer. There must be at least 4 bytes available. 480 * \li "mctx" is a valid memory context. 481 * \li "keyp" is not NULL and "*keyp" is NULL. 482 * 483 * Returns: 484 * \li ISC_R_SUCCESS 485 * \li any other result indicates failure 486 * 487 * Ensures: 488 * \li If successful, *keyp will contain a valid key, and the consumed 489 * pointer in data will be advanced. 490 */ 491 492 isc_result_t 493 dst_key_todns(const dst_key_t *key, isc_buffer_t *target); 494 /*%< 495 * Converts a DST key into a DNS KEY record. 496 * 497 * Requires: 498 * \li "key" is a valid key. 499 * \li "target" is a valid buffer. There must be at least 4 bytes unused. 500 * 501 * Returns: 502 * \li ISC_R_SUCCESS 503 * \li any other result indicates failure 504 * 505 * Ensures: 506 * \li If successful, the used pointer in 'target' is advanced by at least 4. 507 */ 508 509 isc_result_t 510 dst_key_frombuffer(const dns_name_t *name, unsigned int alg, unsigned int flags, 511 unsigned int protocol, dns_rdataclass_t rdclass, 512 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 513 /*%< 514 * Converts a buffer containing DNS KEY RDATA into a DST key. 515 * 516 * Requires: 517 *\li "name" is a valid absolute dns name. 518 *\li "alg" is a supported key algorithm. 519 *\li "source" is a valid buffer. 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 the consumed 529 * pointer in source will be advanced. 530 */ 531 532 isc_result_t 533 dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 534 /*%< 535 * Converts a DST key into DNS KEY RDATA format. 536 * 537 * Requires: 538 *\li "key" is a valid key. 539 *\li "target" is a valid buffer. 540 * 541 * Returns: 542 *\li ISC_R_SUCCESS 543 * \li any other result indicates failure 544 * 545 * Ensures: 546 *\li If successful, the used pointer in 'target' is advanced. 547 */ 548 549 isc_result_t 550 dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 551 /*%< 552 * Converts a public key into a private key, reading the private key 553 * information from the buffer. The buffer should contain the same data 554 * as the .private key file would. 555 * 556 * Requires: 557 *\li "key" is a valid public key. 558 *\li "buffer" is not NULL. 559 * 560 * Returns: 561 *\li ISC_R_SUCCESS 562 * \li any other result indicates failure 563 * 564 * Ensures: 565 *\li If successful, key will contain a valid private key. 566 */ 567 568 dns_gss_ctx_id_t 569 dst_key_getgssctx(const dst_key_t *key); 570 /*%< 571 * Returns the opaque key data. 572 * Be cautions when using this value unless you know what you are doing. 573 * 574 * Requires: 575 *\li "key" is not NULL. 576 * 577 * Returns: 578 *\li gssctx key data, possibly NULL. 579 */ 580 581 isc_result_t 582 dst_key_fromgssapi(const dns_name_t *name, dns_gss_ctx_id_t gssctx, 583 isc_mem_t *mctx, dst_key_t **keyp, isc_region_t *intoken); 584 /*%< 585 * Converts a GSSAPI opaque context id into a DST key. 586 * 587 * Requires: 588 *\li "name" is a valid absolute dns name. 589 *\li "gssctx" is a GSSAPI context id. 590 *\li "mctx" is a valid memory context. 591 *\li "keyp" is not NULL and "*keyp" is NULL. 592 * 593 * Returns: 594 *\li ISC_R_SUCCESS 595 * \li any other result indicates failure 596 * 597 * Ensures: 598 *\li If successful, *keyp will contain a valid key and be responsible for 599 * the context id. 600 */ 601 602 #ifdef DST_KEY_INTERNAL 603 isc_result_t 604 dst_key_buildinternal(const dns_name_t *name, unsigned int alg, 605 unsigned int bits, unsigned int flags, 606 unsigned int protocol, dns_rdataclass_t rdclass, 607 void *data, isc_mem_t *mctx, dst_key_t **keyp); 608 #endif /* ifdef DST_KEY_INTERNAL */ 609 610 isc_result_t 611 dst_key_fromlabel(const dns_name_t *name, int alg, unsigned int flags, 612 unsigned int protocol, dns_rdataclass_t rdclass, 613 const char *engine, const char *label, const char *pin, 614 isc_mem_t *mctx, dst_key_t **keyp); 615 616 isc_result_t 617 dst_key_generate(const dns_name_t *name, unsigned int alg, unsigned int bits, 618 unsigned int param, unsigned int flags, unsigned int protocol, 619 dns_rdataclass_t rdclass, isc_mem_t *mctx, dst_key_t **keyp, 620 void (*callback)(int)); 621 622 /*%< 623 * Generate a DST key (or keypair) with the supplied parameters. The 624 * interpretation of the "param" field depends on the algorithm: 625 * \code 626 * RSA: exponent 627 * 0 use exponent 3 628 * !0 use Fermat4 (2^16 + 1) 629 * DH: generator 630 * 0 default - use well known prime if bits == 768 or 1024, 631 * otherwise use 2 as the generator. 632 * !0 use this value as the generator. 633 * DSA: unused 634 * HMACMD5: entropy 635 * 0 default - require good entropy 636 * !0 lack of good entropy is ok 637 *\endcode 638 * 639 * Requires: 640 *\li "name" is a valid absolute dns name. 641 *\li "keyp" is not NULL and "*keyp" is NULL. 642 * 643 * Returns: 644 *\li ISC_R_SUCCESS 645 * \li any other result indicates failure 646 * 647 * Ensures: 648 *\li If successful, *keyp will contain a valid key. 649 */ 650 651 bool 652 dst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 653 /*%< 654 * Compares two DST keys. Returns true if they match, false otherwise. 655 * 656 * Keys ARE NOT considered to match if one of them is the revoked version 657 * of the other. 658 * 659 * Requires: 660 *\li "key1" is a valid key. 661 *\li "key2" is a valid key. 662 * 663 * Returns: 664 *\li true 665 * \li false 666 */ 667 668 bool 669 dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 670 bool match_revoked_key); 671 /*%< 672 * Compares only the public portions of two DST keys. Returns true 673 * if they match, false otherwise. This allows us, for example, to 674 * determine whether a public key found in a zone matches up with a 675 * key pair found on disk. 676 * 677 * If match_revoked_key is TRUE, then keys ARE considered to match if one 678 * of them is the revoked version of the other. Otherwise, they are not. 679 * 680 * Requires: 681 *\li "key1" is a valid key. 682 *\li "key2" is a valid key. 683 * 684 * Returns: 685 *\li true 686 * \li false 687 */ 688 689 bool 690 dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 691 /*%< 692 * Compares the parameters of two DST keys. This is used to determine if 693 * two (Diffie-Hellman) keys can be used to derive a shared secret. 694 * 695 * Requires: 696 *\li "key1" is a valid key. 697 *\li "key2" is a valid key. 698 * 699 * Returns: 700 *\li true 701 * \li false 702 */ 703 704 void 705 dst_key_attach(dst_key_t *source, dst_key_t **target); 706 /* 707 * Attach to a existing key increasing the reference count. 708 * 709 * Requires: 710 *\li 'source' to be a valid key. 711 *\li 'target' to be non-NULL and '*target' to be NULL. 712 */ 713 714 void 715 dst_key_free(dst_key_t **keyp); 716 /*%< 717 * Decrement the key's reference counter and, when it reaches zero, 718 * release all memory associated with the key. 719 * 720 * Requires: 721 *\li "keyp" is not NULL and "*keyp" is a valid key. 722 *\li reference counter greater than zero. 723 * 724 * Ensures: 725 *\li All memory associated with "*keyp" will be freed. 726 *\li *keyp == NULL 727 */ 728 729 /*%< 730 * Accessor functions to obtain key fields. 731 * 732 * Require: 733 *\li "key" is a valid key. 734 */ 735 dns_name_t * 736 dst_key_name(const dst_key_t *key); 737 738 unsigned int 739 dst_key_size(const dst_key_t *key); 740 741 unsigned int 742 dst_key_proto(const dst_key_t *key); 743 744 unsigned int 745 dst_key_alg(const dst_key_t *key); 746 747 uint32_t 748 dst_key_flags(const dst_key_t *key); 749 750 dns_keytag_t 751 dst_key_id(const dst_key_t *key); 752 753 dns_keytag_t 754 dst_key_rid(const dst_key_t *key); 755 756 dns_rdataclass_t 757 dst_key_class(const dst_key_t *key); 758 759 bool 760 dst_key_isprivate(const dst_key_t *key); 761 762 bool 763 dst_key_iszonekey(const dst_key_t *key); 764 765 bool 766 dst_key_isnullkey(const dst_key_t *key); 767 768 isc_result_t 769 dst_key_buildfilename(const dst_key_t *key, int type, const char *directory, 770 isc_buffer_t *out); 771 /*%< 772 * Generates the filename used by dst to store the specified key. 773 * If directory is NULL, the current directory is assumed. 774 * 775 * Requires: 776 *\li "key" is a valid key 777 *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 778 *\li "out" is a valid buffer 779 * 780 * Ensures: 781 *\li the file name will be written to "out", and the used pointer will 782 * be advanced. 783 */ 784 785 isc_result_t 786 dst_key_sigsize(const dst_key_t *key, unsigned int *n); 787 /*%< 788 * Computes the size of a signature generated by the given key. 789 * 790 * Requires: 791 *\li "key" is a valid key. 792 *\li "n" is not NULL 793 * 794 * Returns: 795 *\li #ISC_R_SUCCESS 796 *\li DST_R_UNSUPPORTEDALG 797 * 798 * Ensures: 799 *\li "n" stores the size of a generated signature 800 */ 801 802 isc_result_t 803 dst_key_secretsize(const dst_key_t *key, unsigned int *n); 804 /*%< 805 * Computes the size of a shared secret generated by the given key. 806 * 807 * Requires: 808 *\li "key" is a valid key. 809 *\li "n" is not NULL 810 * 811 * Returns: 812 *\li #ISC_R_SUCCESS 813 *\li DST_R_UNSUPPORTEDALG 814 * 815 * Ensures: 816 *\li "n" stores the size of a generated shared secret 817 */ 818 819 uint16_t 820 dst_region_computeid(const isc_region_t *source); 821 uint16_t 822 dst_region_computerid(const isc_region_t *source); 823 /*%< 824 * Computes the (revoked) key id of the key stored in the provided 825 * region. 826 * 827 * Requires: 828 *\li "source" contains a valid, non-NULL region. 829 * 830 * Returns: 831 *\li the key id 832 */ 833 834 uint16_t 835 dst_key_getbits(const dst_key_t *key); 836 /*%< 837 * Get the number of digest bits required (0 == MAX). 838 * 839 * Requires: 840 * "key" is a valid key. 841 */ 842 843 void 844 dst_key_setbits(dst_key_t *key, uint16_t bits); 845 /*%< 846 * Set the number of digest bits required (0 == MAX). 847 * 848 * Requires: 849 * "key" is a valid key. 850 */ 851 852 void 853 dst_key_setttl(dst_key_t *key, dns_ttl_t ttl); 854 /*%< 855 * Set the default TTL to use when converting the key 856 * to a KEY or DNSKEY RR. 857 * 858 * Requires: 859 * "key" is a valid key. 860 */ 861 862 dns_ttl_t 863 dst_key_getttl(const dst_key_t *key); 864 /*%< 865 * Get the default TTL to use when converting the key 866 * to a KEY or DNSKEY RR. 867 * 868 * Requires: 869 * "key" is a valid key. 870 */ 871 872 isc_result_t 873 dst_key_setflags(dst_key_t *key, uint32_t flags); 874 /* 875 * Set the key flags, and recompute the key ID. 876 * 877 * Requires: 878 * "key" is a valid key. 879 */ 880 881 isc_result_t 882 dst_key_getbool(const dst_key_t *key, int type, bool *valuep); 883 /*%< 884 * Get a member of the boolean metadata array and place it in '*valuep'. 885 * 886 * Requires: 887 * "key" is a valid key. 888 * "type" is no larger than DST_MAX_BOOLEAN 889 * "valuep" is not null. 890 */ 891 892 void 893 dst_key_setbool(dst_key_t *key, int type, bool value); 894 /*%< 895 * Set a member of the boolean metadata array. 896 * 897 * Requires: 898 * "key" is a valid key. 899 * "type" is no larger than DST_MAX_BOOLEAN 900 */ 901 902 void 903 dst_key_unsetbool(dst_key_t *key, int type); 904 /*%< 905 * Flag a member of the boolean metadata array as "not set". 906 * 907 * Requires: 908 * "key" is a valid key. 909 * "type" is no larger than DST_MAX_BOOLEAN 910 */ 911 912 isc_result_t 913 dst_key_getnum(const dst_key_t *key, int type, uint32_t *valuep); 914 /*%< 915 * Get a member of the numeric metadata array and place it in '*valuep'. 916 * 917 * Requires: 918 * "key" is a valid key. 919 * "type" is no larger than DST_MAX_NUMERIC 920 * "valuep" is not null. 921 */ 922 923 void 924 dst_key_setnum(dst_key_t *key, int type, uint32_t value); 925 /*%< 926 * Set a member of the numeric metadata array. 927 * 928 * Requires: 929 * "key" is a valid key. 930 * "type" is no larger than DST_MAX_NUMERIC 931 */ 932 933 void 934 dst_key_unsetnum(dst_key_t *key, int type); 935 /*%< 936 * Flag a member of the numeric metadata array as "not set". 937 * 938 * Requires: 939 * "key" is a valid key. 940 * "type" is no larger than DST_MAX_NUMERIC 941 */ 942 943 isc_result_t 944 dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 945 /*%< 946 * Get a member of the timing metadata array and place it in '*timep'. 947 * 948 * Requires: 949 * "key" is a valid key. 950 * "type" is no larger than DST_MAX_TIMES 951 * "timep" is not null. 952 */ 953 954 void 955 dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 956 /*%< 957 * Set a member of the timing metadata array. 958 * 959 * Requires: 960 * "key" is a valid key. 961 * "type" is no larger than DST_MAX_TIMES 962 */ 963 964 void 965 dst_key_unsettime(dst_key_t *key, int type); 966 /*%< 967 * Flag a member of the timing metadata array as "not set". 968 * 969 * Requires: 970 * "key" is a valid key. 971 * "type" is no larger than DST_MAX_TIMES 972 */ 973 974 isc_result_t 975 dst_key_getstate(const dst_key_t *key, int type, dst_key_state_t *statep); 976 /*%< 977 * Get a member of the keystate metadata array and place it in '*statep'. 978 * 979 * Requires: 980 * "key" is a valid key. 981 * "type" is no larger than DST_MAX_KEYSTATES 982 * "statep" is not null. 983 */ 984 985 void 986 dst_key_setstate(dst_key_t *key, int type, dst_key_state_t state); 987 /*%< 988 * Set a member of the keystate metadata array. 989 * 990 * Requires: 991 * "key" is a valid key. 992 * "state" is a valid state. 993 * "type" is no larger than DST_MAX_KEYSTATES 994 */ 995 996 void 997 dst_key_unsetstate(dst_key_t *key, int type); 998 /*%< 999 * Flag a member of the keystate metadata array as "not set". 1000 * 1001 * Requires: 1002 * "key" is a valid key. 1003 * "type" is no larger than DST_MAX_KEYSTATES 1004 */ 1005 1006 isc_result_t 1007 dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 1008 /*%< 1009 * Get the private key format version number. (If the key does not have 1010 * a private key associated with it, the version will be 0.0.) The major 1011 * version number is placed in '*majorp', and the minor version number in 1012 * '*minorp'. 1013 * 1014 * Requires: 1015 * "key" is a valid key. 1016 * "majorp" is not NULL. 1017 * "minorp" is not NULL. 1018 */ 1019 1020 void 1021 dst_key_setprivateformat(dst_key_t *key, int major, int minor); 1022 /*%< 1023 * Set the private key format version number. 1024 * 1025 * Requires: 1026 * "key" is a valid key. 1027 */ 1028 1029 #define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 1030 1031 void 1032 dst_key_format(const dst_key_t *key, char *cp, unsigned int size); 1033 /*%< 1034 * Write the uniquely identifying information about the key (name, 1035 * algorithm, key ID) into a string 'cp' of size 'size'. 1036 */ 1037 1038 isc_buffer_t * 1039 dst_key_tkeytoken(const dst_key_t *key); 1040 /*%< 1041 * Return the token from the TKEY request, if any. If this key was 1042 * not negotiated via TKEY, return NULL. 1043 * 1044 * Requires: 1045 * "key" is a valid key. 1046 */ 1047 1048 isc_result_t 1049 dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 1050 /*%< 1051 * Allocate 'buffer' and dump the key into it in base64 format. The buffer 1052 * is not NUL terminated. The length of the buffer is returned in *length. 1053 * 1054 * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 1055 * 1056 * Requires: 1057 * 'buffer' to be non NULL and *buffer to be NULL. 1058 * 'length' to be non NULL and *length to be zero. 1059 * 1060 * Returns: 1061 * ISC_R_SUCCESS 1062 * ISC_R_NOMEMORY 1063 * ISC_R_NOTIMPLEMENTED 1064 * others. 1065 */ 1066 1067 isc_result_t 1068 dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 1069 unsigned int protocol, dns_rdataclass_t rdclass, 1070 isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 1071 1072 bool 1073 dst_key_inactive(const dst_key_t *key); 1074 /*%< 1075 * Determines if the private key is missing due the key being deemed inactive. 1076 * 1077 * Requires: 1078 * 'key' to be valid. 1079 */ 1080 1081 void 1082 dst_key_setinactive(dst_key_t *key, bool inactive); 1083 /*%< 1084 * Set key inactive state. 1085 * 1086 * Requires: 1087 * 'key' to be valid. 1088 */ 1089 1090 void 1091 dst_key_setexternal(dst_key_t *key, bool value); 1092 /*%< 1093 * Set key external state. 1094 * 1095 * Requires: 1096 * 'key' to be valid. 1097 */ 1098 1099 bool 1100 dst_key_isexternal(dst_key_t *key); 1101 /*%< 1102 * Check if this is an external key. 1103 * 1104 * Requires: 1105 * 'key' to be valid. 1106 */ 1107 1108 bool 1109 dst_key_haskasp(dst_key_t *key); 1110 /*%< 1111 * Check if this key has state (and thus uses KASP). 1112 * 1113 * Requires: 1114 * 'key' to be valid. 1115 */ 1116 1117 bool 1118 dst_key_is_unused(dst_key_t *key); 1119 /*%< 1120 * Check if this key is unused. 1121 * 1122 * Requires: 1123 * 'key' to be valid. 1124 */ 1125 1126 bool 1127 dst_key_is_published(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *publish); 1128 /*%< 1129 * Check if it is safe to publish this key (e.g. put the DNSKEY in the zone). 1130 * 1131 * Requires: 1132 * 'key' to be valid. 1133 */ 1134 1135 bool 1136 dst_key_is_active(dst_key_t *key, isc_stdtime_t now); 1137 /*%< 1138 * Check if this key is active. This means that it is creating RRSIG records 1139 * (ZSK), or that it is used to create a chain of trust (KSK), or both (CSK). 1140 * 1141 * Requires: 1142 * 'key' to be valid. 1143 */ 1144 1145 bool 1146 dst_key_is_signing(dst_key_t *key, int role, isc_stdtime_t now, 1147 isc_stdtime_t *active); 1148 /*%< 1149 * Check if it is safe to use this key for signing, given the role. 1150 * 1151 * Requires: 1152 * 'key' to be valid. 1153 */ 1154 1155 bool 1156 dst_key_is_revoked(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *revoke); 1157 /*%< 1158 * Check if this key is revoked. 1159 * 1160 * Requires: 1161 * 'key' to be valid. 1162 */ 1163 1164 bool 1165 dst_key_is_removed(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *remove); 1166 /*%< 1167 * Check if this key is removed from the zone (e.g. the DNSKEY record should 1168 * no longer be in the zone). 1169 * 1170 * Requires: 1171 * 'key' to be valid. 1172 */ 1173 1174 dst_key_state_t 1175 dst_key_goal(dst_key_t *key); 1176 /*%< 1177 * Get the key goal. Should be OMNIPRESENT or HIDDEN. 1178 * This can be used to determine if the key is being introduced or 1179 * is on its way out. 1180 * 1181 * Requires: 1182 * 'key' to be valid. 1183 */ 1184 1185 void 1186 dst_key_copy_metadata(dst_key_t *to, dst_key_t *from); 1187 /*%< 1188 * Copy key metadata from one key to another. 1189 * 1190 * Requires: 1191 * 'to' and 'from' to be valid. 1192 */ 1193 1194 ISC_LANG_ENDDECLS 1195 1196 #endif /* DST_DST_H */ 1197