dst.h revision 204619
1/* 2 * Copyright (C) 2004-2008, 2010 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: dst.h,v 1.12.50.2 2010/01/15 23:47:34 tbox Exp $ */ 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 27#include <dns/types.h> 28 29#include <dst/gssapi.h> 30 31ISC_LANG_BEGINDECLS 32 33/*** 34 *** Types 35 ***/ 36 37/*% 38 * The dst_key structure is opaque. Applications should use the accessor 39 * functions provided to retrieve key attributes. If an application needs 40 * to set attributes, new accessor functions will be written. 41 */ 42 43typedef struct dst_key dst_key_t; 44typedef struct dst_context dst_context_t; 45 46/* DST algorithm codes */ 47#define DST_ALG_UNKNOWN 0 48#define DST_ALG_RSAMD5 1 49#define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ 50#define DST_ALG_DH 2 51#define DST_ALG_DSA 3 52#define DST_ALG_ECC 4 53#define DST_ALG_RSASHA1 5 54#define DST_ALG_NSEC3DSA 6 55#define DST_ALG_NSEC3RSASHA1 7 56#define DST_ALG_RSASHA256 8 57#define DST_ALG_RSASHA512 10 58#define DST_ALG_HMACMD5 157 59#define DST_ALG_GSSAPI 160 60#define DST_ALG_HMACSHA1 161 /* XXXMPA */ 61#define DST_ALG_HMACSHA224 162 /* XXXMPA */ 62#define DST_ALG_HMACSHA256 163 /* XXXMPA */ 63#define DST_ALG_HMACSHA384 164 /* XXXMPA */ 64#define DST_ALG_HMACSHA512 165 /* XXXMPA */ 65#define DST_ALG_PRIVATE 254 66#define DST_ALG_EXPAND 255 67#define DST_MAX_ALGS 255 68 69/*% A buffer of this size is large enough to hold any key */ 70#define DST_KEY_MAXSIZE 1280 71 72/*% 73 * A buffer of this size is large enough to hold the textual representation 74 * of any key 75 */ 76#define DST_KEY_MAXTEXTSIZE 2048 77 78/*% 'Type' for dst_read_key() */ 79#define DST_TYPE_KEY 0x1000000 /* KEY key */ 80#define DST_TYPE_PRIVATE 0x2000000 81#define DST_TYPE_PUBLIC 0x4000000 82 83/*** 84 *** Functions 85 ***/ 86 87isc_result_t 88dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); 89/*%< 90 * Initializes the DST subsystem. 91 * 92 * Requires: 93 * \li "mctx" is a valid memory context 94 * \li "ectx" is a valid entropy context 95 * 96 * Returns: 97 * \li ISC_R_SUCCESS 98 * \li ISC_R_NOMEMORY 99 * 100 * Ensures: 101 * \li DST is properly initialized. 102 */ 103 104void 105dst_lib_destroy(void); 106/*%< 107 * Releases all resources allocated by DST. 108 */ 109 110isc_boolean_t 111dst_algorithm_supported(unsigned int alg); 112/*%< 113 * Checks that a given algorithm is supported by DST. 114 * 115 * Returns: 116 * \li ISC_TRUE 117 * \li ISC_FALSE 118 */ 119 120isc_result_t 121dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); 122/*%< 123 * Creates a context to be used for a sign or verify operation. 124 * 125 * Requires: 126 * \li "key" is a valid key. 127 * \li "mctx" is a valid memory context. 128 * \li dctxp != NULL && *dctxp == NULL 129 * 130 * Returns: 131 * \li ISC_R_SUCCESS 132 * \li ISC_R_NOMEMORY 133 * 134 * Ensures: 135 * \li *dctxp will contain a usable context. 136 */ 137 138void 139dst_context_destroy(dst_context_t **dctxp); 140/*%< 141 * Destroys all memory associated with a context. 142 * 143 * Requires: 144 * \li *dctxp != NULL && *dctxp == NULL 145 * 146 * Ensures: 147 * \li *dctxp == NULL 148 */ 149 150isc_result_t 151dst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 152/*%< 153 * Incrementally adds data to the context to be used in a sign or verify 154 * operation. 155 * 156 * Requires: 157 * \li "dctx" is a valid context 158 * \li "data" is a valid region 159 * 160 * Returns: 161 * \li ISC_R_SUCCESS 162 * \li DST_R_SIGNFAILURE 163 * \li all other errors indicate failure 164 */ 165 166isc_result_t 167dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 168/*%< 169 * Computes a signature using the data and key stored in the context. 170 * 171 * Requires: 172 * \li "dctx" is a valid context. 173 * \li "sig" is a valid buffer. 174 * 175 * Returns: 176 * \li ISC_R_SUCCESS 177 * \li DST_R_VERIFYFAILURE 178 * \li all other errors indicate failure 179 * 180 * Ensures: 181 * \li "sig" will contain the signature 182 */ 183 184isc_result_t 185dst_context_verify(dst_context_t *dctx, isc_region_t *sig); 186/*%< 187 * Verifies the signature using the data and key stored in the context. 188 * 189 * Requires: 190 * \li "dctx" is a valid context. 191 * \li "sig" is a valid region. 192 * 193 * Returns: 194 * \li ISC_R_SUCCESS 195 * \li all other errors indicate failure 196 * 197 * Ensures: 198 * \li "sig" will contain the signature 199 */ 200 201isc_result_t 202dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 203 isc_buffer_t *secret); 204/*%< 205 * Computes a shared secret from two (Diffie-Hellman) keys. 206 * 207 * Requires: 208 * \li "pub" is a valid key that can be used to derive a shared secret 209 * \li "priv" is a valid private key that can be used to derive a shared secret 210 * \li "secret" is a valid buffer 211 * 212 * Returns: 213 * \li ISC_R_SUCCESS 214 * \li any other result indicates failure 215 * 216 * Ensures: 217 * \li If successful, secret will contain the derived shared secret. 218 */ 219 220isc_result_t 221dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 222 const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 223/*%< 224 * Reads a key from permanent storage. The key can either be a public or 225 * private key, and is specified by name, algorithm, and id. If a private key 226 * is specified, the public key must also be present. If directory is NULL, 227 * the current directory is assumed. 228 * 229 * Requires: 230 * \li "name" is a valid absolute dns name. 231 * \li "id" is a valid key tag identifier. 232 * \li "alg" is a supported key algorithm. 233 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 234 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 235 * \li "mctx" is a valid memory context. 236 * \li "keyp" is not NULL and "*keyp" is NULL. 237 * 238 * Returns: 239 * \li ISC_R_SUCCESS 240 * \li any other result indicates failure 241 * 242 * Ensures: 243 * \li If successful, *keyp will contain a valid key. 244 */ 245 246isc_result_t 247dst_key_fromnamedfile(const char *filename, int type, isc_mem_t *mctx, 248 dst_key_t **keyp); 249/*%< 250 * Reads a key from permanent storage. The key can either be a public or 251 * key, and is specified by filename. If a private key is specified, the 252 * public key must also be present. 253 * 254 * Requires: 255 * \li "filename" is not NULL 256 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 257 * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 258 * \li "mctx" is a valid memory context 259 * \li "keyp" is not NULL and "*keyp" is NULL. 260 * 261 * Returns: 262 * \li ISC_R_SUCCESS 263 * \li any other result indicates failure 264 * 265 * Ensures: 266 * \li If successful, *keyp will contain a valid key. 267 */ 268 269 270isc_result_t 271dst_key_read_public(const char *filename, int type, 272 isc_mem_t *mctx, dst_key_t **keyp); 273/*%< 274 * Reads a public key from permanent storage. The key must be a public key. 275 * 276 * Requires: 277 * \li "filename" is not NULL 278 * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 279 * \li "mctx" is a valid memory context 280 * \li "keyp" is not NULL and "*keyp" is NULL. 281 * 282 * Returns: 283 * \li ISC_R_SUCCESS 284 * \li DST_R_BADKEYTYPE if the key type is not the expected one 285 * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 286 * \li any other result indicates failure 287 * 288 * Ensures: 289 * \li If successful, *keyp will contain a valid key. 290 */ 291 292isc_result_t 293dst_key_tofile(const dst_key_t *key, int type, const char *directory); 294/*%< 295 * Writes a key to permanent storage. The key can either be a public or 296 * private key. Public keys are written in DNS format and private keys 297 * are written as a set of base64 encoded values. If directory is NULL, 298 * the current directory is assumed. 299 * 300 * Requires: 301 * \li "key" is a valid key. 302 * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 303 * 304 * Returns: 305 * \li ISC_R_SUCCESS 306 * \li any other result indicates failure 307 */ 308 309isc_result_t 310dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 311 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 312/*%< 313 * Converts a DNS KEY record into a DST key. 314 * 315 * Requires: 316 * \li "name" is a valid absolute dns name. 317 * \li "source" is a valid buffer. There must be at least 4 bytes available. 318 * \li "mctx" is a valid memory context. 319 * \li "keyp" is not NULL and "*keyp" is NULL. 320 * 321 * Returns: 322 * \li ISC_R_SUCCESS 323 * \li any other result indicates failure 324 * 325 * Ensures: 326 * \li If successful, *keyp will contain a valid key, and the consumed 327 * pointer in data will be advanced. 328 */ 329 330isc_result_t 331dst_key_todns(const dst_key_t *key, isc_buffer_t *target); 332/*%< 333 * Converts a DST key into a DNS KEY record. 334 * 335 * Requires: 336 * \li "key" is a valid key. 337 * \li "target" is a valid buffer. There must be at least 4 bytes unused. 338 * 339 * Returns: 340 * \li ISC_R_SUCCESS 341 * \li any other result indicates failure 342 * 343 * Ensures: 344 * \li If successful, the used pointer in 'target' is advanced by at least 4. 345 */ 346 347isc_result_t 348dst_key_frombuffer(dns_name_t *name, unsigned int alg, 349 unsigned int flags, unsigned int protocol, 350 dns_rdataclass_t rdclass, 351 isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 352/*%< 353 * Converts a buffer containing DNS KEY RDATA into a DST key. 354 * 355 * Requires: 356 *\li "name" is a valid absolute dns name. 357 *\li "alg" is a supported key algorithm. 358 *\li "source" is a valid buffer. 359 *\li "mctx" is a valid memory context. 360 *\li "keyp" is not NULL and "*keyp" is NULL. 361 * 362 * Returns: 363 *\li ISC_R_SUCCESS 364 * \li any other result indicates failure 365 * 366 * Ensures: 367 *\li If successful, *keyp will contain a valid key, and the consumed 368 * pointer in source will be advanced. 369 */ 370 371isc_result_t 372dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 373/*%< 374 * Converts a DST key into DNS KEY RDATA format. 375 * 376 * Requires: 377 *\li "key" is a valid key. 378 *\li "target" is a valid buffer. 379 * 380 * Returns: 381 *\li ISC_R_SUCCESS 382 * \li any other result indicates failure 383 * 384 * Ensures: 385 *\li If successful, the used pointer in 'target' is advanced. 386 */ 387 388isc_result_t 389dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 390/*%< 391 * Converts a public key into a private key, reading the private key 392 * information from the buffer. The buffer should contain the same data 393 * as the .private key file would. 394 * 395 * Requires: 396 *\li "key" is a valid public key. 397 *\li "buffer" is not NULL. 398 * 399 * Returns: 400 *\li ISC_R_SUCCESS 401 * \li any other result indicates failure 402 * 403 * Ensures: 404 *\li If successful, key will contain a valid private key. 405 */ 406 407gss_ctx_id_t 408dst_key_getgssctx(const dst_key_t *key); 409/*%< 410 * Returns the opaque key data. 411 * Be cautions when using this value unless you know what you are doing. 412 * 413 * Requires: 414 *\li "key" is not NULL. 415 * 416 * Returns: 417 *\li gssctx key data, possibly NULL. 418 */ 419 420isc_result_t 421dst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 422 dst_key_t **keyp); 423/*%< 424 * Converts a GSSAPI opaque context id into a DST key. 425 * 426 * Requires: 427 *\li "name" is a valid absolute dns name. 428 *\li "gssctx" is a GSSAPI context id. 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 any other result indicates failure 435 * 436 * Ensures: 437 *\li If successful, *keyp will contain a valid key and be responsible for 438 * the context id. 439 */ 440 441isc_result_t 442dst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 443 unsigned int protocol, dns_rdataclass_t rdclass, 444 const char *engine, const char *label, const char *pin, 445 isc_mem_t *mctx, dst_key_t **keyp); 446 447isc_result_t 448dst_key_generate(dns_name_t *name, unsigned int alg, 449 unsigned int bits, unsigned int param, 450 unsigned int flags, unsigned int protocol, 451 dns_rdataclass_t rdclass, 452 isc_mem_t *mctx, dst_key_t **keyp); 453/*%< 454 * Generate a DST key (or keypair) with the supplied parameters. The 455 * interpretation of the "param" field depends on the algorithm: 456 * \code 457 * RSA: exponent 458 * 0 use exponent 3 459 * !0 use Fermat4 (2^16 + 1) 460 * DH: generator 461 * 0 default - use well known prime if bits == 768 or 1024, 462 * otherwise use 2 as the generator. 463 * !0 use this value as the generator. 464 * DSA: unused 465 * HMACMD5: entropy 466 * 0 default - require good entropy 467 * !0 lack of good entropy is ok 468 *\endcode 469 * 470 * Requires: 471 *\li "name" is a valid absolute dns name. 472 *\li "keyp" is not NULL and "*keyp" is NULL. 473 * 474 * Returns: 475 *\li ISC_R_SUCCESS 476 * \li any other result indicates failure 477 * 478 * Ensures: 479 *\li If successful, *keyp will contain a valid key. 480 */ 481 482isc_boolean_t 483dst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 484/*%< 485 * Compares two DST keys. 486 * 487 * Requires: 488 *\li "key1" is a valid key. 489 *\li "key2" is a valid key. 490 * 491 * Returns: 492 *\li ISC_TRUE 493 * \li ISC_FALSE 494 */ 495 496isc_boolean_t 497dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 498/*%< 499 * Compares the parameters of two DST keys. This is used to determine if 500 * two (Diffie-Hellman) keys can be used to derive a shared secret. 501 * 502 * Requires: 503 *\li "key1" is a valid key. 504 *\li "key2" is a valid key. 505 * 506 * Returns: 507 *\li ISC_TRUE 508 * \li ISC_FALSE 509 */ 510 511void 512dst_key_free(dst_key_t **keyp); 513/*%< 514 * Release all memory associated with the key. 515 * 516 * Requires: 517 *\li "keyp" is not NULL and "*keyp" is a valid key. 518 * 519 * Ensures: 520 *\li All memory associated with "*keyp" will be freed. 521 *\li *keyp == NULL 522 */ 523 524/*%< 525 * Accessor functions to obtain key fields. 526 * 527 * Require: 528 *\li "key" is a valid key. 529 */ 530dns_name_t * 531dst_key_name(const dst_key_t *key); 532 533unsigned int 534dst_key_size(const dst_key_t *key); 535 536unsigned int 537dst_key_proto(const dst_key_t *key); 538 539unsigned int 540dst_key_alg(const dst_key_t *key); 541 542isc_uint32_t 543dst_key_flags(const dst_key_t *key); 544 545dns_keytag_t 546dst_key_id(const dst_key_t *key); 547 548dns_rdataclass_t 549dst_key_class(const dst_key_t *key); 550 551isc_boolean_t 552dst_key_isprivate(const dst_key_t *key); 553 554isc_boolean_t 555dst_key_iszonekey(const dst_key_t *key); 556 557isc_boolean_t 558dst_key_isnullkey(const dst_key_t *key); 559 560isc_result_t 561dst_key_buildfilename(const dst_key_t *key, int type, 562 const char *directory, isc_buffer_t *out); 563/*%< 564 * Generates the filename used by dst to store the specified key. 565 * If directory is NULL, the current directory is assumed. 566 * 567 * Requires: 568 *\li "key" is a valid key 569 *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 570 *\li "out" is a valid buffer 571 * 572 * Ensures: 573 *\li the file name will be written to "out", and the used pointer will 574 * be advanced. 575 */ 576 577isc_result_t 578dst_key_sigsize(const dst_key_t *key, unsigned int *n); 579/*%< 580 * Computes the size of a signature generated by the given key. 581 * 582 * Requires: 583 *\li "key" is a valid key. 584 *\li "n" is not NULL 585 * 586 * Returns: 587 *\li #ISC_R_SUCCESS 588 *\li DST_R_UNSUPPORTEDALG 589 * 590 * Ensures: 591 *\li "n" stores the size of a generated signature 592 */ 593 594isc_result_t 595dst_key_secretsize(const dst_key_t *key, unsigned int *n); 596/*%< 597 * Computes the size of a shared secret generated by the given key. 598 * 599 * Requires: 600 *\li "key" is a valid key. 601 *\li "n" is not NULL 602 * 603 * Returns: 604 *\li #ISC_R_SUCCESS 605 *\li DST_R_UNSUPPORTEDALG 606 * 607 * Ensures: 608 *\li "n" stores the size of a generated shared secret 609 */ 610 611isc_uint16_t 612dst_region_computeid(const isc_region_t *source, unsigned int alg); 613/*%< 614 * Computes the key id of the key stored in the provided region with the 615 * given algorithm. 616 * 617 * Requires: 618 *\li "source" contains a valid, non-NULL region. 619 * 620 * Returns: 621 *\li the key id 622 */ 623 624isc_uint16_t 625dst_key_getbits(const dst_key_t *key); 626/* 627 * Get the number of digest bits required (0 == MAX). 628 * 629 * Requires: 630 * "key" is a valid key. 631 */ 632 633void 634dst_key_setbits(dst_key_t *key, isc_uint16_t bits); 635/* 636 * Set the number of digest bits required (0 == MAX). 637 * 638 * Requires: 639 * "key" is a valid key. 640 */ 641 642ISC_LANG_ENDDECLS 643 644#endif /* DST_DST_H */ 645