dst.h revision 254897
1143731Sdougb/* 2234010Sdougb * Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC") 3143731Sdougb * Copyright (C) 2000-2002 Internet Software Consortium. 4143731Sdougb * 5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6143731Sdougb * purpose with or without fee is hereby granted, provided that the above 7143731Sdougb * copyright notice and this permission notice appear in all copies. 8143731Sdougb * 9143731Sdougb * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10143731Sdougb * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11143731Sdougb * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12143731Sdougb * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13143731Sdougb * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14143731Sdougb * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15143731Sdougb * PERFORMANCE OF THIS SOFTWARE. 16143731Sdougb */ 17143731Sdougb 18254897Serwin/* $Id: dst.h,v 1.34 2011/10/20 21:20:02 marka Exp $ */ 19143731Sdougb 20143731Sdougb#ifndef DST_DST_H 21143731Sdougb#define DST_DST_H 1 22143731Sdougb 23193149Sdougb/*! \file dst/dst.h */ 24170222Sdougb 25143731Sdougb#include <isc/lang.h> 26224092Sdougb#include <isc/stdtime.h> 27143731Sdougb 28143731Sdougb#include <dns/types.h> 29254402Serwin#include <dns/log.h> 30224092Sdougb#include <dns/name.h> 31224092Sdougb#include <dns/secalg.h> 32143731Sdougb 33193149Sdougb#include <dst/gssapi.h> 34193149Sdougb 35143731SdougbISC_LANG_BEGINDECLS 36143731Sdougb 37143731Sdougb/*** 38143731Sdougb *** Types 39143731Sdougb ***/ 40143731Sdougb 41170222Sdougb/*% 42143731Sdougb * The dst_key structure is opaque. Applications should use the accessor 43143731Sdougb * functions provided to retrieve key attributes. If an application needs 44143731Sdougb * to set attributes, new accessor functions will be written. 45143731Sdougb */ 46143731Sdougb 47143731Sdougbtypedef struct dst_key dst_key_t; 48143731Sdougbtypedef struct dst_context dst_context_t; 49143731Sdougb 50143731Sdougb/* DST algorithm codes */ 51143731Sdougb#define DST_ALG_UNKNOWN 0 52143731Sdougb#define DST_ALG_RSAMD5 1 53170222Sdougb#define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ 54143731Sdougb#define DST_ALG_DH 2 55143731Sdougb#define DST_ALG_DSA 3 56143731Sdougb#define DST_ALG_ECC 4 57143731Sdougb#define DST_ALG_RSASHA1 5 58193149Sdougb#define DST_ALG_NSEC3DSA 6 59193149Sdougb#define DST_ALG_NSEC3RSASHA1 7 60204619Sdougb#define DST_ALG_RSASHA256 8 61204619Sdougb#define DST_ALG_RSASHA512 10 62224092Sdougb#define DST_ALG_ECCGOST 12 63245163Serwin#define DST_ALG_ECDSA256 13 64245163Serwin#define DST_ALG_ECDSA384 14 65143731Sdougb#define DST_ALG_HMACMD5 157 66143731Sdougb#define DST_ALG_GSSAPI 160 67170222Sdougb#define DST_ALG_HMACSHA1 161 /* XXXMPA */ 68170222Sdougb#define DST_ALG_HMACSHA224 162 /* XXXMPA */ 69170222Sdougb#define DST_ALG_HMACSHA256 163 /* XXXMPA */ 70170222Sdougb#define DST_ALG_HMACSHA384 164 /* XXXMPA */ 71170222Sdougb#define DST_ALG_HMACSHA512 165 /* XXXMPA */ 72143731Sdougb#define DST_ALG_PRIVATE 254 73143731Sdougb#define DST_ALG_EXPAND 255 74143731Sdougb#define DST_MAX_ALGS 255 75143731Sdougb 76170222Sdougb/*% A buffer of this size is large enough to hold any key */ 77143731Sdougb#define DST_KEY_MAXSIZE 1280 78143731Sdougb 79170222Sdougb/*% 80143731Sdougb * A buffer of this size is large enough to hold the textual representation 81143731Sdougb * of any key 82143731Sdougb */ 83143731Sdougb#define DST_KEY_MAXTEXTSIZE 2048 84143731Sdougb 85170222Sdougb/*% 'Type' for dst_read_key() */ 86143731Sdougb#define DST_TYPE_KEY 0x1000000 /* KEY key */ 87143731Sdougb#define DST_TYPE_PRIVATE 0x2000000 88143731Sdougb#define DST_TYPE_PUBLIC 0x4000000 89143731Sdougb 90224092Sdougb/* Key timing metadata definitions */ 91224092Sdougb#define DST_TIME_CREATED 0 92224092Sdougb#define DST_TIME_PUBLISH 1 93224092Sdougb#define DST_TIME_ACTIVATE 2 94224092Sdougb#define DST_TIME_REVOKE 3 95224092Sdougb#define DST_TIME_INACTIVE 4 96224092Sdougb#define DST_TIME_DELETE 5 97224092Sdougb#define DST_TIME_DSPUBLISH 6 98224092Sdougb#define DST_MAX_TIMES 6 99224092Sdougb 100224092Sdougb/* Numeric metadata definitions */ 101224092Sdougb#define DST_NUM_PREDECESSOR 0 102224092Sdougb#define DST_NUM_SUCCESSOR 1 103224092Sdougb#define DST_NUM_MAXTTL 2 104224092Sdougb#define DST_NUM_ROLLPERIOD 3 105224092Sdougb#define DST_MAX_NUMERIC 3 106224092Sdougb 107224092Sdougb/* 108224092Sdougb * Current format version number of the private key parser. 109224092Sdougb * 110224092Sdougb * When parsing a key file with the same major number but a higher minor 111224092Sdougb * number, the key parser will ignore any fields it does not recognize. 112224092Sdougb * Thus, DST_MINOR_VERSION should be incremented whenever new 113224092Sdougb * fields are added to the private key file (such as new metadata). 114224092Sdougb * 115224092Sdougb * When rewriting these keys, those fields will be dropped, and the 116224092Sdougb * format version set back to the current one.. 117224092Sdougb * 118224092Sdougb * When a key is seen with a higher major number, the key parser will 119224092Sdougb * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented 120224092Sdougb * and DST_MINOR_VERSION set to zero whenever there is a format change 121224092Sdougb * which is not backward compatible to previous versions of the dst_key 122224092Sdougb * parser, such as change in the syntax of an existing field, the removal 123224092Sdougb * of a currently mandatory field, or a new field added which would 124224092Sdougb * alter the functioning of the key if it were absent. 125224092Sdougb */ 126224092Sdougb#define DST_MAJOR_VERSION 1 127224092Sdougb#define DST_MINOR_VERSION 3 128224092Sdougb 129143731Sdougb/*** 130143731Sdougb *** Functions 131143731Sdougb ***/ 132143731Sdougb 133143731Sdougbisc_result_t 134143731Sdougbdst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); 135224092Sdougb 136224092Sdougbisc_result_t 137224092Sdougbdst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx, 138224092Sdougb const char *engine, unsigned int eflags); 139170222Sdougb/*%< 140143731Sdougb * Initializes the DST subsystem. 141143731Sdougb * 142143731Sdougb * Requires: 143170222Sdougb * \li "mctx" is a valid memory context 144170222Sdougb * \li "ectx" is a valid entropy context 145143731Sdougb * 146143731Sdougb * Returns: 147170222Sdougb * \li ISC_R_SUCCESS 148170222Sdougb * \li ISC_R_NOMEMORY 149224092Sdougb * \li DST_R_NOENGINE 150143731Sdougb * 151143731Sdougb * Ensures: 152170222Sdougb * \li DST is properly initialized. 153143731Sdougb */ 154143731Sdougb 155143731Sdougbvoid 156143731Sdougbdst_lib_destroy(void); 157170222Sdougb/*%< 158143731Sdougb * Releases all resources allocated by DST. 159143731Sdougb */ 160143731Sdougb 161143731Sdougbisc_boolean_t 162143731Sdougbdst_algorithm_supported(unsigned int alg); 163170222Sdougb/*%< 164143731Sdougb * Checks that a given algorithm is supported by DST. 165143731Sdougb * 166143731Sdougb * Returns: 167170222Sdougb * \li ISC_TRUE 168170222Sdougb * \li ISC_FALSE 169143731Sdougb */ 170143731Sdougb 171143731Sdougbisc_result_t 172143731Sdougbdst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); 173254402Serwin 174254402Serwinisc_result_t 175254402Serwindst_context_create2(dst_key_t *key, isc_mem_t *mctx, 176254402Serwin isc_logcategory_t *category, dst_context_t **dctxp); 177254402Serwin 178170222Sdougb/*%< 179143731Sdougb * Creates a context to be used for a sign or verify operation. 180143731Sdougb * 181143731Sdougb * Requires: 182170222Sdougb * \li "key" is a valid key. 183170222Sdougb * \li "mctx" is a valid memory context. 184170222Sdougb * \li dctxp != NULL && *dctxp == NULL 185143731Sdougb * 186143731Sdougb * Returns: 187170222Sdougb * \li ISC_R_SUCCESS 188170222Sdougb * \li ISC_R_NOMEMORY 189143731Sdougb * 190143731Sdougb * Ensures: 191170222Sdougb * \li *dctxp will contain a usable context. 192143731Sdougb */ 193143731Sdougb 194143731Sdougbvoid 195143731Sdougbdst_context_destroy(dst_context_t **dctxp); 196170222Sdougb/*%< 197143731Sdougb * Destroys all memory associated with a context. 198143731Sdougb * 199143731Sdougb * Requires: 200170222Sdougb * \li *dctxp != NULL && *dctxp == NULL 201143731Sdougb * 202143731Sdougb * Ensures: 203170222Sdougb * \li *dctxp == NULL 204143731Sdougb */ 205143731Sdougb 206143731Sdougbisc_result_t 207143731Sdougbdst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 208170222Sdougb/*%< 209143731Sdougb * Incrementally adds data to the context to be used in a sign or verify 210143731Sdougb * operation. 211143731Sdougb * 212143731Sdougb * Requires: 213170222Sdougb * \li "dctx" is a valid context 214170222Sdougb * \li "data" is a valid region 215143731Sdougb * 216143731Sdougb * Returns: 217170222Sdougb * \li ISC_R_SUCCESS 218170222Sdougb * \li DST_R_SIGNFAILURE 219170222Sdougb * \li all other errors indicate failure 220143731Sdougb */ 221143731Sdougb 222143731Sdougbisc_result_t 223143731Sdougbdst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 224170222Sdougb/*%< 225143731Sdougb * Computes a signature using the data and key stored in the context. 226143731Sdougb * 227143731Sdougb * Requires: 228170222Sdougb * \li "dctx" is a valid context. 229170222Sdougb * \li "sig" is a valid buffer. 230143731Sdougb * 231143731Sdougb * Returns: 232170222Sdougb * \li ISC_R_SUCCESS 233170222Sdougb * \li DST_R_VERIFYFAILURE 234170222Sdougb * \li all other errors indicate failure 235143731Sdougb * 236143731Sdougb * Ensures: 237170222Sdougb * \li "sig" will contain the signature 238143731Sdougb */ 239143731Sdougb 240143731Sdougbisc_result_t 241143731Sdougbdst_context_verify(dst_context_t *dctx, isc_region_t *sig); 242254897Serwin 243254897Serwinisc_result_t 244254897Serwindst_context_verify2(dst_context_t *dctx, unsigned int maxbits, 245254897Serwin isc_region_t *sig); 246170222Sdougb/*%< 247143731Sdougb * Verifies the signature using the data and key stored in the context. 248143731Sdougb * 249254897Serwin * 'maxbits' specifies the maximum number of bits permitted in the RSA 250254897Serwin * exponent. 251254897Serwin * 252143731Sdougb * Requires: 253170222Sdougb * \li "dctx" is a valid context. 254170222Sdougb * \li "sig" is a valid region. 255143731Sdougb * 256143731Sdougb * Returns: 257170222Sdougb * \li ISC_R_SUCCESS 258170222Sdougb * \li all other errors indicate failure 259143731Sdougb * 260143731Sdougb * Ensures: 261170222Sdougb * \li "sig" will contain the signature 262143731Sdougb */ 263143731Sdougb 264143731Sdougbisc_result_t 265143731Sdougbdst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 266143731Sdougb isc_buffer_t *secret); 267170222Sdougb/*%< 268143731Sdougb * Computes a shared secret from two (Diffie-Hellman) keys. 269143731Sdougb * 270143731Sdougb * Requires: 271170222Sdougb * \li "pub" is a valid key that can be used to derive a shared secret 272170222Sdougb * \li "priv" is a valid private key that can be used to derive a shared secret 273170222Sdougb * \li "secret" is a valid buffer 274143731Sdougb * 275143731Sdougb * Returns: 276170222Sdougb * \li ISC_R_SUCCESS 277170222Sdougb * \li any other result indicates failure 278143731Sdougb * 279143731Sdougb * Ensures: 280170222Sdougb * \li If successful, secret will contain the derived shared secret. 281143731Sdougb */ 282143731Sdougb 283143731Sdougbisc_result_t 284143731Sdougbdst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 285143731Sdougb const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 286170222Sdougb/*%< 287143731Sdougb * Reads a key from permanent storage. The key can either be a public or 288143731Sdougb * private key, and is specified by name, algorithm, and id. If a private key 289143731Sdougb * is specified, the public key must also be present. If directory is NULL, 290143731Sdougb * the current directory is assumed. 291143731Sdougb * 292143731Sdougb * Requires: 293170222Sdougb * \li "name" is a valid absolute dns name. 294170222Sdougb * \li "id" is a valid key tag identifier. 295170222Sdougb * \li "alg" is a supported key algorithm. 296170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 297143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 298170222Sdougb * \li "mctx" is a valid memory context. 299170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 300143731Sdougb * 301143731Sdougb * Returns: 302170222Sdougb * \li ISC_R_SUCCESS 303170222Sdougb * \li any other result indicates failure 304143731Sdougb * 305143731Sdougb * Ensures: 306170222Sdougb * \li If successful, *keyp will contain a valid key. 307143731Sdougb */ 308143731Sdougb 309143731Sdougbisc_result_t 310224092Sdougbdst_key_fromnamedfile(const char *filename, const char *dirname, 311224092Sdougb int type, isc_mem_t *mctx, dst_key_t **keyp); 312170222Sdougb/*%< 313143731Sdougb * Reads a key from permanent storage. The key can either be a public or 314143731Sdougb * key, and is specified by filename. If a private key is specified, the 315143731Sdougb * public key must also be present. 316143731Sdougb * 317224092Sdougb * If 'dirname' is not NULL, and 'filename' is a relative path, 318224092Sdougb * then the file is looked up relative to the given directory. 319224092Sdougb * If 'filename' is an absolute path, 'dirname' is ignored. 320224092Sdougb * 321143731Sdougb * Requires: 322170222Sdougb * \li "filename" is not NULL 323170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 324143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 325170222Sdougb * \li "mctx" is a valid memory context 326170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 327143731Sdougb * 328143731Sdougb * Returns: 329170222Sdougb * \li ISC_R_SUCCESS 330170222Sdougb * \li any other result indicates failure 331143731Sdougb * 332143731Sdougb * Ensures: 333170222Sdougb * \li If successful, *keyp will contain a valid key. 334143731Sdougb */ 335143731Sdougb 336170222Sdougb 337143731Sdougbisc_result_t 338170222Sdougbdst_key_read_public(const char *filename, int type, 339170222Sdougb isc_mem_t *mctx, dst_key_t **keyp); 340170222Sdougb/*%< 341170222Sdougb * Reads a public key from permanent storage. The key must be a public key. 342170222Sdougb * 343170222Sdougb * Requires: 344170222Sdougb * \li "filename" is not NULL 345170222Sdougb * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 346170222Sdougb * \li "mctx" is a valid memory context 347170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 348170222Sdougb * 349170222Sdougb * Returns: 350170222Sdougb * \li ISC_R_SUCCESS 351170222Sdougb * \li DST_R_BADKEYTYPE if the key type is not the expected one 352170222Sdougb * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 353170222Sdougb * \li any other result indicates failure 354170222Sdougb * 355170222Sdougb * Ensures: 356170222Sdougb * \li If successful, *keyp will contain a valid key. 357170222Sdougb */ 358170222Sdougb 359170222Sdougbisc_result_t 360143731Sdougbdst_key_tofile(const dst_key_t *key, int type, const char *directory); 361170222Sdougb/*%< 362143731Sdougb * Writes a key to permanent storage. The key can either be a public or 363143731Sdougb * private key. Public keys are written in DNS format and private keys 364143731Sdougb * are written as a set of base64 encoded values. If directory is NULL, 365143731Sdougb * the current directory is assumed. 366143731Sdougb * 367143731Sdougb * Requires: 368170222Sdougb * \li "key" is a valid key. 369170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 370143731Sdougb * 371143731Sdougb * Returns: 372170222Sdougb * \li ISC_R_SUCCESS 373170222Sdougb * \li any other result indicates failure 374143731Sdougb */ 375143731Sdougb 376143731Sdougbisc_result_t 377143731Sdougbdst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 378143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 379170222Sdougb/*%< 380143731Sdougb * Converts a DNS KEY record into a DST key. 381143731Sdougb * 382143731Sdougb * Requires: 383170222Sdougb * \li "name" is a valid absolute dns name. 384170222Sdougb * \li "source" is a valid buffer. There must be at least 4 bytes available. 385170222Sdougb * \li "mctx" is a valid memory context. 386170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 387143731Sdougb * 388143731Sdougb * Returns: 389170222Sdougb * \li ISC_R_SUCCESS 390170222Sdougb * \li any other result indicates failure 391143731Sdougb * 392143731Sdougb * Ensures: 393170222Sdougb * \li If successful, *keyp will contain a valid key, and the consumed 394143731Sdougb * pointer in data will be advanced. 395143731Sdougb */ 396143731Sdougb 397143731Sdougbisc_result_t 398143731Sdougbdst_key_todns(const dst_key_t *key, isc_buffer_t *target); 399170222Sdougb/*%< 400143731Sdougb * Converts a DST key into a DNS KEY record. 401143731Sdougb * 402143731Sdougb * Requires: 403170222Sdougb * \li "key" is a valid key. 404170222Sdougb * \li "target" is a valid buffer. There must be at least 4 bytes unused. 405143731Sdougb * 406143731Sdougb * Returns: 407170222Sdougb * \li ISC_R_SUCCESS 408170222Sdougb * \li any other result indicates failure 409143731Sdougb * 410143731Sdougb * Ensures: 411170222Sdougb * \li If successful, the used pointer in 'target' is advanced by at least 4. 412143731Sdougb */ 413143731Sdougb 414143731Sdougbisc_result_t 415143731Sdougbdst_key_frombuffer(dns_name_t *name, unsigned int alg, 416143731Sdougb unsigned int flags, unsigned int protocol, 417143731Sdougb dns_rdataclass_t rdclass, 418143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 419170222Sdougb/*%< 420143731Sdougb * Converts a buffer containing DNS KEY RDATA into a DST key. 421143731Sdougb * 422143731Sdougb * Requires: 423170222Sdougb *\li "name" is a valid absolute dns name. 424170222Sdougb *\li "alg" is a supported key algorithm. 425170222Sdougb *\li "source" is a valid buffer. 426170222Sdougb *\li "mctx" is a valid memory context. 427170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 428143731Sdougb * 429143731Sdougb * Returns: 430170222Sdougb *\li ISC_R_SUCCESS 431170222Sdougb * \li any other result indicates failure 432143731Sdougb * 433143731Sdougb * Ensures: 434170222Sdougb *\li If successful, *keyp will contain a valid key, and the consumed 435143731Sdougb * pointer in source will be advanced. 436143731Sdougb */ 437143731Sdougb 438143731Sdougbisc_result_t 439143731Sdougbdst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 440170222Sdougb/*%< 441143731Sdougb * Converts a DST key into DNS KEY RDATA format. 442143731Sdougb * 443143731Sdougb * Requires: 444170222Sdougb *\li "key" is a valid key. 445170222Sdougb *\li "target" is a valid buffer. 446143731Sdougb * 447143731Sdougb * Returns: 448170222Sdougb *\li ISC_R_SUCCESS 449170222Sdougb * \li any other result indicates failure 450143731Sdougb * 451143731Sdougb * Ensures: 452170222Sdougb *\li If successful, the used pointer in 'target' is advanced. 453143731Sdougb */ 454143731Sdougb 455143731Sdougbisc_result_t 456143731Sdougbdst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 457170222Sdougb/*%< 458143731Sdougb * Converts a public key into a private key, reading the private key 459143731Sdougb * information from the buffer. The buffer should contain the same data 460143731Sdougb * as the .private key file would. 461143731Sdougb * 462143731Sdougb * Requires: 463170222Sdougb *\li "key" is a valid public key. 464170222Sdougb *\li "buffer" is not NULL. 465143731Sdougb * 466143731Sdougb * Returns: 467170222Sdougb *\li ISC_R_SUCCESS 468170222Sdougb * \li any other result indicates failure 469143731Sdougb * 470143731Sdougb * Ensures: 471170222Sdougb *\li If successful, key will contain a valid private key. 472143731Sdougb */ 473143731Sdougb 474193149Sdougbgss_ctx_id_t 475193149Sdougbdst_key_getgssctx(const dst_key_t *key); 476193149Sdougb/*%< 477193149Sdougb * Returns the opaque key data. 478193149Sdougb * Be cautions when using this value unless you know what you are doing. 479193149Sdougb * 480193149Sdougb * Requires: 481193149Sdougb *\li "key" is not NULL. 482193149Sdougb * 483193149Sdougb * Returns: 484193149Sdougb *\li gssctx key data, possibly NULL. 485193149Sdougb */ 486143731Sdougb 487143731Sdougbisc_result_t 488193149Sdougbdst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 489224092Sdougb dst_key_t **keyp, isc_region_t *intoken); 490170222Sdougb/*%< 491143731Sdougb * Converts a GSSAPI opaque context id into a DST key. 492143731Sdougb * 493143731Sdougb * Requires: 494170222Sdougb *\li "name" is a valid absolute dns name. 495193149Sdougb *\li "gssctx" is a GSSAPI context id. 496170222Sdougb *\li "mctx" is a valid memory context. 497170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 498143731Sdougb * 499143731Sdougb * Returns: 500170222Sdougb *\li ISC_R_SUCCESS 501170222Sdougb * \li any other result indicates failure 502143731Sdougb * 503143731Sdougb * Ensures: 504170222Sdougb *\li If successful, *keyp will contain a valid key and be responsible for 505143731Sdougb * the context id. 506143731Sdougb */ 507143731Sdougb 508254897Serwin#ifdef DST_KEY_INTERNAL 509143731Sdougbisc_result_t 510254897Serwindst_key_buildinternal(dns_name_t *name, unsigned int alg, 511254897Serwin unsigned int bits, unsigned int flags, 512254897Serwin unsigned int protocol, dns_rdataclass_t rdclass, 513254897Serwin void *data, isc_mem_t *mctx, dst_key_t **keyp); 514254897Serwin#endif 515254897Serwin 516254897Serwinisc_result_t 517193149Sdougbdst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 518193149Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 519193149Sdougb const char *engine, const char *label, const char *pin, 520193149Sdougb isc_mem_t *mctx, dst_key_t **keyp); 521193149Sdougb 522193149Sdougbisc_result_t 523143731Sdougbdst_key_generate(dns_name_t *name, unsigned int alg, 524143731Sdougb unsigned int bits, unsigned int param, 525143731Sdougb unsigned int flags, unsigned int protocol, 526143731Sdougb dns_rdataclass_t rdclass, 527143731Sdougb isc_mem_t *mctx, dst_key_t **keyp); 528224092Sdougb 529224092Sdougbisc_result_t 530224092Sdougbdst_key_generate2(dns_name_t *name, unsigned int alg, 531224092Sdougb unsigned int bits, unsigned int param, 532224092Sdougb unsigned int flags, unsigned int protocol, 533224092Sdougb dns_rdataclass_t rdclass, 534224092Sdougb isc_mem_t *mctx, dst_key_t **keyp, 535224092Sdougb void (*callback)(int)); 536254897Serwin 537170222Sdougb/*%< 538143731Sdougb * Generate a DST key (or keypair) with the supplied parameters. The 539143731Sdougb * interpretation of the "param" field depends on the algorithm: 540170222Sdougb * \code 541143731Sdougb * RSA: exponent 542143731Sdougb * 0 use exponent 3 543143731Sdougb * !0 use Fermat4 (2^16 + 1) 544143731Sdougb * DH: generator 545143731Sdougb * 0 default - use well known prime if bits == 768 or 1024, 546143731Sdougb * otherwise use 2 as the generator. 547143731Sdougb * !0 use this value as the generator. 548143731Sdougb * DSA: unused 549143731Sdougb * HMACMD5: entropy 550143731Sdougb * 0 default - require good entropy 551143731Sdougb * !0 lack of good entropy is ok 552170222Sdougb *\endcode 553143731Sdougb * 554143731Sdougb * Requires: 555170222Sdougb *\li "name" is a valid absolute dns name. 556170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 557143731Sdougb * 558143731Sdougb * Returns: 559170222Sdougb *\li ISC_R_SUCCESS 560170222Sdougb * \li any other result indicates failure 561143731Sdougb * 562143731Sdougb * Ensures: 563170222Sdougb *\li If successful, *keyp will contain a valid key. 564143731Sdougb */ 565143731Sdougb 566143731Sdougbisc_boolean_t 567143731Sdougbdst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 568170222Sdougb/*%< 569224092Sdougb * Compares two DST keys. Returns true if they match, false otherwise. 570143731Sdougb * 571224092Sdougb * Keys ARE NOT considered to match if one of them is the revoked version 572224092Sdougb * of the other. 573224092Sdougb * 574143731Sdougb * Requires: 575170222Sdougb *\li "key1" is a valid key. 576170222Sdougb *\li "key2" is a valid key. 577143731Sdougb * 578143731Sdougb * Returns: 579170222Sdougb *\li ISC_TRUE 580170222Sdougb * \li ISC_FALSE 581143731Sdougb */ 582143731Sdougb 583143731Sdougbisc_boolean_t 584224092Sdougbdst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 585224092Sdougb isc_boolean_t match_revoked_key); 586224092Sdougb/*%< 587224092Sdougb * Compares only the public portions of two DST keys. Returns true 588224092Sdougb * if they match, false otherwise. This allows us, for example, to 589224092Sdougb * determine whether a public key found in a zone matches up with a 590224092Sdougb * key pair found on disk. 591224092Sdougb * 592224092Sdougb * If match_revoked_key is TRUE, then keys ARE considered to match if one 593224092Sdougb * of them is the revoked version of the other. Otherwise, they are not. 594224092Sdougb * 595224092Sdougb * Requires: 596224092Sdougb *\li "key1" is a valid key. 597224092Sdougb *\li "key2" is a valid key. 598224092Sdougb * 599224092Sdougb * Returns: 600224092Sdougb *\li ISC_TRUE 601224092Sdougb * \li ISC_FALSE 602224092Sdougb */ 603224092Sdougb 604224092Sdougbisc_boolean_t 605143731Sdougbdst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 606170222Sdougb/*%< 607143731Sdougb * Compares the parameters of two DST keys. This is used to determine if 608143731Sdougb * two (Diffie-Hellman) keys can be used to derive a shared secret. 609143731Sdougb * 610143731Sdougb * Requires: 611170222Sdougb *\li "key1" is a valid key. 612170222Sdougb *\li "key2" is a valid key. 613143731Sdougb * 614143731Sdougb * Returns: 615170222Sdougb *\li ISC_TRUE 616170222Sdougb * \li ISC_FALSE 617143731Sdougb */ 618143731Sdougb 619143731Sdougbvoid 620218384Sdougbdst_key_attach(dst_key_t *source, dst_key_t **target); 621218384Sdougb/* 622218384Sdougb * Attach to a existing key increasing the reference count. 623218384Sdougb * 624218384Sdougb * Requires: 625218384Sdougb *\li 'source' to be a valid key. 626218384Sdougb *\li 'target' to be non-NULL and '*target' to be NULL. 627218384Sdougb */ 628218384Sdougb 629218384Sdougbvoid 630143731Sdougbdst_key_free(dst_key_t **keyp); 631170222Sdougb/*%< 632224092Sdougb * Decrement the key's reference counter and, when it reaches zero, 633224092Sdougb * release all memory associated with the key. 634143731Sdougb * 635143731Sdougb * Requires: 636170222Sdougb *\li "keyp" is not NULL and "*keyp" is a valid key. 637224092Sdougb *\li reference counter greater than zero. 638143731Sdougb * 639143731Sdougb * Ensures: 640170222Sdougb *\li All memory associated with "*keyp" will be freed. 641170222Sdougb *\li *keyp == NULL 642143731Sdougb */ 643143731Sdougb 644170222Sdougb/*%< 645143731Sdougb * Accessor functions to obtain key fields. 646143731Sdougb * 647143731Sdougb * Require: 648170222Sdougb *\li "key" is a valid key. 649143731Sdougb */ 650143731Sdougbdns_name_t * 651143731Sdougbdst_key_name(const dst_key_t *key); 652143731Sdougb 653143731Sdougbunsigned int 654143731Sdougbdst_key_size(const dst_key_t *key); 655143731Sdougb 656143731Sdougbunsigned int 657143731Sdougbdst_key_proto(const dst_key_t *key); 658143731Sdougb 659143731Sdougbunsigned int 660143731Sdougbdst_key_alg(const dst_key_t *key); 661143731Sdougb 662143731Sdougbisc_uint32_t 663143731Sdougbdst_key_flags(const dst_key_t *key); 664143731Sdougb 665143731Sdougbdns_keytag_t 666143731Sdougbdst_key_id(const dst_key_t *key); 667143731Sdougb 668234010Sdougbdns_keytag_t 669234010Sdougbdst_key_rid(const dst_key_t *key); 670234010Sdougb 671143731Sdougbdns_rdataclass_t 672143731Sdougbdst_key_class(const dst_key_t *key); 673143731Sdougb 674143731Sdougbisc_boolean_t 675143731Sdougbdst_key_isprivate(const dst_key_t *key); 676143731Sdougb 677143731Sdougbisc_boolean_t 678143731Sdougbdst_key_iszonekey(const dst_key_t *key); 679143731Sdougb 680143731Sdougbisc_boolean_t 681143731Sdougbdst_key_isnullkey(const dst_key_t *key); 682143731Sdougb 683143731Sdougbisc_result_t 684143731Sdougbdst_key_buildfilename(const dst_key_t *key, int type, 685143731Sdougb const char *directory, isc_buffer_t *out); 686170222Sdougb/*%< 687143731Sdougb * Generates the filename used by dst to store the specified key. 688143731Sdougb * If directory is NULL, the current directory is assumed. 689143731Sdougb * 690143731Sdougb * Requires: 691170222Sdougb *\li "key" is a valid key 692170222Sdougb *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 693170222Sdougb *\li "out" is a valid buffer 694143731Sdougb * 695143731Sdougb * Ensures: 696170222Sdougb *\li the file name will be written to "out", and the used pointer will 697143731Sdougb * be advanced. 698143731Sdougb */ 699143731Sdougb 700143731Sdougbisc_result_t 701143731Sdougbdst_key_sigsize(const dst_key_t *key, unsigned int *n); 702170222Sdougb/*%< 703143731Sdougb * Computes the size of a signature generated by the given key. 704143731Sdougb * 705143731Sdougb * Requires: 706170222Sdougb *\li "key" is a valid key. 707170222Sdougb *\li "n" is not NULL 708143731Sdougb * 709143731Sdougb * Returns: 710170222Sdougb *\li #ISC_R_SUCCESS 711170222Sdougb *\li DST_R_UNSUPPORTEDALG 712143731Sdougb * 713143731Sdougb * Ensures: 714170222Sdougb *\li "n" stores the size of a generated signature 715143731Sdougb */ 716143731Sdougb 717143731Sdougbisc_result_t 718143731Sdougbdst_key_secretsize(const dst_key_t *key, unsigned int *n); 719170222Sdougb/*%< 720143731Sdougb * Computes the size of a shared secret generated by the given key. 721143731Sdougb * 722143731Sdougb * Requires: 723170222Sdougb *\li "key" is a valid key. 724170222Sdougb *\li "n" is not NULL 725143731Sdougb * 726143731Sdougb * Returns: 727170222Sdougb *\li #ISC_R_SUCCESS 728170222Sdougb *\li DST_R_UNSUPPORTEDALG 729143731Sdougb * 730143731Sdougb * Ensures: 731170222Sdougb *\li "n" stores the size of a generated shared secret 732143731Sdougb */ 733143731Sdougb 734143731Sdougbisc_uint16_t 735143731Sdougbdst_region_computeid(const isc_region_t *source, unsigned int alg); 736234010Sdougbisc_uint16_t 737234010Sdougbdst_region_computerid(const isc_region_t *source, unsigned int alg); 738170222Sdougb/*%< 739234010Sdougb * Computes the (revoked) key id of the key stored in the provided 740234010Sdougb * region with the given algorithm. 741143731Sdougb * 742143731Sdougb * Requires: 743170222Sdougb *\li "source" contains a valid, non-NULL region. 744143731Sdougb * 745143731Sdougb * Returns: 746170222Sdougb *\li the key id 747143731Sdougb */ 748143731Sdougb 749170222Sdougbisc_uint16_t 750170222Sdougbdst_key_getbits(const dst_key_t *key); 751224092Sdougb/*%< 752170222Sdougb * Get the number of digest bits required (0 == MAX). 753170222Sdougb * 754170222Sdougb * Requires: 755170222Sdougb * "key" is a valid key. 756170222Sdougb */ 757170222Sdougb 758170222Sdougbvoid 759170222Sdougbdst_key_setbits(dst_key_t *key, isc_uint16_t bits); 760224092Sdougb/*%< 761170222Sdougb * Set the number of digest bits required (0 == MAX). 762170222Sdougb * 763170222Sdougb * Requires: 764170222Sdougb * "key" is a valid key. 765170222Sdougb */ 766170222Sdougb 767254897Serwinvoid 768254897Serwindst_key_setttl(dst_key_t *key, dns_ttl_t ttl); 769254897Serwin/*%< 770254897Serwin * Set the default TTL to use when converting the key 771254897Serwin * to a KEY or DNSKEY RR. 772254897Serwin * 773254897Serwin * Requires: 774254897Serwin * "key" is a valid key. 775254897Serwin */ 776254897Serwin 777254897Serwindns_ttl_t 778254897Serwindst_key_getttl(const dst_key_t *key); 779254897Serwin/*%< 780254897Serwin * Get the default TTL to use when converting the key 781254897Serwin * to a KEY or DNSKEY RR. 782254897Serwin * 783254897Serwin * Requires: 784254897Serwin * "key" is a valid key. 785254897Serwin */ 786254897Serwin 787224092Sdougbisc_result_t 788224092Sdougbdst_key_setflags(dst_key_t *key, isc_uint32_t flags); 789224092Sdougb/* 790224092Sdougb * Set the key flags, and recompute the key ID. 791224092Sdougb * 792224092Sdougb * Requires: 793224092Sdougb * "key" is a valid key. 794224092Sdougb */ 795224092Sdougb 796224092Sdougbisc_result_t 797224092Sdougbdst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep); 798224092Sdougb/*%< 799224092Sdougb * Get a member of the numeric metadata array and place it in '*valuep'. 800224092Sdougb * 801224092Sdougb * Requires: 802224092Sdougb * "key" is a valid key. 803224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 804224092Sdougb * "timep" is not null. 805224092Sdougb */ 806224092Sdougb 807224092Sdougbvoid 808224092Sdougbdst_key_setnum(dst_key_t *key, int type, isc_uint32_t value); 809224092Sdougb/*%< 810224092Sdougb * Set a member of the numeric metadata array. 811224092Sdougb * 812224092Sdougb * Requires: 813224092Sdougb * "key" is a valid key. 814224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 815224092Sdougb */ 816224092Sdougb 817224092Sdougbvoid 818224092Sdougbdst_key_unsetnum(dst_key_t *key, int type); 819224092Sdougb/*%< 820224092Sdougb * Flag a member of the numeric metadata array as "not set". 821224092Sdougb * 822224092Sdougb * Requires: 823224092Sdougb * "key" is a valid key. 824224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 825224092Sdougb */ 826224092Sdougb 827224092Sdougbisc_result_t 828224092Sdougbdst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 829224092Sdougb/*%< 830224092Sdougb * Get a member of the timing metadata array and place it in '*timep'. 831224092Sdougb * 832224092Sdougb * Requires: 833224092Sdougb * "key" is a valid key. 834224092Sdougb * "type" is no larger than DST_MAX_TIMES 835224092Sdougb * "timep" is not null. 836224092Sdougb */ 837224092Sdougb 838224092Sdougbvoid 839224092Sdougbdst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 840224092Sdougb/*%< 841224092Sdougb * Set a member of the timing metadata array. 842224092Sdougb * 843224092Sdougb * Requires: 844224092Sdougb * "key" is a valid key. 845224092Sdougb * "type" is no larger than DST_MAX_TIMES 846224092Sdougb */ 847224092Sdougb 848224092Sdougbvoid 849224092Sdougbdst_key_unsettime(dst_key_t *key, int type); 850224092Sdougb/*%< 851224092Sdougb * Flag a member of the timing metadata array as "not set". 852224092Sdougb * 853224092Sdougb * Requires: 854224092Sdougb * "key" is a valid key. 855224092Sdougb * "type" is no larger than DST_MAX_TIMES 856224092Sdougb */ 857224092Sdougb 858224092Sdougbisc_result_t 859224092Sdougbdst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 860224092Sdougb/*%< 861224092Sdougb * Get the private key format version number. (If the key does not have 862224092Sdougb * a private key associated with it, the version will be 0.0.) The major 863224092Sdougb * version number is placed in '*majorp', and the minor version number in 864224092Sdougb * '*minorp'. 865224092Sdougb * 866224092Sdougb * Requires: 867224092Sdougb * "key" is a valid key. 868224092Sdougb * "majorp" is not NULL. 869224092Sdougb * "minorp" is not NULL. 870224092Sdougb */ 871224092Sdougb 872224092Sdougbvoid 873224092Sdougbdst_key_setprivateformat(dst_key_t *key, int major, int minor); 874224092Sdougb/*%< 875224092Sdougb * Set the private key format version number. 876224092Sdougb * 877224092Sdougb * Requires: 878224092Sdougb * "key" is a valid key. 879224092Sdougb */ 880224092Sdougb 881224092Sdougb#define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 882224092Sdougb 883224092Sdougbvoid 884224092Sdougbdst_key_format(const dst_key_t *key, char *cp, unsigned int size); 885224092Sdougb/*%< 886224092Sdougb * Write the uniquely identifying information about the key (name, 887224092Sdougb * algorithm, key ID) into a string 'cp' of size 'size'. 888224092Sdougb */ 889224092Sdougb 890224092Sdougb 891224092Sdougbisc_buffer_t * 892224092Sdougbdst_key_tkeytoken(const dst_key_t *key); 893224092Sdougb/*%< 894224092Sdougb * Return the token from the TKEY request, if any. If this key was 895224092Sdougb * not negotiated via TKEY, return NULL. 896225361Sdougb * 897225361Sdougb * Requires: 898225361Sdougb * "key" is a valid key. 899224092Sdougb */ 900224092Sdougb 901224092Sdougb 902224092Sdougbisc_result_t 903224092Sdougbdst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 904224092Sdougb/*%< 905224092Sdougb * Allocate 'buffer' and dump the key into it in base64 format. The buffer 906224092Sdougb * is not NUL terminated. The length of the buffer is returned in *length. 907224092Sdougb * 908224092Sdougb * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 909224092Sdougb * 910224092Sdougb * Requires: 911224092Sdougb * 'buffer' to be non NULL and *buffer to be NULL. 912224092Sdougb * 'length' to be non NULL and *length to be zero. 913224092Sdougb * 914224092Sdougb * Returns: 915224092Sdougb * ISC_R_SUCCESS 916224092Sdougb * ISC_R_NOMEMORY 917224092Sdougb * ISC_R_NOTIMPLEMENTED 918224092Sdougb * others. 919224092Sdougb */ 920224092Sdougb 921224092Sdougbisc_result_t 922224092Sdougbdst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 923224092Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 924224092Sdougb isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 925224092Sdougb 926224092Sdougb 927143731SdougbISC_LANG_ENDDECLS 928143731Sdougb 929143731Sdougb#endif /* DST_DST_H */ 930