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