1143731Sdougb/* 2262706Serwin * Copyright (C) 2004-2013 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 */ 72287410Sdelphij#define DST_ALG_INDIRECT 252 73143731Sdougb#define DST_ALG_PRIVATE 254 74143731Sdougb#define DST_ALG_EXPAND 255 75143731Sdougb#define DST_MAX_ALGS 255 76143731Sdougb 77170222Sdougb/*% A buffer of this size is large enough to hold any key */ 78143731Sdougb#define DST_KEY_MAXSIZE 1280 79143731Sdougb 80170222Sdougb/*% 81143731Sdougb * A buffer of this size is large enough to hold the textual representation 82143731Sdougb * of any key 83143731Sdougb */ 84143731Sdougb#define DST_KEY_MAXTEXTSIZE 2048 85143731Sdougb 86170222Sdougb/*% 'Type' for dst_read_key() */ 87143731Sdougb#define DST_TYPE_KEY 0x1000000 /* KEY key */ 88143731Sdougb#define DST_TYPE_PRIVATE 0x2000000 89143731Sdougb#define DST_TYPE_PUBLIC 0x4000000 90143731Sdougb 91224092Sdougb/* Key timing metadata definitions */ 92224092Sdougb#define DST_TIME_CREATED 0 93224092Sdougb#define DST_TIME_PUBLISH 1 94224092Sdougb#define DST_TIME_ACTIVATE 2 95224092Sdougb#define DST_TIME_REVOKE 3 96224092Sdougb#define DST_TIME_INACTIVE 4 97224092Sdougb#define DST_TIME_DELETE 5 98224092Sdougb#define DST_TIME_DSPUBLISH 6 99224092Sdougb#define DST_MAX_TIMES 6 100224092Sdougb 101224092Sdougb/* Numeric metadata definitions */ 102224092Sdougb#define DST_NUM_PREDECESSOR 0 103224092Sdougb#define DST_NUM_SUCCESSOR 1 104224092Sdougb#define DST_NUM_MAXTTL 2 105224092Sdougb#define DST_NUM_ROLLPERIOD 3 106224092Sdougb#define DST_MAX_NUMERIC 3 107224092Sdougb 108224092Sdougb/* 109224092Sdougb * Current format version number of the private key parser. 110224092Sdougb * 111224092Sdougb * When parsing a key file with the same major number but a higher minor 112224092Sdougb * number, the key parser will ignore any fields it does not recognize. 113224092Sdougb * Thus, DST_MINOR_VERSION should be incremented whenever new 114224092Sdougb * fields are added to the private key file (such as new metadata). 115224092Sdougb * 116224092Sdougb * When rewriting these keys, those fields will be dropped, and the 117224092Sdougb * format version set back to the current one.. 118224092Sdougb * 119224092Sdougb * When a key is seen with a higher major number, the key parser will 120224092Sdougb * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented 121224092Sdougb * and DST_MINOR_VERSION set to zero whenever there is a format change 122224092Sdougb * which is not backward compatible to previous versions of the dst_key 123224092Sdougb * parser, such as change in the syntax of an existing field, the removal 124224092Sdougb * of a currently mandatory field, or a new field added which would 125224092Sdougb * alter the functioning of the key if it were absent. 126224092Sdougb */ 127224092Sdougb#define DST_MAJOR_VERSION 1 128224092Sdougb#define DST_MINOR_VERSION 3 129224092Sdougb 130143731Sdougb/*** 131143731Sdougb *** Functions 132143731Sdougb ***/ 133143731Sdougb 134143731Sdougbisc_result_t 135143731Sdougbdst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); 136224092Sdougb 137224092Sdougbisc_result_t 138224092Sdougbdst_lib_init2(isc_mem_t *mctx, isc_entropy_t *ectx, 139224092Sdougb const char *engine, unsigned int eflags); 140170222Sdougb/*%< 141143731Sdougb * Initializes the DST subsystem. 142143731Sdougb * 143143731Sdougb * Requires: 144170222Sdougb * \li "mctx" is a valid memory context 145170222Sdougb * \li "ectx" is a valid entropy context 146143731Sdougb * 147143731Sdougb * Returns: 148170222Sdougb * \li ISC_R_SUCCESS 149170222Sdougb * \li ISC_R_NOMEMORY 150224092Sdougb * \li DST_R_NOENGINE 151143731Sdougb * 152143731Sdougb * Ensures: 153170222Sdougb * \li DST is properly initialized. 154143731Sdougb */ 155143731Sdougb 156143731Sdougbvoid 157143731Sdougbdst_lib_destroy(void); 158170222Sdougb/*%< 159143731Sdougb * Releases all resources allocated by DST. 160143731Sdougb */ 161143731Sdougb 162143731Sdougbisc_boolean_t 163143731Sdougbdst_algorithm_supported(unsigned int alg); 164170222Sdougb/*%< 165143731Sdougb * Checks that a given algorithm is supported by DST. 166143731Sdougb * 167143731Sdougb * Returns: 168170222Sdougb * \li ISC_TRUE 169170222Sdougb * \li ISC_FALSE 170143731Sdougb */ 171143731Sdougb 172143731Sdougbisc_result_t 173143731Sdougbdst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); 174254402Serwin 175254402Serwinisc_result_t 176254402Serwindst_context_create2(dst_key_t *key, isc_mem_t *mctx, 177254402Serwin isc_logcategory_t *category, dst_context_t **dctxp); 178254402Serwin 179170222Sdougb/*%< 180143731Sdougb * Creates a context to be used for a sign or verify operation. 181143731Sdougb * 182143731Sdougb * Requires: 183170222Sdougb * \li "key" is a valid key. 184170222Sdougb * \li "mctx" is a valid memory context. 185170222Sdougb * \li dctxp != NULL && *dctxp == NULL 186143731Sdougb * 187143731Sdougb * Returns: 188170222Sdougb * \li ISC_R_SUCCESS 189170222Sdougb * \li ISC_R_NOMEMORY 190143731Sdougb * 191143731Sdougb * Ensures: 192170222Sdougb * \li *dctxp will contain a usable context. 193143731Sdougb */ 194143731Sdougb 195143731Sdougbvoid 196143731Sdougbdst_context_destroy(dst_context_t **dctxp); 197170222Sdougb/*%< 198143731Sdougb * Destroys all memory associated with a context. 199143731Sdougb * 200143731Sdougb * Requires: 201170222Sdougb * \li *dctxp != NULL && *dctxp == NULL 202143731Sdougb * 203143731Sdougb * Ensures: 204170222Sdougb * \li *dctxp == NULL 205143731Sdougb */ 206143731Sdougb 207143731Sdougbisc_result_t 208143731Sdougbdst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 209170222Sdougb/*%< 210143731Sdougb * Incrementally adds data to the context to be used in a sign or verify 211143731Sdougb * operation. 212143731Sdougb * 213143731Sdougb * Requires: 214170222Sdougb * \li "dctx" is a valid context 215170222Sdougb * \li "data" is a valid region 216143731Sdougb * 217143731Sdougb * Returns: 218170222Sdougb * \li ISC_R_SUCCESS 219170222Sdougb * \li DST_R_SIGNFAILURE 220170222Sdougb * \li all other errors indicate failure 221143731Sdougb */ 222143731Sdougb 223143731Sdougbisc_result_t 224143731Sdougbdst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 225170222Sdougb/*%< 226143731Sdougb * Computes a signature using the data and key stored in the context. 227143731Sdougb * 228143731Sdougb * Requires: 229170222Sdougb * \li "dctx" is a valid context. 230170222Sdougb * \li "sig" is a valid buffer. 231143731Sdougb * 232143731Sdougb * Returns: 233170222Sdougb * \li ISC_R_SUCCESS 234170222Sdougb * \li DST_R_VERIFYFAILURE 235170222Sdougb * \li all other errors indicate failure 236143731Sdougb * 237143731Sdougb * Ensures: 238170222Sdougb * \li "sig" will contain the signature 239143731Sdougb */ 240143731Sdougb 241143731Sdougbisc_result_t 242143731Sdougbdst_context_verify(dst_context_t *dctx, isc_region_t *sig); 243254897Serwin 244254897Serwinisc_result_t 245254897Serwindst_context_verify2(dst_context_t *dctx, unsigned int maxbits, 246254897Serwin isc_region_t *sig); 247170222Sdougb/*%< 248143731Sdougb * Verifies the signature using the data and key stored in the context. 249143731Sdougb * 250254897Serwin * 'maxbits' specifies the maximum number of bits permitted in the RSA 251254897Serwin * exponent. 252254897Serwin * 253143731Sdougb * Requires: 254170222Sdougb * \li "dctx" is a valid context. 255170222Sdougb * \li "sig" is a valid region. 256143731Sdougb * 257143731Sdougb * Returns: 258170222Sdougb * \li ISC_R_SUCCESS 259170222Sdougb * \li all other errors indicate failure 260143731Sdougb * 261143731Sdougb * Ensures: 262170222Sdougb * \li "sig" will contain the signature 263143731Sdougb */ 264143731Sdougb 265143731Sdougbisc_result_t 266143731Sdougbdst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 267143731Sdougb isc_buffer_t *secret); 268170222Sdougb/*%< 269143731Sdougb * Computes a shared secret from two (Diffie-Hellman) keys. 270143731Sdougb * 271143731Sdougb * Requires: 272170222Sdougb * \li "pub" is a valid key that can be used to derive a shared secret 273170222Sdougb * \li "priv" is a valid private key that can be used to derive a shared secret 274170222Sdougb * \li "secret" is a valid buffer 275143731Sdougb * 276143731Sdougb * Returns: 277170222Sdougb * \li ISC_R_SUCCESS 278170222Sdougb * \li any other result indicates failure 279143731Sdougb * 280143731Sdougb * Ensures: 281170222Sdougb * \li If successful, secret will contain the derived shared secret. 282143731Sdougb */ 283143731Sdougb 284143731Sdougbisc_result_t 285143731Sdougbdst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 286143731Sdougb const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 287170222Sdougb/*%< 288143731Sdougb * Reads a key from permanent storage. The key can either be a public or 289143731Sdougb * private key, and is specified by name, algorithm, and id. If a private key 290143731Sdougb * is specified, the public key must also be present. If directory is NULL, 291143731Sdougb * the current directory is assumed. 292143731Sdougb * 293143731Sdougb * Requires: 294170222Sdougb * \li "name" is a valid absolute dns name. 295170222Sdougb * \li "id" is a valid key tag identifier. 296170222Sdougb * \li "alg" is a supported key algorithm. 297170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 298143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 299170222Sdougb * \li "mctx" is a valid memory context. 300170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 301143731Sdougb * 302143731Sdougb * Returns: 303170222Sdougb * \li ISC_R_SUCCESS 304170222Sdougb * \li any other result indicates failure 305143731Sdougb * 306143731Sdougb * Ensures: 307170222Sdougb * \li If successful, *keyp will contain a valid key. 308143731Sdougb */ 309143731Sdougb 310143731Sdougbisc_result_t 311224092Sdougbdst_key_fromnamedfile(const char *filename, const char *dirname, 312224092Sdougb int type, isc_mem_t *mctx, dst_key_t **keyp); 313170222Sdougb/*%< 314143731Sdougb * Reads a key from permanent storage. The key can either be a public or 315143731Sdougb * key, and is specified by filename. If a private key is specified, the 316143731Sdougb * public key must also be present. 317143731Sdougb * 318224092Sdougb * If 'dirname' is not NULL, and 'filename' is a relative path, 319224092Sdougb * then the file is looked up relative to the given directory. 320224092Sdougb * If 'filename' is an absolute path, 'dirname' is ignored. 321224092Sdougb * 322143731Sdougb * Requires: 323170222Sdougb * \li "filename" is not NULL 324170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 325143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 326170222Sdougb * \li "mctx" is a valid memory context 327170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 328143731Sdougb * 329143731Sdougb * Returns: 330170222Sdougb * \li ISC_R_SUCCESS 331170222Sdougb * \li any other result indicates failure 332143731Sdougb * 333143731Sdougb * Ensures: 334170222Sdougb * \li If successful, *keyp will contain a valid key. 335143731Sdougb */ 336143731Sdougb 337170222Sdougb 338143731Sdougbisc_result_t 339170222Sdougbdst_key_read_public(const char *filename, int type, 340170222Sdougb isc_mem_t *mctx, dst_key_t **keyp); 341170222Sdougb/*%< 342170222Sdougb * Reads a public key from permanent storage. The key must be a public key. 343170222Sdougb * 344170222Sdougb * Requires: 345170222Sdougb * \li "filename" is not NULL 346170222Sdougb * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 347170222Sdougb * \li "mctx" is a valid memory context 348170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 349170222Sdougb * 350170222Sdougb * Returns: 351170222Sdougb * \li ISC_R_SUCCESS 352170222Sdougb * \li DST_R_BADKEYTYPE if the key type is not the expected one 353170222Sdougb * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 354170222Sdougb * \li any other result indicates failure 355170222Sdougb * 356170222Sdougb * Ensures: 357170222Sdougb * \li If successful, *keyp will contain a valid key. 358170222Sdougb */ 359170222Sdougb 360170222Sdougbisc_result_t 361143731Sdougbdst_key_tofile(const dst_key_t *key, int type, const char *directory); 362170222Sdougb/*%< 363143731Sdougb * Writes a key to permanent storage. The key can either be a public or 364143731Sdougb * private key. Public keys are written in DNS format and private keys 365143731Sdougb * are written as a set of base64 encoded values. If directory is NULL, 366143731Sdougb * the current directory is assumed. 367143731Sdougb * 368143731Sdougb * Requires: 369170222Sdougb * \li "key" is a valid key. 370170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 371143731Sdougb * 372143731Sdougb * Returns: 373170222Sdougb * \li ISC_R_SUCCESS 374170222Sdougb * \li any other result indicates failure 375143731Sdougb */ 376143731Sdougb 377143731Sdougbisc_result_t 378143731Sdougbdst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 379143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 380170222Sdougb/*%< 381143731Sdougb * Converts a DNS KEY record into a DST key. 382143731Sdougb * 383143731Sdougb * Requires: 384170222Sdougb * \li "name" is a valid absolute dns name. 385170222Sdougb * \li "source" is a valid buffer. There must be at least 4 bytes available. 386170222Sdougb * \li "mctx" is a valid memory context. 387170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 388143731Sdougb * 389143731Sdougb * Returns: 390170222Sdougb * \li ISC_R_SUCCESS 391170222Sdougb * \li any other result indicates failure 392143731Sdougb * 393143731Sdougb * Ensures: 394170222Sdougb * \li If successful, *keyp will contain a valid key, and the consumed 395143731Sdougb * pointer in data will be advanced. 396143731Sdougb */ 397143731Sdougb 398143731Sdougbisc_result_t 399143731Sdougbdst_key_todns(const dst_key_t *key, isc_buffer_t *target); 400170222Sdougb/*%< 401143731Sdougb * Converts a DST key into a DNS KEY record. 402143731Sdougb * 403143731Sdougb * Requires: 404170222Sdougb * \li "key" is a valid key. 405170222Sdougb * \li "target" is a valid buffer. There must be at least 4 bytes unused. 406143731Sdougb * 407143731Sdougb * Returns: 408170222Sdougb * \li ISC_R_SUCCESS 409170222Sdougb * \li any other result indicates failure 410143731Sdougb * 411143731Sdougb * Ensures: 412170222Sdougb * \li If successful, the used pointer in 'target' is advanced by at least 4. 413143731Sdougb */ 414143731Sdougb 415143731Sdougbisc_result_t 416143731Sdougbdst_key_frombuffer(dns_name_t *name, unsigned int alg, 417143731Sdougb unsigned int flags, unsigned int protocol, 418143731Sdougb dns_rdataclass_t rdclass, 419143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 420170222Sdougb/*%< 421143731Sdougb * Converts a buffer containing DNS KEY RDATA into a DST key. 422143731Sdougb * 423143731Sdougb * Requires: 424170222Sdougb *\li "name" is a valid absolute dns name. 425170222Sdougb *\li "alg" is a supported key algorithm. 426170222Sdougb *\li "source" is a valid buffer. 427170222Sdougb *\li "mctx" is a valid memory context. 428170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 429143731Sdougb * 430143731Sdougb * Returns: 431170222Sdougb *\li ISC_R_SUCCESS 432170222Sdougb * \li any other result indicates failure 433143731Sdougb * 434143731Sdougb * Ensures: 435170222Sdougb *\li If successful, *keyp will contain a valid key, and the consumed 436143731Sdougb * pointer in source will be advanced. 437143731Sdougb */ 438143731Sdougb 439143731Sdougbisc_result_t 440143731Sdougbdst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 441170222Sdougb/*%< 442143731Sdougb * Converts a DST key into DNS KEY RDATA format. 443143731Sdougb * 444143731Sdougb * Requires: 445170222Sdougb *\li "key" is a valid key. 446170222Sdougb *\li "target" is a valid buffer. 447143731Sdougb * 448143731Sdougb * Returns: 449170222Sdougb *\li ISC_R_SUCCESS 450170222Sdougb * \li any other result indicates failure 451143731Sdougb * 452143731Sdougb * Ensures: 453170222Sdougb *\li If successful, the used pointer in 'target' is advanced. 454143731Sdougb */ 455143731Sdougb 456143731Sdougbisc_result_t 457143731Sdougbdst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 458170222Sdougb/*%< 459143731Sdougb * Converts a public key into a private key, reading the private key 460143731Sdougb * information from the buffer. The buffer should contain the same data 461143731Sdougb * as the .private key file would. 462143731Sdougb * 463143731Sdougb * Requires: 464170222Sdougb *\li "key" is a valid public key. 465170222Sdougb *\li "buffer" is not NULL. 466143731Sdougb * 467143731Sdougb * Returns: 468170222Sdougb *\li ISC_R_SUCCESS 469170222Sdougb * \li any other result indicates failure 470143731Sdougb * 471143731Sdougb * Ensures: 472170222Sdougb *\li If successful, key will contain a valid private key. 473143731Sdougb */ 474143731Sdougb 475193149Sdougbgss_ctx_id_t 476193149Sdougbdst_key_getgssctx(const dst_key_t *key); 477193149Sdougb/*%< 478193149Sdougb * Returns the opaque key data. 479193149Sdougb * Be cautions when using this value unless you know what you are doing. 480193149Sdougb * 481193149Sdougb * Requires: 482193149Sdougb *\li "key" is not NULL. 483193149Sdougb * 484193149Sdougb * Returns: 485193149Sdougb *\li gssctx key data, possibly NULL. 486193149Sdougb */ 487143731Sdougb 488143731Sdougbisc_result_t 489193149Sdougbdst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 490224092Sdougb dst_key_t **keyp, isc_region_t *intoken); 491170222Sdougb/*%< 492143731Sdougb * Converts a GSSAPI opaque context id into a DST key. 493143731Sdougb * 494143731Sdougb * Requires: 495170222Sdougb *\li "name" is a valid absolute dns name. 496193149Sdougb *\li "gssctx" is a GSSAPI context id. 497170222Sdougb *\li "mctx" is a valid memory context. 498170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 499143731Sdougb * 500143731Sdougb * Returns: 501170222Sdougb *\li ISC_R_SUCCESS 502170222Sdougb * \li any other result indicates failure 503143731Sdougb * 504143731Sdougb * Ensures: 505170222Sdougb *\li If successful, *keyp will contain a valid key and be responsible for 506143731Sdougb * the context id. 507143731Sdougb */ 508143731Sdougb 509254897Serwin#ifdef DST_KEY_INTERNAL 510143731Sdougbisc_result_t 511254897Serwindst_key_buildinternal(dns_name_t *name, unsigned int alg, 512254897Serwin unsigned int bits, unsigned int flags, 513254897Serwin unsigned int protocol, dns_rdataclass_t rdclass, 514254897Serwin void *data, isc_mem_t *mctx, dst_key_t **keyp); 515254897Serwin#endif 516254897Serwin 517254897Serwinisc_result_t 518193149Sdougbdst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 519193149Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 520193149Sdougb const char *engine, const char *label, const char *pin, 521193149Sdougb isc_mem_t *mctx, dst_key_t **keyp); 522193149Sdougb 523193149Sdougbisc_result_t 524143731Sdougbdst_key_generate(dns_name_t *name, unsigned int alg, 525143731Sdougb unsigned int bits, unsigned int param, 526143731Sdougb unsigned int flags, unsigned int protocol, 527143731Sdougb dns_rdataclass_t rdclass, 528143731Sdougb isc_mem_t *mctx, dst_key_t **keyp); 529224092Sdougb 530224092Sdougbisc_result_t 531224092Sdougbdst_key_generate2(dns_name_t *name, unsigned int alg, 532224092Sdougb unsigned int bits, unsigned int param, 533224092Sdougb unsigned int flags, unsigned int protocol, 534224092Sdougb dns_rdataclass_t rdclass, 535224092Sdougb isc_mem_t *mctx, dst_key_t **keyp, 536224092Sdougb void (*callback)(int)); 537254897Serwin 538170222Sdougb/*%< 539143731Sdougb * Generate a DST key (or keypair) with the supplied parameters. The 540143731Sdougb * interpretation of the "param" field depends on the algorithm: 541170222Sdougb * \code 542143731Sdougb * RSA: exponent 543143731Sdougb * 0 use exponent 3 544143731Sdougb * !0 use Fermat4 (2^16 + 1) 545143731Sdougb * DH: generator 546143731Sdougb * 0 default - use well known prime if bits == 768 or 1024, 547143731Sdougb * otherwise use 2 as the generator. 548143731Sdougb * !0 use this value as the generator. 549143731Sdougb * DSA: unused 550143731Sdougb * HMACMD5: entropy 551143731Sdougb * 0 default - require good entropy 552143731Sdougb * !0 lack of good entropy is ok 553170222Sdougb *\endcode 554143731Sdougb * 555143731Sdougb * Requires: 556170222Sdougb *\li "name" is a valid absolute dns name. 557170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 558143731Sdougb * 559143731Sdougb * Returns: 560170222Sdougb *\li ISC_R_SUCCESS 561170222Sdougb * \li any other result indicates failure 562143731Sdougb * 563143731Sdougb * Ensures: 564170222Sdougb *\li If successful, *keyp will contain a valid key. 565143731Sdougb */ 566143731Sdougb 567143731Sdougbisc_boolean_t 568143731Sdougbdst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 569170222Sdougb/*%< 570224092Sdougb * Compares two DST keys. Returns true if they match, false otherwise. 571143731Sdougb * 572224092Sdougb * Keys ARE NOT considered to match if one of them is the revoked version 573224092Sdougb * of the other. 574224092Sdougb * 575143731Sdougb * Requires: 576170222Sdougb *\li "key1" is a valid key. 577170222Sdougb *\li "key2" is a valid key. 578143731Sdougb * 579143731Sdougb * Returns: 580170222Sdougb *\li ISC_TRUE 581170222Sdougb * \li ISC_FALSE 582143731Sdougb */ 583143731Sdougb 584143731Sdougbisc_boolean_t 585224092Sdougbdst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 586224092Sdougb isc_boolean_t match_revoked_key); 587224092Sdougb/*%< 588224092Sdougb * Compares only the public portions of two DST keys. Returns true 589224092Sdougb * if they match, false otherwise. This allows us, for example, to 590224092Sdougb * determine whether a public key found in a zone matches up with a 591224092Sdougb * key pair found on disk. 592224092Sdougb * 593224092Sdougb * If match_revoked_key is TRUE, then keys ARE considered to match if one 594224092Sdougb * of them is the revoked version of the other. Otherwise, they are not. 595224092Sdougb * 596224092Sdougb * Requires: 597224092Sdougb *\li "key1" is a valid key. 598224092Sdougb *\li "key2" is a valid key. 599224092Sdougb * 600224092Sdougb * Returns: 601224092Sdougb *\li ISC_TRUE 602224092Sdougb * \li ISC_FALSE 603224092Sdougb */ 604224092Sdougb 605224092Sdougbisc_boolean_t 606143731Sdougbdst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 607170222Sdougb/*%< 608143731Sdougb * Compares the parameters of two DST keys. This is used to determine if 609143731Sdougb * two (Diffie-Hellman) keys can be used to derive a shared secret. 610143731Sdougb * 611143731Sdougb * Requires: 612170222Sdougb *\li "key1" is a valid key. 613170222Sdougb *\li "key2" is a valid key. 614143731Sdougb * 615143731Sdougb * Returns: 616170222Sdougb *\li ISC_TRUE 617170222Sdougb * \li ISC_FALSE 618143731Sdougb */ 619143731Sdougb 620143731Sdougbvoid 621218384Sdougbdst_key_attach(dst_key_t *source, dst_key_t **target); 622218384Sdougb/* 623218384Sdougb * Attach to a existing key increasing the reference count. 624218384Sdougb * 625218384Sdougb * Requires: 626218384Sdougb *\li 'source' to be a valid key. 627218384Sdougb *\li 'target' to be non-NULL and '*target' to be NULL. 628218384Sdougb */ 629218384Sdougb 630218384Sdougbvoid 631143731Sdougbdst_key_free(dst_key_t **keyp); 632170222Sdougb/*%< 633224092Sdougb * Decrement the key's reference counter and, when it reaches zero, 634224092Sdougb * release all memory associated with the key. 635143731Sdougb * 636143731Sdougb * Requires: 637170222Sdougb *\li "keyp" is not NULL and "*keyp" is a valid key. 638224092Sdougb *\li reference counter greater than zero. 639143731Sdougb * 640143731Sdougb * Ensures: 641170222Sdougb *\li All memory associated with "*keyp" will be freed. 642170222Sdougb *\li *keyp == NULL 643143731Sdougb */ 644143731Sdougb 645170222Sdougb/*%< 646143731Sdougb * Accessor functions to obtain key fields. 647143731Sdougb * 648143731Sdougb * Require: 649170222Sdougb *\li "key" is a valid key. 650143731Sdougb */ 651143731Sdougbdns_name_t * 652143731Sdougbdst_key_name(const dst_key_t *key); 653143731Sdougb 654143731Sdougbunsigned int 655143731Sdougbdst_key_size(const dst_key_t *key); 656143731Sdougb 657143731Sdougbunsigned int 658143731Sdougbdst_key_proto(const dst_key_t *key); 659143731Sdougb 660143731Sdougbunsigned int 661143731Sdougbdst_key_alg(const dst_key_t *key); 662143731Sdougb 663143731Sdougbisc_uint32_t 664143731Sdougbdst_key_flags(const dst_key_t *key); 665143731Sdougb 666143731Sdougbdns_keytag_t 667143731Sdougbdst_key_id(const dst_key_t *key); 668143731Sdougb 669234010Sdougbdns_keytag_t 670234010Sdougbdst_key_rid(const dst_key_t *key); 671234010Sdougb 672143731Sdougbdns_rdataclass_t 673143731Sdougbdst_key_class(const dst_key_t *key); 674143731Sdougb 675143731Sdougbisc_boolean_t 676143731Sdougbdst_key_isprivate(const dst_key_t *key); 677143731Sdougb 678143731Sdougbisc_boolean_t 679143731Sdougbdst_key_iszonekey(const dst_key_t *key); 680143731Sdougb 681143731Sdougbisc_boolean_t 682143731Sdougbdst_key_isnullkey(const dst_key_t *key); 683143731Sdougb 684143731Sdougbisc_result_t 685143731Sdougbdst_key_buildfilename(const dst_key_t *key, int type, 686143731Sdougb const char *directory, isc_buffer_t *out); 687170222Sdougb/*%< 688143731Sdougb * Generates the filename used by dst to store the specified key. 689143731Sdougb * If directory is NULL, the current directory is assumed. 690143731Sdougb * 691143731Sdougb * Requires: 692170222Sdougb *\li "key" is a valid key 693170222Sdougb *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 694170222Sdougb *\li "out" is a valid buffer 695143731Sdougb * 696143731Sdougb * Ensures: 697170222Sdougb *\li the file name will be written to "out", and the used pointer will 698143731Sdougb * be advanced. 699143731Sdougb */ 700143731Sdougb 701143731Sdougbisc_result_t 702143731Sdougbdst_key_sigsize(const dst_key_t *key, unsigned int *n); 703170222Sdougb/*%< 704143731Sdougb * Computes the size of a signature generated by the given key. 705143731Sdougb * 706143731Sdougb * Requires: 707170222Sdougb *\li "key" is a valid key. 708170222Sdougb *\li "n" is not NULL 709143731Sdougb * 710143731Sdougb * Returns: 711170222Sdougb *\li #ISC_R_SUCCESS 712170222Sdougb *\li DST_R_UNSUPPORTEDALG 713143731Sdougb * 714143731Sdougb * Ensures: 715170222Sdougb *\li "n" stores the size of a generated signature 716143731Sdougb */ 717143731Sdougb 718143731Sdougbisc_result_t 719143731Sdougbdst_key_secretsize(const dst_key_t *key, unsigned int *n); 720170222Sdougb/*%< 721143731Sdougb * Computes the size of a shared secret generated by the given key. 722143731Sdougb * 723143731Sdougb * Requires: 724170222Sdougb *\li "key" is a valid key. 725170222Sdougb *\li "n" is not NULL 726143731Sdougb * 727143731Sdougb * Returns: 728170222Sdougb *\li #ISC_R_SUCCESS 729170222Sdougb *\li DST_R_UNSUPPORTEDALG 730143731Sdougb * 731143731Sdougb * Ensures: 732170222Sdougb *\li "n" stores the size of a generated shared secret 733143731Sdougb */ 734143731Sdougb 735143731Sdougbisc_uint16_t 736143731Sdougbdst_region_computeid(const isc_region_t *source, unsigned int alg); 737234010Sdougbisc_uint16_t 738234010Sdougbdst_region_computerid(const isc_region_t *source, unsigned int alg); 739170222Sdougb/*%< 740234010Sdougb * Computes the (revoked) key id of the key stored in the provided 741234010Sdougb * region with the given algorithm. 742143731Sdougb * 743143731Sdougb * Requires: 744170222Sdougb *\li "source" contains a valid, non-NULL region. 745143731Sdougb * 746143731Sdougb * Returns: 747170222Sdougb *\li the key id 748143731Sdougb */ 749143731Sdougb 750170222Sdougbisc_uint16_t 751170222Sdougbdst_key_getbits(const dst_key_t *key); 752224092Sdougb/*%< 753170222Sdougb * Get the number of digest bits required (0 == MAX). 754170222Sdougb * 755170222Sdougb * Requires: 756170222Sdougb * "key" is a valid key. 757170222Sdougb */ 758170222Sdougb 759170222Sdougbvoid 760170222Sdougbdst_key_setbits(dst_key_t *key, isc_uint16_t bits); 761224092Sdougb/*%< 762170222Sdougb * Set the number of digest bits required (0 == MAX). 763170222Sdougb * 764170222Sdougb * Requires: 765170222Sdougb * "key" is a valid key. 766170222Sdougb */ 767170222Sdougb 768254897Serwinvoid 769254897Serwindst_key_setttl(dst_key_t *key, dns_ttl_t ttl); 770254897Serwin/*%< 771254897Serwin * Set the default TTL to use when converting the key 772254897Serwin * to a KEY or DNSKEY RR. 773254897Serwin * 774254897Serwin * Requires: 775254897Serwin * "key" is a valid key. 776254897Serwin */ 777254897Serwin 778254897Serwindns_ttl_t 779254897Serwindst_key_getttl(const dst_key_t *key); 780254897Serwin/*%< 781254897Serwin * Get the default TTL to use when converting the key 782254897Serwin * to a KEY or DNSKEY RR. 783254897Serwin * 784254897Serwin * Requires: 785254897Serwin * "key" is a valid key. 786254897Serwin */ 787254897Serwin 788224092Sdougbisc_result_t 789224092Sdougbdst_key_setflags(dst_key_t *key, isc_uint32_t flags); 790224092Sdougb/* 791224092Sdougb * Set the key flags, and recompute the key ID. 792224092Sdougb * 793224092Sdougb * Requires: 794224092Sdougb * "key" is a valid key. 795224092Sdougb */ 796224092Sdougb 797224092Sdougbisc_result_t 798224092Sdougbdst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep); 799224092Sdougb/*%< 800224092Sdougb * Get a member of the numeric metadata array and place it in '*valuep'. 801224092Sdougb * 802224092Sdougb * Requires: 803224092Sdougb * "key" is a valid key. 804224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 805224092Sdougb * "timep" is not null. 806224092Sdougb */ 807224092Sdougb 808224092Sdougbvoid 809224092Sdougbdst_key_setnum(dst_key_t *key, int type, isc_uint32_t value); 810224092Sdougb/*%< 811224092Sdougb * Set a member of the numeric metadata array. 812224092Sdougb * 813224092Sdougb * Requires: 814224092Sdougb * "key" is a valid key. 815224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 816224092Sdougb */ 817224092Sdougb 818224092Sdougbvoid 819224092Sdougbdst_key_unsetnum(dst_key_t *key, int type); 820224092Sdougb/*%< 821224092Sdougb * Flag a member of the numeric metadata array as "not set". 822224092Sdougb * 823224092Sdougb * Requires: 824224092Sdougb * "key" is a valid key. 825224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 826224092Sdougb */ 827224092Sdougb 828224092Sdougbisc_result_t 829224092Sdougbdst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 830224092Sdougb/*%< 831224092Sdougb * Get a member of the timing metadata array and place it in '*timep'. 832224092Sdougb * 833224092Sdougb * Requires: 834224092Sdougb * "key" is a valid key. 835224092Sdougb * "type" is no larger than DST_MAX_TIMES 836224092Sdougb * "timep" is not null. 837224092Sdougb */ 838224092Sdougb 839224092Sdougbvoid 840224092Sdougbdst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 841224092Sdougb/*%< 842224092Sdougb * Set a member of the timing metadata array. 843224092Sdougb * 844224092Sdougb * Requires: 845224092Sdougb * "key" is a valid key. 846224092Sdougb * "type" is no larger than DST_MAX_TIMES 847224092Sdougb */ 848224092Sdougb 849224092Sdougbvoid 850224092Sdougbdst_key_unsettime(dst_key_t *key, int type); 851224092Sdougb/*%< 852224092Sdougb * Flag a member of the timing metadata array as "not set". 853224092Sdougb * 854224092Sdougb * Requires: 855224092Sdougb * "key" is a valid key. 856224092Sdougb * "type" is no larger than DST_MAX_TIMES 857224092Sdougb */ 858224092Sdougb 859224092Sdougbisc_result_t 860224092Sdougbdst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 861224092Sdougb/*%< 862224092Sdougb * Get the private key format version number. (If the key does not have 863224092Sdougb * a private key associated with it, the version will be 0.0.) The major 864224092Sdougb * version number is placed in '*majorp', and the minor version number in 865224092Sdougb * '*minorp'. 866224092Sdougb * 867224092Sdougb * Requires: 868224092Sdougb * "key" is a valid key. 869224092Sdougb * "majorp" is not NULL. 870224092Sdougb * "minorp" is not NULL. 871224092Sdougb */ 872224092Sdougb 873224092Sdougbvoid 874224092Sdougbdst_key_setprivateformat(dst_key_t *key, int major, int minor); 875224092Sdougb/*%< 876224092Sdougb * Set the private key format version number. 877224092Sdougb * 878224092Sdougb * Requires: 879224092Sdougb * "key" is a valid key. 880224092Sdougb */ 881224092Sdougb 882224092Sdougb#define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 883224092Sdougb 884224092Sdougbvoid 885224092Sdougbdst_key_format(const dst_key_t *key, char *cp, unsigned int size); 886224092Sdougb/*%< 887224092Sdougb * Write the uniquely identifying information about the key (name, 888224092Sdougb * algorithm, key ID) into a string 'cp' of size 'size'. 889224092Sdougb */ 890224092Sdougb 891224092Sdougb 892224092Sdougbisc_buffer_t * 893224092Sdougbdst_key_tkeytoken(const dst_key_t *key); 894224092Sdougb/*%< 895224092Sdougb * Return the token from the TKEY request, if any. If this key was 896224092Sdougb * not negotiated via TKEY, return NULL. 897225361Sdougb * 898225361Sdougb * Requires: 899225361Sdougb * "key" is a valid key. 900224092Sdougb */ 901224092Sdougb 902224092Sdougb 903224092Sdougbisc_result_t 904224092Sdougbdst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 905224092Sdougb/*%< 906224092Sdougb * Allocate 'buffer' and dump the key into it in base64 format. The buffer 907224092Sdougb * is not NUL terminated. The length of the buffer is returned in *length. 908224092Sdougb * 909224092Sdougb * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 910224092Sdougb * 911224092Sdougb * Requires: 912224092Sdougb * 'buffer' to be non NULL and *buffer to be NULL. 913224092Sdougb * 'length' to be non NULL and *length to be zero. 914224092Sdougb * 915224092Sdougb * Returns: 916224092Sdougb * ISC_R_SUCCESS 917224092Sdougb * ISC_R_NOMEMORY 918224092Sdougb * ISC_R_NOTIMPLEMENTED 919224092Sdougb * others. 920224092Sdougb */ 921224092Sdougb 922224092Sdougbisc_result_t 923224092Sdougbdst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 924224092Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 925224092Sdougb isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 926224092Sdougb 927262706Serwinisc_boolean_t 928262706Serwindst_key_inactive(const dst_key_t *key); 929262706Serwin/*%< 930262706Serwin * Determines if the private key is missing due the key being deemed inactive. 931262706Serwin * 932262706Serwin * Requires: 933262706Serwin * 'key' to be valid. 934262706Serwin */ 935224092Sdougb 936262706Serwinvoid 937262706Serwindst_key_setinactive(dst_key_t *key, isc_boolean_t inactive); 938262706Serwin/*%< 939262706Serwin * Set key inactive state. 940262706Serwin * 941262706Serwin * Requires: 942262706Serwin * 'key' to be valid. 943262706Serwin */ 944262706Serwin 945262706Serwinvoid 946262706Serwindst_key_setexternal(dst_key_t *key, isc_boolean_t value); 947262706Serwin 948262706Serwinisc_boolean_t 949262706Serwindst_key_isexternal(dst_key_t *key); 950262706Serwin 951143731SdougbISC_LANG_ENDDECLS 952143731Sdougb 953143731Sdougb#endif /* DST_DST_H */ 954