1/* 2 * Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 2000-2002 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* $Id$ */ 19 20#ifndef DST_DST_H 21#define DST_DST_H 1 22 23/*! \file dst/dst.h */ 24 25#include <isc/lang.h> 26#include <isc/stdtime.h> 27 28#include <dns/types.h> 29#include <dns/name.h> 30#include <dns/secalg.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/* DST algorithm codes */ 50#define DST_ALG_UNKNOWN 0 51#define DST_ALG_RSAMD5 1 52#define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ 53#define DST_ALG_DH 2 54#define DST_ALG_DSA 3 55#define DST_ALG_ECC 4 56#define DST_ALG_RSASHA1 5 57#define DST_ALG_NSEC3DSA 6 58#define DST_ALG_NSEC3RSASHA1 7 59#define DST_ALG_RSASHA256 8 60#define DST_ALG_RSASHA512 10 61#define DST_ALG_ECCGOST 12 62#define DST_ALG_HMACMD5 157 63#define DST_ALG_GSSAPI 160 64#define DST_ALG_HMACSHA1 161 /* XXXMPA */ 65#define DST_ALG_HMACSHA224 162 /* XXXMPA */ 66#define DST_ALG_HMACSHA256 163 /* XXXMPA */ 67#define DST_ALG_HMACSHA384 164 /* XXXMPA */ 68#define DST_ALG_HMACSHA512 165 /* XXXMPA */ 69#define DST_ALG_PRIVATE 254 70#define DST_ALG_EXPAND 255 71#define DST_MAX_ALGS 255 72 73/*% A buffer of this size is large enough to hold any key */ 74#define DST_KEY_MAXSIZE 1280 75 76/*% 77 * A buffer of this size is large enough to hold the textual representation 78 * of any key 79 */ 80#define DST_KEY_MAXTEXTSIZE 2048 81 82/*% 'Type' for dst_read_key() */ 83#define DST_TYPE_KEY 0x1000000 /* KEY key */ 84#define DST_TYPE_PRIVATE 0x2000000 85#define DST_TYPE_PUBLIC 0x4000000 86 87/* Key timing metadata definitions */ 88#define DST_TIME_CREATED 0 89#define DST_TIME_PUBLISH 1 90#define DST_TIME_ACTIVATE 2 91#define DST_TIME_REVOKE 3 92#define DST_TIME_INACTIVE 4 93#define DST_TIME_DELETE 5 94#define DST_TIME_DSPUBLISH 6 95#define DST_MAX_TIMES 6 96 97/* Numeric metadata definitions */ 98#define DST_NUM_PREDECESSOR 0 99#define DST_NUM_SUCCESSOR 1 100#define DST_NUM_MAXTTL 2 101#define DST_NUM_ROLLPERIOD 3 102#define DST_MAX_NUMERIC 3 103 104/* 105 * Current format version number of the private key parser. 106 * 107 * When parsing a key file with the same major number but a higher minor 108 * number, the key parser will ignore any fields it does not recognize. 109 * Thus, DST_MINOR_VERSION should be incremented whenever new 110 * fields are added to the private key file (such as new metadata). 111 * 112 * When rewriting these keys, those fields will be dropped, and the 113 * format version set back to the current one.. 114 * 115 * When a key is seen with a higher major number, the key parser will 116 * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented 117 * and DST_MINOR_VERSION set to zero whenever there is a format change 118 * which is not backward compatible to previous versions of the dst_key 119 * parser, such as change in the syntax of an existing field, the removal 120 * of a currently mandatory field, or a new field added which would 121 * alter the functioning of the key if it were absent. 122 */ 123#define DST_MAJOR_VERSION 1 124#define DST_MINOR_VERSION 3 125 126/*** 127 *** Functions 128 ***/ 129 130isc_result_t 131dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); 132 133isc_result_t 134dst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx, 135 const char *engine, unsigned int eflags); 136/*%< 137 * Initializes the DST subsystem. 138 * 139 * Requires: 140 * \li "mctx" is a valid memory context 141 * \li "ectx" is a valid entropy context 142 * 143 * Returns: 144 * \li ISC_R_SUCCESS 145 * \li ISC_R_NOMEMORY 146 * \li DST_R_NOENGINE 147 * 148 * Ensures: 149 * \li DST is properly initialized. 150 */ 151 152void 153dst_lib_destroy(void); 154/*%< 155 * Releases all resources allocated by DST. 156 */ 157 158isc_boolean_t 159dst_algorithm_supported(unsigned int alg); 160/*%< 161 * Checks that a given algorithm is supported by DST. 162 * 163 * Returns: 164 * \li ISC_TRUE 165 * \li ISC_FALSE 166 */ 167 168isc_result_t 169dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); 170/*%< 171 * Creates a context to be used for a sign or verify operation. 172 * 173 * Requires: 174 * \li "key" is a valid key. 175 * \li "mctx" is a valid memory context. 176 * \li dctxp != NULL && *dctxp == NULL 177 * 178 * Returns: 179 * \li ISC_R_SUCCESS 180 * \li ISC_R_NOMEMORY 181 * 182 * Ensures: 183 * \li *dctxp will contain a usable context. 184 */ 185 186void 187dst_context_destroy(dst_context_t **dctxp); 188/*%< 189 * Destroys all memory associated with a context. 190 * 191 * Requires: 192 * \li *dctxp != NULL && *dctxp == NULL 193 * 194 * Ensures: 195 * \li *dctxp == NULL 196 */ 197 198isc_result_t 199dst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 200/*%< 201 * Incrementally adds data to the context to be used in a sign or verify 202 * operation. 203 * 204 * Requires: 205 * \li "dctx" is a valid context 206 * \li "data" is a valid region 207 * 208 * Returns: 209 * \li ISC_R_SUCCESS 210 * \li DST_R_SIGNFAILURE 211 * \li all other errors indicate failure 212 */ 213 214isc_result_t 215dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 216/*%< 217 * Computes a signature using the data and key stored in the context. 218 * 219 * Requires: 220 * \li "dctx" is a valid context. 221 * \li "sig" is a valid buffer. 222 * 223 * Returns: 224 * \li ISC_R_SUCCESS 225 * \li DST_R_VERIFYFAILURE 226 * \li all other errors indicate failure 227 * 228 * Ensures: 229 * \li "sig" will contain the signature 230 */ 231 232isc_result_t 233dst_context_verify(dst_context_t *dctx, isc_region_t *sig); 234/*%< 235 * Verifies the signature using the data and key stored in the context. 236 * 237 * Requires: 238 * \li "dctx" is a valid context. 239 * \li "sig" is a valid region. 240 * 241 * Returns: 242 * \li ISC_R_SUCCESS 243 * \li all other errors indicate failure 244 * 245 * Ensures: 246 * \li "sig" will contain the signature 247 */ 248 249isc_result_t 250dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 251 isc_buffer_t *secret); 252/*%< 253 * Computes a shared secret from two (Diffie-Hellman) keys. 254 * 255 * Requires: 256 * \li "pub" is a valid key that can be used to derive a shared secret 257 * \li "priv" is a valid private key that can be used to derive a shared secret 258 * \li "secret" is a valid buffer 259 * 260 * Returns: 261 * \li ISC_R_SUCCESS 262 * \li any other result indicates failure 263 * 264 * Ensures: 265 * \li If successful, secret will contain the derived shared secret. 266 */ 267 268isc_result_t 269dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 270 const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 271/*%< 272 * Reads a key from permanent storage. The key can either be a public or 273 * private key, and is specified by name, algorithm, and id. If a private key 274 * is specified, the public key must also be present. If directory is NULL, 275 * the current directory is assumed. 276 * 277 * Requires: 278 * \li "name" is a valid absolute dns name. 279 * \li "id" is a valid key tag identifier. 280 * \li "alg" is a supported key algorithm. 281 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 282 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 283 * \li "mctx" is a valid memory context. 284 * \li "keyp" is not NULL and "*keyp" is NULL. 285 * 286 * Returns: 287 * \li ISC_R_SUCCESS 288 * \li any other result indicates failure 289 * 290 * Ensures: 291 * \li If successful, *keyp will contain a valid key. 292 */ 293 294isc_result_t 295dst_key_fromnamedfile(const char *filename, const char *dirname, 296 int type, isc_mem_t *mctx, dst_key_t **keyp); 297/*%< 298 * Reads a key from permanent storage. The key can either be a public or 299 * key, and is specified by filename. If a private key is specified, the 300 * public key must also be present. 301 * 302 * If 'dirname' is not NULL, and 'filename' is a relative path, 303 * then the file is looked up relative to the given directory. 304 * If 'filename' is an absolute path, 'dirname' is ignored. 305 * 306 * Requires: 307 * \li "filename" is not NULL 308 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 309 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 310 * \li "mctx" is a valid memory context 311 * \li "keyp" is not NULL and "*keyp" is NULL. 312 * 313 * Returns: 314 * \li ISC_R_SUCCESS 315 * \li any other result indicates failure 316 * 317 * Ensures: 318 * \li If successful, *keyp will contain a valid key. 319 */ 320 321 322isc_result_t 323dst_key_read_public(const char *filename, int type, 324 isc_mem_t *mctx, dst_key_t **keyp); 325/*%< 326 * Reads a public key from permanent storage. The key must be a public key. 327 * 328 * Requires: 329 * \li "filename" is not NULL 330 * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 331 * \li "mctx" is a valid memory context 332 * \li "keyp" is not NULL and "*keyp" is NULL. 333 * 334 * Returns: 335 * \li ISC_R_SUCCESS 336 * \li DST_R_BADKEYTYPE if the key type is not the expected one 337 * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 338 * \li any other result indicates failure 339 * 340 * Ensures: 341 * \li If successful, *keyp will contain a valid key. 342 */ 343 344isc_result_t 345dst_key_tofile(const dst_key_t *key, int type, const char *directory); 346/*%< 347 * Writes a key to permanent storage. The key can either be a public or 348 * private key. Public keys are written in DNS format and private keys 349 * are written as a set of base64 encoded values. If directory is NULL, 350 * the current directory is assumed. 351 * 352 * Requires: 353 * \li "key" is a valid key. 354 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 355 * 356 * Returns: 357 * \li ISC_R_SUCCESS 358 * \li any other result indicates failure 359 */ 360 361isc_result_t 362dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 363 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 364/*%< 365 * Converts a DNS KEY record into a DST key. 366 * 367 * Requires: 368 * \li "name" is a valid absolute dns name. 369 * \li "source" is a valid buffer. There must be at least 4 bytes available. 370 * \li "mctx" is a valid memory context. 371 * \li "keyp" is not NULL and "*keyp" is NULL. 372 * 373 * Returns: 374 * \li ISC_R_SUCCESS 375 * \li any other result indicates failure 376 * 377 * Ensures: 378 * \li If successful, *keyp will contain a valid key, and the consumed 379 * pointer in data will be advanced. 380 */ 381 382isc_result_t 383dst_key_todns(const dst_key_t *key, isc_buffer_t *target); 384/*%< 385 * Converts a DST key into a DNS KEY record. 386 * 387 * Requires: 388 * \li "key" is a valid key. 389 * \li "target" is a valid buffer. There must be at least 4 bytes unused. 390 * 391 * Returns: 392 * \li ISC_R_SUCCESS 393 * \li any other result indicates failure 394 * 395 * Ensures: 396 * \li If successful, the used pointer in 'target' is advanced by at least 4. 397 */ 398 399isc_result_t 400dst_key_frombuffer(dns_name_t *name, unsigned int alg, 401 unsigned int flags, unsigned int protocol, 402 dns_rdataclass_t rdclass, 403 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 404/*%< 405 * Converts a buffer containing DNS KEY RDATA into a DST key. 406 * 407 * Requires: 408 *\li "name" is a valid absolute dns name. 409 *\li "alg" is a supported key algorithm. 410 *\li "source" is a valid buffer. 411 *\li "mctx" is a valid memory context. 412 *\li "keyp" is not NULL and "*keyp" is NULL. 413 * 414 * Returns: 415 *\li ISC_R_SUCCESS 416 * \li any other result indicates failure 417 * 418 * Ensures: 419 *\li If successful, *keyp will contain a valid key, and the consumed 420 * pointer in source will be advanced. 421 */ 422 423isc_result_t 424dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 425/*%< 426 * Converts a DST key into DNS KEY RDATA format. 427 * 428 * Requires: 429 *\li "key" is a valid key. 430 *\li "target" is a valid buffer. 431 * 432 * Returns: 433 *\li ISC_R_SUCCESS 434 * \li any other result indicates failure 435 * 436 * Ensures: 437 *\li If successful, the used pointer in 'target' is advanced. 438 */ 439 440isc_result_t 441dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 442/*%< 443 * Converts a public key into a private key, reading the private key 444 * information from the buffer. The buffer should contain the same data 445 * as the .private key file would. 446 * 447 * Requires: 448 *\li "key" is a valid public key. 449 *\li "buffer" is not NULL. 450 * 451 * Returns: 452 *\li ISC_R_SUCCESS 453 * \li any other result indicates failure 454 * 455 * Ensures: 456 *\li If successful, key will contain a valid private key. 457 */ 458 459gss_ctx_id_t 460dst_key_getgssctx(const dst_key_t *key); 461/*%< 462 * Returns the opaque key data. 463 * Be cautions when using this value unless you know what you are doing. 464 * 465 * Requires: 466 *\li "key" is not NULL. 467 * 468 * Returns: 469 *\li gssctx key data, possibly NULL. 470 */ 471 472isc_result_t 473dst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 474 dst_key_t **keyp, isc_region_t *intoken); 475/*%< 476 * Converts a GSSAPI opaque context id into a DST key. 477 * 478 * Requires: 479 *\li "name" is a valid absolute dns name. 480 *\li "gssctx" is a GSSAPI context id. 481 *\li "mctx" is a valid memory context. 482 *\li "keyp" is not NULL and "*keyp" is NULL. 483 * 484 * Returns: 485 *\li ISC_R_SUCCESS 486 * \li any other result indicates failure 487 * 488 * Ensures: 489 *\li If successful, *keyp will contain a valid key and be responsible for 490 * the context id. 491 */ 492 493isc_result_t 494dst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 495 unsigned int protocol, dns_rdataclass_t rdclass, 496 const char *engine, const char *label, const char *pin, 497 isc_mem_t *mctx, dst_key_t **keyp); 498 499isc_result_t 500dst_key_generate(dns_name_t *name, unsigned int alg, 501 unsigned int bits, unsigned int param, 502 unsigned int flags, unsigned int protocol, 503 dns_rdataclass_t rdclass, 504 isc_mem_t *mctx, dst_key_t **keyp); 505 506isc_result_t 507dst_key_generate2(dns_name_t *name, unsigned int alg, 508 unsigned int bits, unsigned int param, 509 unsigned int flags, unsigned int protocol, 510 dns_rdataclass_t rdclass, 511 isc_mem_t *mctx, dst_key_t **keyp, 512 void (*callback)(int)); 513/*%< 514 * Generate a DST key (or keypair) with the supplied parameters. The 515 * interpretation of the "param" field depends on the algorithm: 516 * \code 517 * RSA: exponent 518 * 0 use exponent 3 519 * !0 use Fermat4 (2^16 + 1) 520 * DH: generator 521 * 0 default - use well known prime if bits == 768 or 1024, 522 * otherwise use 2 as the generator. 523 * !0 use this value as the generator. 524 * DSA: unused 525 * HMACMD5: entropy 526 * 0 default - require good entropy 527 * !0 lack of good entropy is ok 528 *\endcode 529 * 530 * Requires: 531 *\li "name" is a valid absolute dns name. 532 *\li "keyp" is not NULL and "*keyp" is NULL. 533 * 534 * Returns: 535 *\li ISC_R_SUCCESS 536 * \li any other result indicates failure 537 * 538 * Ensures: 539 *\li If successful, *keyp will contain a valid key. 540 */ 541 542isc_boolean_t 543dst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 544/*%< 545 * Compares two DST keys. Returns true if they match, false otherwise. 546 * 547 * Keys ARE NOT considered to match if one of them is the revoked version 548 * of the other. 549 * 550 * Requires: 551 *\li "key1" is a valid key. 552 *\li "key2" is a valid key. 553 * 554 * Returns: 555 *\li ISC_TRUE 556 * \li ISC_FALSE 557 */ 558 559isc_boolean_t 560dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 561 isc_boolean_t match_revoked_key); 562/*%< 563 * Compares only the public portions of two DST keys. Returns true 564 * if they match, false otherwise. This allows us, for example, to 565 * determine whether a public key found in a zone matches up with a 566 * key pair found on disk. 567 * 568 * If match_revoked_key is TRUE, then keys ARE considered to match if one 569 * of them is the revoked version of the other. Otherwise, they are not. 570 * 571 * Requires: 572 *\li "key1" is a valid key. 573 *\li "key2" is a valid key. 574 * 575 * Returns: 576 *\li ISC_TRUE 577 * \li ISC_FALSE 578 */ 579 580isc_boolean_t 581dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 582/*%< 583 * Compares the parameters of two DST keys. This is used to determine if 584 * two (Diffie-Hellman) keys can be used to derive a shared secret. 585 * 586 * Requires: 587 *\li "key1" is a valid key. 588 *\li "key2" is a valid key. 589 * 590 * Returns: 591 *\li ISC_TRUE 592 * \li ISC_FALSE 593 */ 594 595void 596dst_key_attach(dst_key_t *source, dst_key_t **target); 597/* 598 * Attach to a existing key increasing the reference count. 599 * 600 * Requires: 601 *\li 'source' to be a valid key. 602 *\li 'target' to be non-NULL and '*target' to be NULL. 603 */ 604 605void 606dst_key_free(dst_key_t **keyp); 607/*%< 608 * Decrement the key's reference counter and, when it reaches zero, 609 * release all memory associated with the key. 610 * 611 * Requires: 612 *\li "keyp" is not NULL and "*keyp" is a valid key. 613 *\li reference counter greater than zero. 614 * 615 * Ensures: 616 *\li All memory associated with "*keyp" will be freed. 617 *\li *keyp == NULL 618 */ 619 620/*%< 621 * Accessor functions to obtain key fields. 622 * 623 * Require: 624 *\li "key" is a valid key. 625 */ 626dns_name_t * 627dst_key_name(const dst_key_t *key); 628 629unsigned int 630dst_key_size(const dst_key_t *key); 631 632unsigned int 633dst_key_proto(const dst_key_t *key); 634 635unsigned int 636dst_key_alg(const dst_key_t *key); 637 638isc_uint32_t 639dst_key_flags(const dst_key_t *key); 640 641dns_keytag_t 642dst_key_id(const dst_key_t *key); 643 644dns_keytag_t 645dst_key_rid(const dst_key_t *key); 646 647dns_rdataclass_t 648dst_key_class(const dst_key_t *key); 649 650isc_boolean_t 651dst_key_isprivate(const dst_key_t *key); 652 653isc_boolean_t 654dst_key_iszonekey(const dst_key_t *key); 655 656isc_boolean_t 657dst_key_isnullkey(const dst_key_t *key); 658 659isc_result_t 660dst_key_buildfilename(const dst_key_t *key, int type, 661 const char *directory, isc_buffer_t *out); 662/*%< 663 * Generates the filename used by dst to store the specified key. 664 * If directory is NULL, the current directory is assumed. 665 * 666 * Requires: 667 *\li "key" is a valid key 668 *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 669 *\li "out" is a valid buffer 670 * 671 * Ensures: 672 *\li the file name will be written to "out", and the used pointer will 673 * be advanced. 674 */ 675 676isc_result_t 677dst_key_sigsize(const dst_key_t *key, unsigned int *n); 678/*%< 679 * Computes the size of a signature generated by the given key. 680 * 681 * Requires: 682 *\li "key" is a valid key. 683 *\li "n" is not NULL 684 * 685 * Returns: 686 *\li #ISC_R_SUCCESS 687 *\li DST_R_UNSUPPORTEDALG 688 * 689 * Ensures: 690 *\li "n" stores the size of a generated signature 691 */ 692 693isc_result_t 694dst_key_secretsize(const dst_key_t *key, unsigned int *n); 695/*%< 696 * Computes the size of a shared secret generated by the given key. 697 * 698 * Requires: 699 *\li "key" is a valid key. 700 *\li "n" is not NULL 701 * 702 * Returns: 703 *\li #ISC_R_SUCCESS 704 *\li DST_R_UNSUPPORTEDALG 705 * 706 * Ensures: 707 *\li "n" stores the size of a generated shared secret 708 */ 709 710isc_uint16_t 711dst_region_computeid(const isc_region_t *source, unsigned int alg); 712isc_uint16_t 713dst_region_computerid(const isc_region_t *source, unsigned int alg); 714/*%< 715 * Computes the (revoked) key id of the key stored in the provided 716 * region with the given algorithm. 717 * 718 * Requires: 719 *\li "source" contains a valid, non-NULL region. 720 * 721 * Returns: 722 *\li the key id 723 */ 724 725isc_uint16_t 726dst_key_getbits(const dst_key_t *key); 727/*%< 728 * Get the number of digest bits required (0 == MAX). 729 * 730 * Requires: 731 * "key" is a valid key. 732 */ 733 734void 735dst_key_setbits(dst_key_t *key, isc_uint16_t bits); 736/*%< 737 * Set the number of digest bits required (0 == MAX). 738 * 739 * Requires: 740 * "key" is a valid key. 741 */ 742 743isc_result_t 744dst_key_setflags(dst_key_t *key, isc_uint32_t flags); 745/* 746 * Set the key flags, and recompute the key ID. 747 * 748 * Requires: 749 * "key" is a valid key. 750 */ 751 752isc_result_t 753dst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep); 754/*%< 755 * Get a member of the numeric metadata array and place it in '*valuep'. 756 * 757 * Requires: 758 * "key" is a valid key. 759 * "type" is no larger than DST_MAX_NUMERIC 760 * "timep" is not null. 761 */ 762 763void 764dst_key_setnum(dst_key_t *key, int type, isc_uint32_t value); 765/*%< 766 * Set a member of the numeric metadata array. 767 * 768 * Requires: 769 * "key" is a valid key. 770 * "type" is no larger than DST_MAX_NUMERIC 771 */ 772 773void 774dst_key_unsetnum(dst_key_t *key, int type); 775/*%< 776 * Flag a member of the numeric metadata array as "not set". 777 * 778 * Requires: 779 * "key" is a valid key. 780 * "type" is no larger than DST_MAX_NUMERIC 781 */ 782 783isc_result_t 784dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 785/*%< 786 * Get a member of the timing metadata array and place it in '*timep'. 787 * 788 * Requires: 789 * "key" is a valid key. 790 * "type" is no larger than DST_MAX_TIMES 791 * "timep" is not null. 792 */ 793 794void 795dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 796/*%< 797 * Set a member of the timing metadata array. 798 * 799 * Requires: 800 * "key" is a valid key. 801 * "type" is no larger than DST_MAX_TIMES 802 */ 803 804void 805dst_key_unsettime(dst_key_t *key, int type); 806/*%< 807 * Flag a member of the timing metadata array as "not set". 808 * 809 * Requires: 810 * "key" is a valid key. 811 * "type" is no larger than DST_MAX_TIMES 812 */ 813 814isc_result_t 815dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 816/*%< 817 * Get the private key format version number. (If the key does not have 818 * a private key associated with it, the version will be 0.0.) The major 819 * version number is placed in '*majorp', and the minor version number in 820 * '*minorp'. 821 * 822 * Requires: 823 * "key" is a valid key. 824 * "majorp" is not NULL. 825 * "minorp" is not NULL. 826 */ 827 828void 829dst_key_setprivateformat(dst_key_t *key, int major, int minor); 830/*%< 831 * Set the private key format version number. 832 * 833 * Requires: 834 * "key" is a valid key. 835 */ 836 837#define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 838 839void 840dst_key_format(const dst_key_t *key, char *cp, unsigned int size); 841/*%< 842 * Write the uniquely identifying information about the key (name, 843 * algorithm, key ID) into a string 'cp' of size 'size'. 844 */ 845 846 847isc_buffer_t * 848dst_key_tkeytoken(const dst_key_t *key); 849/*%< 850 * Return the token from the TKEY request, if any. If this key was 851 * not negotiated via TKEY, return NULL. 852 * 853 * Requires: 854 * "key" is a valid key. 855 */ 856 857 858isc_result_t 859dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 860/*%< 861 * Allocate 'buffer' and dump the key into it in base64 format. The buffer 862 * is not NUL terminated. The length of the buffer is returned in *length. 863 * 864 * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 865 * 866 * Requires: 867 * 'buffer' to be non NULL and *buffer to be NULL. 868 * 'length' to be non NULL and *length to be zero. 869 * 870 * Returns: 871 * ISC_R_SUCCESS 872 * ISC_R_NOMEMORY 873 * ISC_R_NOTIMPLEMENTED 874 * others. 875 */ 876 877isc_result_t 878dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 879 unsigned int protocol, dns_rdataclass_t rdclass, 880 isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 881 882 883ISC_LANG_ENDDECLS 884 885#endif /* DST_DST_H */ 886