contrib/bind-9.2.4rc7/lib/dns/sec/dst/include/dst/dst.h

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