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