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