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