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