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