1193323Sed/* $NetBSD: dst.h,v 1.11 2024/02/21 22:52:11 christos Exp $ */ 2193323Sed 3193323Sed/* 4193323Sed * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5193323Sed * 6193323Sed * SPDX-License-Identifier: MPL-2.0 7193323Sed * 8193323Sed * This Source Code Form is subject to the terms of the Mozilla Public 9193323Sed * License, v. 2.0. If a copy of the MPL was not distributed with this 10193323Sed * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11193323Sed * 12193323Sed * See the COPYRIGHT file distributed with this work for additional 13193323Sed * information regarding copyright ownership. 14193323Sed */ 15193323Sed 16193323Sed#pragma once 17193323Sed 18193323Sed/*! \file dst/dst.h */ 19193323Sed 20193323Sed#include <inttypes.h> 21193323Sed#include <stdbool.h> 22193323Sed 23193323Sed#include <isc/lang.h> 24193323Sed#include <isc/stdtime.h> 25193323Sed 26193323Sed#include <dns/ds.h> 27193323Sed#include <dns/dsdigest.h> 28193323Sed#include <dns/log.h> 29193323Sed#include <dns/name.h> 30193323Sed#include <dns/secalg.h> 31193323Sed#include <dns/types.h> 32193323Sed 33193323Sed#include <dst/gssapi.h> 34193323Sed 35193323SedISC_LANG_BEGINDECLS 36193323Sed 37193323Sed/*** 38193323Sed *** Types 39193323Sed ***/ 40193323Sed 41193323Sed/*% 42193323Sed * The dst_key structure is opaque. Applications should use the accessor 43193323Sed * functions provided to retrieve key attributes. If an application needs 44193323Sed * to set attributes, new accessor functions will be written. 45193323Sed */ 46193323Sed 47193323Sedtypedef struct dst_key dst_key_t; 48193323Sedtypedef struct dst_context dst_context_t; 49193323Sed 50193323Sed/*% 51193323Sed * 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 */ 74typedef 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 */ 83typedef 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, 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 ***/ 202isc_result_t 203dst_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 219void 220dst_lib_destroy(void); 221/*%< 222 * Releases all resources allocated by DST. 223 */ 224 225bool 226dst_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 235bool 236dst_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 245isc_result_t 246dst_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 264void 265dst_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 276isc_result_t 277dst_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 292isc_result_t 293dst_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 310isc_result_t 311dst_context_verify(dst_context_t *dctx, isc_region_t *sig); 312 313isc_result_t 314dst_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 334isc_result_t 335dst_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 353isc_result_t 354dst_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 376isc_result_t 377dst_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 403isc_result_t 404dst_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 431isc_result_t 432dst_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 453isc_result_t 454dst_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 469isc_result_t 470dst_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 486isc_result_t 487dst_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); 490isc_result_t 491dst_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 511isc_result_t 512dst_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 528isc_result_t 529dst_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 551isc_result_t 552dst_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 568isc_result_t 569dst_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 587dns_gss_ctx_id_t 588dst_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 600isc_result_t 601dst_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 622isc_result_t 623dst_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 629isc_result_t 630dst_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 635isc_result_t 636dst_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, isc_mem_t *mctx, dst_key_t **keyp, 639 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 * DH: generator 649 * 0 default - use well known prime if bits == 768 or 1024, 650 * otherwise use 2 as the generator. 651 * !0 use this value as the generator. 652 * DSA: unused 653 * HMACMD5: entropy 654 * 0 default - require good entropy 655 * !0 lack of good entropy is ok 656 *\endcode 657 * 658 * Requires: 659 *\li "name" is a valid absolute dns name. 660 *\li "keyp" is not NULL and "*keyp" is NULL. 661 * 662 * Returns: 663 *\li ISC_R_SUCCESS 664 * \li any other result indicates failure 665 * 666 * Ensures: 667 *\li If successful, *keyp will contain a valid key. 668 */ 669 670bool 671dst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 672/*%< 673 * Compares two DST keys. Returns true if they match, false otherwise. 674 * 675 * Keys ARE NOT considered to match if one of them is the revoked version 676 * of the other. 677 * 678 * Requires: 679 *\li "key1" is a valid key. 680 *\li "key2" is a valid key. 681 * 682 * Returns: 683 *\li true 684 * \li false 685 */ 686 687bool 688dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 689 bool match_revoked_key); 690/*%< 691 * Compares only the public portions of two DST keys. Returns true 692 * if they match, false otherwise. This allows us, for example, to 693 * determine whether a public key found in a zone matches up with a 694 * key pair found on disk. 695 * 696 * If match_revoked_key is TRUE, then keys ARE considered to match if one 697 * of them is the revoked version of the other. Otherwise, they are not. 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 708bool 709dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 710/*%< 711 * Compares the parameters of two DST keys. This is used to determine if 712 * two (Diffie-Hellman) keys can be used to derive a shared secret. 713 * 714 * Requires: 715 *\li "key1" is a valid key. 716 *\li "key2" is a valid key. 717 * 718 * Returns: 719 *\li true 720 * \li false 721 */ 722 723void 724dst_key_attach(dst_key_t *source, dst_key_t **target); 725/* 726 * Attach to a existing key increasing the reference count. 727 * 728 * Requires: 729 *\li 'source' to be a valid key. 730 *\li 'target' to be non-NULL and '*target' to be NULL. 731 */ 732 733void 734dst_key_free(dst_key_t **keyp); 735/*%< 736 * Decrement the key's reference counter and, when it reaches zero, 737 * release all memory associated with the key. 738 * 739 * Requires: 740 *\li "keyp" is not NULL and "*keyp" is a valid key. 741 *\li reference counter greater than zero. 742 * 743 * Ensures: 744 *\li All memory associated with "*keyp" will be freed. 745 *\li *keyp == NULL 746 */ 747 748/*%< 749 * Accessor functions to obtain key fields. 750 * 751 * Require: 752 *\li "key" is a valid key. 753 */ 754dns_name_t * 755dst_key_name(const dst_key_t *key); 756 757unsigned int 758dst_key_size(const dst_key_t *key); 759 760unsigned int 761dst_key_proto(const dst_key_t *key); 762 763unsigned int 764dst_key_alg(const dst_key_t *key); 765 766uint32_t 767dst_key_flags(const dst_key_t *key); 768 769dns_keytag_t 770dst_key_id(const dst_key_t *key); 771 772dns_keytag_t 773dst_key_rid(const dst_key_t *key); 774 775dns_rdataclass_t 776dst_key_class(const dst_key_t *key); 777 778bool 779dst_key_isprivate(const dst_key_t *key); 780 781bool 782dst_key_iszonekey(const dst_key_t *key); 783 784bool 785dst_key_isnullkey(const dst_key_t *key); 786 787isc_result_t 788dst_key_buildfilename(const dst_key_t *key, int type, const char *directory, 789 isc_buffer_t *out); 790/*%< 791 * Generates the filename used by dst to store the specified key. 792 * If directory is NULL, the current directory is assumed. 793 * If tmp is not NULL, generates a template for mkstemp(). 794 * 795 * Requires: 796 *\li "key" is a valid key 797 *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 798 *\li "out" is a valid buffer 799 *\li "tmp" is a valid buffer or NULL 800 * 801 * Ensures: 802 *\li the file name will be written to "out", and the used pointer will 803 * be advanced. 804 */ 805 806isc_result_t 807dst_key_sigsize(const dst_key_t *key, unsigned int *n); 808/*%< 809 * Computes the size of a signature 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 signature 821 */ 822 823isc_result_t 824dst_key_secretsize(const dst_key_t *key, unsigned int *n); 825/*%< 826 * Computes the size of a shared secret generated by the given key. 827 * 828 * Requires: 829 *\li "key" is a valid key. 830 *\li "n" is not NULL 831 * 832 * Returns: 833 *\li #ISC_R_SUCCESS 834 *\li DST_R_UNSUPPORTEDALG 835 * 836 * Ensures: 837 *\li "n" stores the size of a generated shared secret 838 */ 839 840uint16_t 841dst_region_computeid(const isc_region_t *source); 842uint16_t 843dst_region_computerid(const isc_region_t *source); 844/*%< 845 * Computes the (revoked) key id of the key stored in the provided 846 * region. 847 * 848 * Requires: 849 *\li "source" contains a valid, non-NULL region. 850 * 851 * Returns: 852 *\li the key id 853 */ 854 855uint16_t 856dst_key_getbits(const dst_key_t *key); 857/*%< 858 * Get the number of digest bits required (0 == MAX). 859 * 860 * Requires: 861 * "key" is a valid key. 862 */ 863 864void 865dst_key_setbits(dst_key_t *key, uint16_t bits); 866/*%< 867 * Set the number of digest bits required (0 == MAX). 868 * 869 * Requires: 870 * "key" is a valid key. 871 */ 872 873void 874dst_key_setttl(dst_key_t *key, dns_ttl_t ttl); 875/*%< 876 * Set the default TTL to use when converting the key 877 * to a KEY or DNSKEY RR. 878 * 879 * Requires: 880 * "key" is a valid key. 881 */ 882 883dns_ttl_t 884dst_key_getttl(const dst_key_t *key); 885/*%< 886 * Get the default TTL to use when converting the key 887 * to a KEY or DNSKEY RR. 888 * 889 * Requires: 890 * "key" is a valid key. 891 */ 892 893isc_result_t 894dst_key_setflags(dst_key_t *key, uint32_t flags); 895/* 896 * Set the key flags, and recompute the key ID. 897 * 898 * Requires: 899 * "key" is a valid key. 900 */ 901 902isc_result_t 903dst_key_getbool(const dst_key_t *key, int type, bool *valuep); 904/*%< 905 * Get a member of the boolean metadata array and place it in '*valuep'. 906 * 907 * Requires: 908 * "key" is a valid key. 909 * "type" is no larger than DST_MAX_BOOLEAN 910 * "valuep" is not null. 911 */ 912 913void 914dst_key_setbool(dst_key_t *key, int type, bool value); 915/*%< 916 * Set a member of the boolean metadata array. 917 * 918 * Requires: 919 * "key" is a valid key. 920 * "type" is no larger than DST_MAX_BOOLEAN 921 */ 922 923void 924dst_key_unsetbool(dst_key_t *key, int type); 925/*%< 926 * Flag a member of the boolean metadata array as "not set". 927 * 928 * Requires: 929 * "key" is a valid key. 930 * "type" is no larger than DST_MAX_BOOLEAN 931 */ 932 933isc_result_t 934dst_key_getnum(const dst_key_t *key, int type, uint32_t *valuep); 935/*%< 936 * Get a member of the numeric metadata array and place it in '*valuep'. 937 * 938 * Requires: 939 * "key" is a valid key. 940 * "type" is no larger than DST_MAX_NUMERIC 941 * "valuep" is not null. 942 */ 943 944void 945dst_key_setnum(dst_key_t *key, int type, uint32_t value); 946/*%< 947 * Set a member of the numeric metadata array. 948 * 949 * Requires: 950 * "key" is a valid key. 951 * "type" is no larger than DST_MAX_NUMERIC 952 */ 953 954void 955dst_key_unsetnum(dst_key_t *key, int type); 956/*%< 957 * Flag a member of the numeric metadata array as "not set". 958 * 959 * Requires: 960 * "key" is a valid key. 961 * "type" is no larger than DST_MAX_NUMERIC 962 */ 963 964isc_result_t 965dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 966/*%< 967 * Get a member of the timing metadata array and place it in '*timep'. 968 * 969 * Requires: 970 * "key" is a valid key. 971 * "type" is no larger than DST_MAX_TIMES 972 * "timep" is not null. 973 */ 974 975void 976dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 977/*%< 978 * Set a member of the timing metadata array. 979 * 980 * Requires: 981 * "key" is a valid key. 982 * "type" is no larger than DST_MAX_TIMES 983 */ 984 985void 986dst_key_unsettime(dst_key_t *key, int type); 987/*%< 988 * Flag a member of the timing metadata array as "not set". 989 * 990 * Requires: 991 * "key" is a valid key. 992 * "type" is no larger than DST_MAX_TIMES 993 */ 994 995isc_result_t 996dst_key_getstate(const dst_key_t *key, int type, dst_key_state_t *statep); 997/*%< 998 * Get a member of the keystate metadata array and place it in '*statep'. 999 * 1000 * Requires: 1001 * "key" is a valid key. 1002 * "type" is no larger than DST_MAX_KEYSTATES 1003 * "statep" is not null. 1004 */ 1005 1006void 1007dst_key_setstate(dst_key_t *key, int type, dst_key_state_t state); 1008/*%< 1009 * Set a member of the keystate metadata array. 1010 * 1011 * Requires: 1012 * "key" is a valid key. 1013 * "state" is a valid state. 1014 * "type" is no larger than DST_MAX_KEYSTATES 1015 */ 1016 1017void 1018dst_key_unsetstate(dst_key_t *key, int type); 1019/*%< 1020 * Flag a member of the keystate metadata array as "not set". 1021 * 1022 * Requires: 1023 * "key" is a valid key. 1024 * "type" is no larger than DST_MAX_KEYSTATES 1025 */ 1026 1027isc_result_t 1028dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 1029/*%< 1030 * Get the private key format version number. (If the key does not have 1031 * a private key associated with it, the version will be 0.0.) The major 1032 * version number is placed in '*majorp', and the minor version number in 1033 * '*minorp'. 1034 * 1035 * Requires: 1036 * "key" is a valid key. 1037 * "majorp" is not NULL. 1038 * "minorp" is not NULL. 1039 */ 1040 1041void 1042dst_key_setprivateformat(dst_key_t *key, int major, int minor); 1043/*%< 1044 * Set the private key format version number. 1045 * 1046 * Requires: 1047 * "key" is a valid key. 1048 */ 1049 1050#define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 1051 1052void 1053dst_key_format(const dst_key_t *key, char *cp, unsigned int size); 1054/*%< 1055 * Write the uniquely identifying information about the key (name, 1056 * algorithm, key ID) into a string 'cp' of size 'size'. 1057 */ 1058 1059isc_buffer_t * 1060dst_key_tkeytoken(const dst_key_t *key); 1061/*%< 1062 * Return the token from the TKEY request, if any. If this key was 1063 * not negotiated via TKEY, return NULL. 1064 * 1065 * Requires: 1066 * "key" is a valid key. 1067 */ 1068 1069isc_result_t 1070dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 1071/*%< 1072 * Allocate 'buffer' and dump the key into it in base64 format. The buffer 1073 * is not NUL terminated. The length of the buffer is returned in *length. 1074 * 1075 * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 1076 * 1077 * Requires: 1078 * 'buffer' to be non NULL and *buffer to be NULL. 1079 * 'length' to be non NULL and *length to be zero. 1080 * 1081 * Returns: 1082 * ISC_R_SUCCESS 1083 * ISC_R_NOMEMORY 1084 * ISC_R_NOTIMPLEMENTED 1085 * others. 1086 */ 1087 1088isc_result_t 1089dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 1090 unsigned int protocol, dns_rdataclass_t rdclass, 1091 isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 1092 1093bool 1094dst_key_inactive(const dst_key_t *key); 1095/*%< 1096 * Determines if the private key is missing due the key being deemed inactive. 1097 * 1098 * Requires: 1099 * 'key' to be valid. 1100 */ 1101 1102void 1103dst_key_setinactive(dst_key_t *key, bool inactive); 1104/*%< 1105 * Set key inactive state. 1106 * 1107 * Requires: 1108 * 'key' to be valid. 1109 */ 1110 1111void 1112dst_key_setexternal(dst_key_t *key, bool value); 1113/*%< 1114 * Set key external state. 1115 * 1116 * Requires: 1117 * 'key' to be valid. 1118 */ 1119 1120bool 1121dst_key_isexternal(dst_key_t *key); 1122/*%< 1123 * Check if this is an external key. 1124 * 1125 * Requires: 1126 * 'key' to be valid. 1127 */ 1128 1129void 1130dst_key_setmodified(dst_key_t *key, bool value); 1131/*%< 1132 * If 'value' is true, this marks the key to indicate that key file metadata 1133 * has been modified. If 'value' is false, this resets the value, for example 1134 * after you have written the key to file. 1135 * 1136 * Requires: 1137 * 'key' to be valid. 1138 */ 1139 1140bool 1141dst_key_ismodified(const dst_key_t *key); 1142/*%< 1143 * Check if the key file has been modified. 1144 * 1145 * Requires: 1146 * 'key' to be valid. 1147 */ 1148 1149bool 1150dst_key_haskasp(dst_key_t *key); 1151/*%< 1152 * Check if this key has state (and thus uses KASP). 1153 * 1154 * Requires: 1155 * 'key' to be valid. 1156 */ 1157 1158bool 1159dst_key_is_unused(dst_key_t *key); 1160/*%< 1161 * Check if this key is unused. 1162 * 1163 * Requires: 1164 * 'key' to be valid. 1165 */ 1166 1167bool 1168dst_key_is_published(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *publish); 1169/*%< 1170 * Check if it is safe to publish this key (e.g. put the DNSKEY in the zone). 1171 * 1172 * Requires: 1173 * 'key' to be valid. 1174 */ 1175 1176bool 1177dst_key_is_active(dst_key_t *key, isc_stdtime_t now); 1178/*%< 1179 * Check if this key is active. This means that it is creating RRSIG records 1180 * (ZSK), or that it is used to create a chain of trust (KSK), or both (CSK). 1181 * 1182 * Requires: 1183 * 'key' to be valid. 1184 */ 1185 1186bool 1187dst_key_is_signing(dst_key_t *key, int role, isc_stdtime_t now, 1188 isc_stdtime_t *active); 1189/*%< 1190 * Check if it is safe to use this key for signing, given the role. 1191 * 1192 * Requires: 1193 * 'key' to be valid. 1194 */ 1195 1196bool 1197dst_key_is_revoked(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *revoke); 1198/*%< 1199 * Check if this key is revoked. 1200 * 1201 * Requires: 1202 * 'key' to be valid. 1203 */ 1204 1205bool 1206dst_key_is_removed(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *remove); 1207/*%< 1208 * Check if this key is removed from the zone (e.g. the DNSKEY record should 1209 * no longer be in the zone). 1210 * 1211 * Requires: 1212 * 'key' to be valid. 1213 */ 1214 1215dst_key_state_t 1216dst_key_goal(dst_key_t *key); 1217/*%< 1218 * Get the key goal. Should be OMNIPRESENT or HIDDEN. 1219 * This can be used to determine if the key is being introduced or 1220 * is on its way out. 1221 * 1222 * Requires: 1223 * 'key' to be valid. 1224 */ 1225 1226isc_result_t 1227dst_key_role(dst_key_t *key, bool *ksk, bool *zsk); 1228/*%< 1229 * Get the key role. A key can have the KSK or the ZSK role, or both. 1230 * 1231 * Requires: 1232 * 'key' to be valid. 1233 */ 1234 1235void 1236dst_key_copy_metadata(dst_key_t *to, dst_key_t *from); 1237/*%< 1238 * Copy key metadata from one key to another. 1239 * 1240 * Requires: 1241 * 'to' and 'from' to be valid. 1242 */ 1243 1244const char * 1245dst_hmac_algorithm_totext(dst_algorithm_t alg); 1246/*$< 1247 * Return the name associtated with the HMAC algorithm 'alg' 1248 * or return "unknown". 1249 */ 1250 1251ISC_LANG_ENDDECLS 1252