dst.h revision 254402
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 18234010Sdougb/* $Id$ */ 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); 242170222Sdougb/*%< 243143731Sdougb * Verifies the signature using the data and key stored in the context. 244143731Sdougb * 245143731Sdougb * Requires: 246170222Sdougb * \li "dctx" is a valid context. 247170222Sdougb * \li "sig" is a valid region. 248143731Sdougb * 249143731Sdougb * Returns: 250170222Sdougb * \li ISC_R_SUCCESS 251170222Sdougb * \li all other errors indicate failure 252143731Sdougb * 253143731Sdougb * Ensures: 254170222Sdougb * \li "sig" will contain the signature 255143731Sdougb */ 256143731Sdougb 257143731Sdougbisc_result_t 258143731Sdougbdst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 259143731Sdougb isc_buffer_t *secret); 260170222Sdougb/*%< 261143731Sdougb * Computes a shared secret from two (Diffie-Hellman) keys. 262143731Sdougb * 263143731Sdougb * Requires: 264170222Sdougb * \li "pub" is a valid key that can be used to derive a shared secret 265170222Sdougb * \li "priv" is a valid private key that can be used to derive a shared secret 266170222Sdougb * \li "secret" is a valid buffer 267143731Sdougb * 268143731Sdougb * Returns: 269170222Sdougb * \li ISC_R_SUCCESS 270170222Sdougb * \li any other result indicates failure 271143731Sdougb * 272143731Sdougb * Ensures: 273170222Sdougb * \li If successful, secret will contain the derived shared secret. 274143731Sdougb */ 275143731Sdougb 276143731Sdougbisc_result_t 277143731Sdougbdst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 278143731Sdougb const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 279170222Sdougb/*%< 280143731Sdougb * Reads a key from permanent storage. The key can either be a public or 281143731Sdougb * private key, and is specified by name, algorithm, and id. If a private key 282143731Sdougb * is specified, the public key must also be present. If directory is NULL, 283143731Sdougb * the current directory is assumed. 284143731Sdougb * 285143731Sdougb * Requires: 286170222Sdougb * \li "name" is a valid absolute dns name. 287170222Sdougb * \li "id" is a valid key tag identifier. 288170222Sdougb * \li "alg" is a supported key algorithm. 289170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 290143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 291170222Sdougb * \li "mctx" is a valid memory context. 292170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 293143731Sdougb * 294143731Sdougb * Returns: 295170222Sdougb * \li ISC_R_SUCCESS 296170222Sdougb * \li any other result indicates failure 297143731Sdougb * 298143731Sdougb * Ensures: 299170222Sdougb * \li If successful, *keyp will contain a valid key. 300143731Sdougb */ 301143731Sdougb 302143731Sdougbisc_result_t 303224092Sdougbdst_key_fromnamedfile(const char *filename, const char *dirname, 304224092Sdougb int type, isc_mem_t *mctx, dst_key_t **keyp); 305170222Sdougb/*%< 306143731Sdougb * Reads a key from permanent storage. The key can either be a public or 307143731Sdougb * key, and is specified by filename. If a private key is specified, the 308143731Sdougb * public key must also be present. 309143731Sdougb * 310224092Sdougb * If 'dirname' is not NULL, and 'filename' is a relative path, 311224092Sdougb * then the file is looked up relative to the given directory. 312224092Sdougb * If 'filename' is an absolute path, 'dirname' is ignored. 313224092Sdougb * 314143731Sdougb * Requires: 315170222Sdougb * \li "filename" is not NULL 316170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 317143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 318170222Sdougb * \li "mctx" is a valid memory context 319170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 320143731Sdougb * 321143731Sdougb * Returns: 322170222Sdougb * \li ISC_R_SUCCESS 323170222Sdougb * \li any other result indicates failure 324143731Sdougb * 325143731Sdougb * Ensures: 326170222Sdougb * \li If successful, *keyp will contain a valid key. 327143731Sdougb */ 328143731Sdougb 329170222Sdougb 330143731Sdougbisc_result_t 331170222Sdougbdst_key_read_public(const char *filename, int type, 332170222Sdougb isc_mem_t *mctx, dst_key_t **keyp); 333170222Sdougb/*%< 334170222Sdougb * Reads a public key from permanent storage. The key must be a public key. 335170222Sdougb * 336170222Sdougb * Requires: 337170222Sdougb * \li "filename" is not NULL 338170222Sdougb * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 339170222Sdougb * \li "mctx" is a valid memory context 340170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 341170222Sdougb * 342170222Sdougb * Returns: 343170222Sdougb * \li ISC_R_SUCCESS 344170222Sdougb * \li DST_R_BADKEYTYPE if the key type is not the expected one 345170222Sdougb * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 346170222Sdougb * \li any other result indicates failure 347170222Sdougb * 348170222Sdougb * Ensures: 349170222Sdougb * \li If successful, *keyp will contain a valid key. 350170222Sdougb */ 351170222Sdougb 352170222Sdougbisc_result_t 353143731Sdougbdst_key_tofile(const dst_key_t *key, int type, const char *directory); 354170222Sdougb/*%< 355143731Sdougb * Writes a key to permanent storage. The key can either be a public or 356143731Sdougb * private key. Public keys are written in DNS format and private keys 357143731Sdougb * are written as a set of base64 encoded values. If directory is NULL, 358143731Sdougb * the current directory is assumed. 359143731Sdougb * 360143731Sdougb * Requires: 361170222Sdougb * \li "key" is a valid key. 362170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 363143731Sdougb * 364143731Sdougb * Returns: 365170222Sdougb * \li ISC_R_SUCCESS 366170222Sdougb * \li any other result indicates failure 367143731Sdougb */ 368143731Sdougb 369143731Sdougbisc_result_t 370143731Sdougbdst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 371143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 372170222Sdougb/*%< 373143731Sdougb * Converts a DNS KEY record into a DST key. 374143731Sdougb * 375143731Sdougb * Requires: 376170222Sdougb * \li "name" is a valid absolute dns name. 377170222Sdougb * \li "source" is a valid buffer. There must be at least 4 bytes available. 378170222Sdougb * \li "mctx" is a valid memory context. 379170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 380143731Sdougb * 381143731Sdougb * Returns: 382170222Sdougb * \li ISC_R_SUCCESS 383170222Sdougb * \li any other result indicates failure 384143731Sdougb * 385143731Sdougb * Ensures: 386170222Sdougb * \li If successful, *keyp will contain a valid key, and the consumed 387143731Sdougb * pointer in data will be advanced. 388143731Sdougb */ 389143731Sdougb 390143731Sdougbisc_result_t 391143731Sdougbdst_key_todns(const dst_key_t *key, isc_buffer_t *target); 392170222Sdougb/*%< 393143731Sdougb * Converts a DST key into a DNS KEY record. 394143731Sdougb * 395143731Sdougb * Requires: 396170222Sdougb * \li "key" is a valid key. 397170222Sdougb * \li "target" is a valid buffer. There must be at least 4 bytes unused. 398143731Sdougb * 399143731Sdougb * Returns: 400170222Sdougb * \li ISC_R_SUCCESS 401170222Sdougb * \li any other result indicates failure 402143731Sdougb * 403143731Sdougb * Ensures: 404170222Sdougb * \li If successful, the used pointer in 'target' is advanced by at least 4. 405143731Sdougb */ 406143731Sdougb 407143731Sdougbisc_result_t 408143731Sdougbdst_key_frombuffer(dns_name_t *name, unsigned int alg, 409143731Sdougb unsigned int flags, unsigned int protocol, 410143731Sdougb dns_rdataclass_t rdclass, 411143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 412170222Sdougb/*%< 413143731Sdougb * Converts a buffer containing DNS KEY RDATA into a DST key. 414143731Sdougb * 415143731Sdougb * Requires: 416170222Sdougb *\li "name" is a valid absolute dns name. 417170222Sdougb *\li "alg" is a supported key algorithm. 418170222Sdougb *\li "source" is a valid buffer. 419170222Sdougb *\li "mctx" is a valid memory context. 420170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 421143731Sdougb * 422143731Sdougb * Returns: 423170222Sdougb *\li ISC_R_SUCCESS 424170222Sdougb * \li any other result indicates failure 425143731Sdougb * 426143731Sdougb * Ensures: 427170222Sdougb *\li If successful, *keyp will contain a valid key, and the consumed 428143731Sdougb * pointer in source will be advanced. 429143731Sdougb */ 430143731Sdougb 431143731Sdougbisc_result_t 432143731Sdougbdst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 433170222Sdougb/*%< 434143731Sdougb * Converts a DST key into DNS KEY RDATA format. 435143731Sdougb * 436143731Sdougb * Requires: 437170222Sdougb *\li "key" is a valid key. 438170222Sdougb *\li "target" is a valid buffer. 439143731Sdougb * 440143731Sdougb * Returns: 441170222Sdougb *\li ISC_R_SUCCESS 442170222Sdougb * \li any other result indicates failure 443143731Sdougb * 444143731Sdougb * Ensures: 445170222Sdougb *\li If successful, the used pointer in 'target' is advanced. 446143731Sdougb */ 447143731Sdougb 448143731Sdougbisc_result_t 449143731Sdougbdst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 450170222Sdougb/*%< 451143731Sdougb * Converts a public key into a private key, reading the private key 452143731Sdougb * information from the buffer. The buffer should contain the same data 453143731Sdougb * as the .private key file would. 454143731Sdougb * 455143731Sdougb * Requires: 456170222Sdougb *\li "key" is a valid public key. 457170222Sdougb *\li "buffer" is not NULL. 458143731Sdougb * 459143731Sdougb * Returns: 460170222Sdougb *\li ISC_R_SUCCESS 461170222Sdougb * \li any other result indicates failure 462143731Sdougb * 463143731Sdougb * Ensures: 464170222Sdougb *\li If successful, key will contain a valid private key. 465143731Sdougb */ 466143731Sdougb 467193149Sdougbgss_ctx_id_t 468193149Sdougbdst_key_getgssctx(const dst_key_t *key); 469193149Sdougb/*%< 470193149Sdougb * Returns the opaque key data. 471193149Sdougb * Be cautions when using this value unless you know what you are doing. 472193149Sdougb * 473193149Sdougb * Requires: 474193149Sdougb *\li "key" is not NULL. 475193149Sdougb * 476193149Sdougb * Returns: 477193149Sdougb *\li gssctx key data, possibly NULL. 478193149Sdougb */ 479143731Sdougb 480143731Sdougbisc_result_t 481193149Sdougbdst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 482224092Sdougb dst_key_t **keyp, isc_region_t *intoken); 483170222Sdougb/*%< 484143731Sdougb * Converts a GSSAPI opaque context id into a DST key. 485143731Sdougb * 486143731Sdougb * Requires: 487170222Sdougb *\li "name" is a valid absolute dns name. 488193149Sdougb *\li "gssctx" is a GSSAPI context id. 489170222Sdougb *\li "mctx" is a valid memory context. 490170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 491143731Sdougb * 492143731Sdougb * Returns: 493170222Sdougb *\li ISC_R_SUCCESS 494170222Sdougb * \li any other result indicates failure 495143731Sdougb * 496143731Sdougb * Ensures: 497170222Sdougb *\li If successful, *keyp will contain a valid key and be responsible for 498143731Sdougb * the context id. 499143731Sdougb */ 500143731Sdougb 501143731Sdougbisc_result_t 502193149Sdougbdst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 503193149Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 504193149Sdougb const char *engine, const char *label, const char *pin, 505193149Sdougb isc_mem_t *mctx, dst_key_t **keyp); 506193149Sdougb 507193149Sdougbisc_result_t 508143731Sdougbdst_key_generate(dns_name_t *name, unsigned int alg, 509143731Sdougb unsigned int bits, unsigned int param, 510143731Sdougb unsigned int flags, unsigned int protocol, 511143731Sdougb dns_rdataclass_t rdclass, 512143731Sdougb isc_mem_t *mctx, dst_key_t **keyp); 513224092Sdougb 514224092Sdougbisc_result_t 515224092Sdougbdst_key_generate2(dns_name_t *name, unsigned int alg, 516224092Sdougb unsigned int bits, unsigned int param, 517224092Sdougb unsigned int flags, unsigned int protocol, 518224092Sdougb dns_rdataclass_t rdclass, 519224092Sdougb isc_mem_t *mctx, dst_key_t **keyp, 520224092Sdougb void (*callback)(int)); 521170222Sdougb/*%< 522143731Sdougb * Generate a DST key (or keypair) with the supplied parameters. The 523143731Sdougb * interpretation of the "param" field depends on the algorithm: 524170222Sdougb * \code 525143731Sdougb * RSA: exponent 526143731Sdougb * 0 use exponent 3 527143731Sdougb * !0 use Fermat4 (2^16 + 1) 528143731Sdougb * DH: generator 529143731Sdougb * 0 default - use well known prime if bits == 768 or 1024, 530143731Sdougb * otherwise use 2 as the generator. 531143731Sdougb * !0 use this value as the generator. 532143731Sdougb * DSA: unused 533143731Sdougb * HMACMD5: entropy 534143731Sdougb * 0 default - require good entropy 535143731Sdougb * !0 lack of good entropy is ok 536170222Sdougb *\endcode 537143731Sdougb * 538143731Sdougb * Requires: 539170222Sdougb *\li "name" is a valid absolute dns name. 540170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 541143731Sdougb * 542143731Sdougb * Returns: 543170222Sdougb *\li ISC_R_SUCCESS 544170222Sdougb * \li any other result indicates failure 545143731Sdougb * 546143731Sdougb * Ensures: 547170222Sdougb *\li If successful, *keyp will contain a valid key. 548143731Sdougb */ 549143731Sdougb 550143731Sdougbisc_boolean_t 551143731Sdougbdst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 552170222Sdougb/*%< 553224092Sdougb * Compares two DST keys. Returns true if they match, false otherwise. 554143731Sdougb * 555224092Sdougb * Keys ARE NOT considered to match if one of them is the revoked version 556224092Sdougb * of the other. 557224092Sdougb * 558143731Sdougb * Requires: 559170222Sdougb *\li "key1" is a valid key. 560170222Sdougb *\li "key2" is a valid key. 561143731Sdougb * 562143731Sdougb * Returns: 563170222Sdougb *\li ISC_TRUE 564170222Sdougb * \li ISC_FALSE 565143731Sdougb */ 566143731Sdougb 567143731Sdougbisc_boolean_t 568224092Sdougbdst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2, 569224092Sdougb isc_boolean_t match_revoked_key); 570224092Sdougb/*%< 571224092Sdougb * Compares only the public portions of two DST keys. Returns true 572224092Sdougb * if they match, false otherwise. This allows us, for example, to 573224092Sdougb * determine whether a public key found in a zone matches up with a 574224092Sdougb * key pair found on disk. 575224092Sdougb * 576224092Sdougb * If match_revoked_key is TRUE, then keys ARE considered to match if one 577224092Sdougb * of them is the revoked version of the other. Otherwise, they are not. 578224092Sdougb * 579224092Sdougb * Requires: 580224092Sdougb *\li "key1" is a valid key. 581224092Sdougb *\li "key2" is a valid key. 582224092Sdougb * 583224092Sdougb * Returns: 584224092Sdougb *\li ISC_TRUE 585224092Sdougb * \li ISC_FALSE 586224092Sdougb */ 587224092Sdougb 588224092Sdougbisc_boolean_t 589143731Sdougbdst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 590170222Sdougb/*%< 591143731Sdougb * Compares the parameters of two DST keys. This is used to determine if 592143731Sdougb * two (Diffie-Hellman) keys can be used to derive a shared secret. 593143731Sdougb * 594143731Sdougb * Requires: 595170222Sdougb *\li "key1" is a valid key. 596170222Sdougb *\li "key2" is a valid key. 597143731Sdougb * 598143731Sdougb * Returns: 599170222Sdougb *\li ISC_TRUE 600170222Sdougb * \li ISC_FALSE 601143731Sdougb */ 602143731Sdougb 603143731Sdougbvoid 604218384Sdougbdst_key_attach(dst_key_t *source, dst_key_t **target); 605218384Sdougb/* 606218384Sdougb * Attach to a existing key increasing the reference count. 607218384Sdougb * 608218384Sdougb * Requires: 609218384Sdougb *\li 'source' to be a valid key. 610218384Sdougb *\li 'target' to be non-NULL and '*target' to be NULL. 611218384Sdougb */ 612218384Sdougb 613218384Sdougbvoid 614143731Sdougbdst_key_free(dst_key_t **keyp); 615170222Sdougb/*%< 616224092Sdougb * Decrement the key's reference counter and, when it reaches zero, 617224092Sdougb * release all memory associated with the key. 618143731Sdougb * 619143731Sdougb * Requires: 620170222Sdougb *\li "keyp" is not NULL and "*keyp" is a valid key. 621224092Sdougb *\li reference counter greater than zero. 622143731Sdougb * 623143731Sdougb * Ensures: 624170222Sdougb *\li All memory associated with "*keyp" will be freed. 625170222Sdougb *\li *keyp == NULL 626143731Sdougb */ 627143731Sdougb 628170222Sdougb/*%< 629143731Sdougb * Accessor functions to obtain key fields. 630143731Sdougb * 631143731Sdougb * Require: 632170222Sdougb *\li "key" is a valid key. 633143731Sdougb */ 634143731Sdougbdns_name_t * 635143731Sdougbdst_key_name(const dst_key_t *key); 636143731Sdougb 637143731Sdougbunsigned int 638143731Sdougbdst_key_size(const dst_key_t *key); 639143731Sdougb 640143731Sdougbunsigned int 641143731Sdougbdst_key_proto(const dst_key_t *key); 642143731Sdougb 643143731Sdougbunsigned int 644143731Sdougbdst_key_alg(const dst_key_t *key); 645143731Sdougb 646143731Sdougbisc_uint32_t 647143731Sdougbdst_key_flags(const dst_key_t *key); 648143731Sdougb 649143731Sdougbdns_keytag_t 650143731Sdougbdst_key_id(const dst_key_t *key); 651143731Sdougb 652234010Sdougbdns_keytag_t 653234010Sdougbdst_key_rid(const dst_key_t *key); 654234010Sdougb 655143731Sdougbdns_rdataclass_t 656143731Sdougbdst_key_class(const dst_key_t *key); 657143731Sdougb 658143731Sdougbisc_boolean_t 659143731Sdougbdst_key_isprivate(const dst_key_t *key); 660143731Sdougb 661143731Sdougbisc_boolean_t 662143731Sdougbdst_key_iszonekey(const dst_key_t *key); 663143731Sdougb 664143731Sdougbisc_boolean_t 665143731Sdougbdst_key_isnullkey(const dst_key_t *key); 666143731Sdougb 667143731Sdougbisc_result_t 668143731Sdougbdst_key_buildfilename(const dst_key_t *key, int type, 669143731Sdougb const char *directory, isc_buffer_t *out); 670170222Sdougb/*%< 671143731Sdougb * Generates the filename used by dst to store the specified key. 672143731Sdougb * If directory is NULL, the current directory is assumed. 673143731Sdougb * 674143731Sdougb * Requires: 675170222Sdougb *\li "key" is a valid key 676170222Sdougb *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 677170222Sdougb *\li "out" is a valid buffer 678143731Sdougb * 679143731Sdougb * Ensures: 680170222Sdougb *\li the file name will be written to "out", and the used pointer will 681143731Sdougb * be advanced. 682143731Sdougb */ 683143731Sdougb 684143731Sdougbisc_result_t 685143731Sdougbdst_key_sigsize(const dst_key_t *key, unsigned int *n); 686170222Sdougb/*%< 687143731Sdougb * Computes the size of a signature generated by the given key. 688143731Sdougb * 689143731Sdougb * Requires: 690170222Sdougb *\li "key" is a valid key. 691170222Sdougb *\li "n" is not NULL 692143731Sdougb * 693143731Sdougb * Returns: 694170222Sdougb *\li #ISC_R_SUCCESS 695170222Sdougb *\li DST_R_UNSUPPORTEDALG 696143731Sdougb * 697143731Sdougb * Ensures: 698170222Sdougb *\li "n" stores the size of a generated signature 699143731Sdougb */ 700143731Sdougb 701143731Sdougbisc_result_t 702143731Sdougbdst_key_secretsize(const dst_key_t *key, unsigned int *n); 703170222Sdougb/*%< 704143731Sdougb * Computes the size of a shared secret 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 shared secret 716143731Sdougb */ 717143731Sdougb 718143731Sdougbisc_uint16_t 719143731Sdougbdst_region_computeid(const isc_region_t *source, unsigned int alg); 720234010Sdougbisc_uint16_t 721234010Sdougbdst_region_computerid(const isc_region_t *source, unsigned int alg); 722170222Sdougb/*%< 723234010Sdougb * Computes the (revoked) key id of the key stored in the provided 724234010Sdougb * region with the given algorithm. 725143731Sdougb * 726143731Sdougb * Requires: 727170222Sdougb *\li "source" contains a valid, non-NULL region. 728143731Sdougb * 729143731Sdougb * Returns: 730170222Sdougb *\li the key id 731143731Sdougb */ 732143731Sdougb 733170222Sdougbisc_uint16_t 734170222Sdougbdst_key_getbits(const dst_key_t *key); 735224092Sdougb/*%< 736170222Sdougb * Get the number of digest bits required (0 == MAX). 737170222Sdougb * 738170222Sdougb * Requires: 739170222Sdougb * "key" is a valid key. 740170222Sdougb */ 741170222Sdougb 742170222Sdougbvoid 743170222Sdougbdst_key_setbits(dst_key_t *key, isc_uint16_t bits); 744224092Sdougb/*%< 745170222Sdougb * Set the number of digest bits required (0 == MAX). 746170222Sdougb * 747170222Sdougb * Requires: 748170222Sdougb * "key" is a valid key. 749170222Sdougb */ 750170222Sdougb 751224092Sdougbisc_result_t 752224092Sdougbdst_key_setflags(dst_key_t *key, isc_uint32_t flags); 753224092Sdougb/* 754224092Sdougb * Set the key flags, and recompute the key ID. 755224092Sdougb * 756224092Sdougb * Requires: 757224092Sdougb * "key" is a valid key. 758224092Sdougb */ 759224092Sdougb 760224092Sdougbisc_result_t 761224092Sdougbdst_key_getnum(const dst_key_t *key, int type, isc_uint32_t *valuep); 762224092Sdougb/*%< 763224092Sdougb * Get a member of the numeric metadata array and place it in '*valuep'. 764224092Sdougb * 765224092Sdougb * Requires: 766224092Sdougb * "key" is a valid key. 767224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 768224092Sdougb * "timep" is not null. 769224092Sdougb */ 770224092Sdougb 771224092Sdougbvoid 772224092Sdougbdst_key_setnum(dst_key_t *key, int type, isc_uint32_t value); 773224092Sdougb/*%< 774224092Sdougb * Set a member of the numeric metadata array. 775224092Sdougb * 776224092Sdougb * Requires: 777224092Sdougb * "key" is a valid key. 778224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 779224092Sdougb */ 780224092Sdougb 781224092Sdougbvoid 782224092Sdougbdst_key_unsetnum(dst_key_t *key, int type); 783224092Sdougb/*%< 784224092Sdougb * Flag a member of the numeric metadata array as "not set". 785224092Sdougb * 786224092Sdougb * Requires: 787224092Sdougb * "key" is a valid key. 788224092Sdougb * "type" is no larger than DST_MAX_NUMERIC 789224092Sdougb */ 790224092Sdougb 791224092Sdougbisc_result_t 792224092Sdougbdst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep); 793224092Sdougb/*%< 794224092Sdougb * Get a member of the timing metadata array and place it in '*timep'. 795224092Sdougb * 796224092Sdougb * Requires: 797224092Sdougb * "key" is a valid key. 798224092Sdougb * "type" is no larger than DST_MAX_TIMES 799224092Sdougb * "timep" is not null. 800224092Sdougb */ 801224092Sdougb 802224092Sdougbvoid 803224092Sdougbdst_key_settime(dst_key_t *key, int type, isc_stdtime_t when); 804224092Sdougb/*%< 805224092Sdougb * Set a member of the timing metadata array. 806224092Sdougb * 807224092Sdougb * Requires: 808224092Sdougb * "key" is a valid key. 809224092Sdougb * "type" is no larger than DST_MAX_TIMES 810224092Sdougb */ 811224092Sdougb 812224092Sdougbvoid 813224092Sdougbdst_key_unsettime(dst_key_t *key, int type); 814224092Sdougb/*%< 815224092Sdougb * Flag a member of the timing metadata array as "not set". 816224092Sdougb * 817224092Sdougb * Requires: 818224092Sdougb * "key" is a valid key. 819224092Sdougb * "type" is no larger than DST_MAX_TIMES 820224092Sdougb */ 821224092Sdougb 822224092Sdougbisc_result_t 823224092Sdougbdst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp); 824224092Sdougb/*%< 825224092Sdougb * Get the private key format version number. (If the key does not have 826224092Sdougb * a private key associated with it, the version will be 0.0.) The major 827224092Sdougb * version number is placed in '*majorp', and the minor version number in 828224092Sdougb * '*minorp'. 829224092Sdougb * 830224092Sdougb * Requires: 831224092Sdougb * "key" is a valid key. 832224092Sdougb * "majorp" is not NULL. 833224092Sdougb * "minorp" is not NULL. 834224092Sdougb */ 835224092Sdougb 836224092Sdougbvoid 837224092Sdougbdst_key_setprivateformat(dst_key_t *key, int major, int minor); 838224092Sdougb/*%< 839224092Sdougb * Set the private key format version number. 840224092Sdougb * 841224092Sdougb * Requires: 842224092Sdougb * "key" is a valid key. 843224092Sdougb */ 844224092Sdougb 845224092Sdougb#define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7) 846224092Sdougb 847224092Sdougbvoid 848224092Sdougbdst_key_format(const dst_key_t *key, char *cp, unsigned int size); 849224092Sdougb/*%< 850224092Sdougb * Write the uniquely identifying information about the key (name, 851224092Sdougb * algorithm, key ID) into a string 'cp' of size 'size'. 852224092Sdougb */ 853224092Sdougb 854224092Sdougb 855224092Sdougbisc_buffer_t * 856224092Sdougbdst_key_tkeytoken(const dst_key_t *key); 857224092Sdougb/*%< 858224092Sdougb * Return the token from the TKEY request, if any. If this key was 859224092Sdougb * not negotiated via TKEY, return NULL. 860225361Sdougb * 861225361Sdougb * Requires: 862225361Sdougb * "key" is a valid key. 863224092Sdougb */ 864224092Sdougb 865224092Sdougb 866224092Sdougbisc_result_t 867224092Sdougbdst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length); 868224092Sdougb/*%< 869224092Sdougb * Allocate 'buffer' and dump the key into it in base64 format. The buffer 870224092Sdougb * is not NUL terminated. The length of the buffer is returned in *length. 871224092Sdougb * 872224092Sdougb * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length); 873224092Sdougb * 874224092Sdougb * Requires: 875224092Sdougb * 'buffer' to be non NULL and *buffer to be NULL. 876224092Sdougb * 'length' to be non NULL and *length to be zero. 877224092Sdougb * 878224092Sdougb * Returns: 879224092Sdougb * ISC_R_SUCCESS 880224092Sdougb * ISC_R_NOMEMORY 881224092Sdougb * ISC_R_NOTIMPLEMENTED 882224092Sdougb * others. 883224092Sdougb */ 884224092Sdougb 885224092Sdougbisc_result_t 886224092Sdougbdst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags, 887224092Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 888224092Sdougb isc_mem_t *mctx, const char *keystr, dst_key_t **keyp); 889224092Sdougb 890224092Sdougb 891143731SdougbISC_LANG_ENDDECLS 892143731Sdougb 893143731Sdougb#endif /* DST_DST_H */ 894