dst.h revision 218384
1143731Sdougb/* 2204619Sdougb * Copyright (C) 2004-2008, 2010 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 18218384Sdougb/* $Id: dst.h,v 1.12.50.3 2010-12-09 01:12:55 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> 26143731Sdougb 27143731Sdougb#include <dns/types.h> 28143731Sdougb 29193149Sdougb#include <dst/gssapi.h> 30193149Sdougb 31143731SdougbISC_LANG_BEGINDECLS 32143731Sdougb 33143731Sdougb/*** 34143731Sdougb *** Types 35143731Sdougb ***/ 36143731Sdougb 37170222Sdougb/*% 38143731Sdougb * The dst_key structure is opaque. Applications should use the accessor 39143731Sdougb * functions provided to retrieve key attributes. If an application needs 40143731Sdougb * to set attributes, new accessor functions will be written. 41143731Sdougb */ 42143731Sdougb 43143731Sdougbtypedef struct dst_key dst_key_t; 44143731Sdougbtypedef struct dst_context dst_context_t; 45143731Sdougb 46143731Sdougb/* DST algorithm codes */ 47143731Sdougb#define DST_ALG_UNKNOWN 0 48143731Sdougb#define DST_ALG_RSAMD5 1 49170222Sdougb#define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ 50143731Sdougb#define DST_ALG_DH 2 51143731Sdougb#define DST_ALG_DSA 3 52143731Sdougb#define DST_ALG_ECC 4 53143731Sdougb#define DST_ALG_RSASHA1 5 54193149Sdougb#define DST_ALG_NSEC3DSA 6 55193149Sdougb#define DST_ALG_NSEC3RSASHA1 7 56204619Sdougb#define DST_ALG_RSASHA256 8 57204619Sdougb#define DST_ALG_RSASHA512 10 58143731Sdougb#define DST_ALG_HMACMD5 157 59143731Sdougb#define DST_ALG_GSSAPI 160 60170222Sdougb#define DST_ALG_HMACSHA1 161 /* XXXMPA */ 61170222Sdougb#define DST_ALG_HMACSHA224 162 /* XXXMPA */ 62170222Sdougb#define DST_ALG_HMACSHA256 163 /* XXXMPA */ 63170222Sdougb#define DST_ALG_HMACSHA384 164 /* XXXMPA */ 64170222Sdougb#define DST_ALG_HMACSHA512 165 /* XXXMPA */ 65143731Sdougb#define DST_ALG_PRIVATE 254 66143731Sdougb#define DST_ALG_EXPAND 255 67143731Sdougb#define DST_MAX_ALGS 255 68143731Sdougb 69170222Sdougb/*% A buffer of this size is large enough to hold any key */ 70143731Sdougb#define DST_KEY_MAXSIZE 1280 71143731Sdougb 72170222Sdougb/*% 73143731Sdougb * A buffer of this size is large enough to hold the textual representation 74143731Sdougb * of any key 75143731Sdougb */ 76143731Sdougb#define DST_KEY_MAXTEXTSIZE 2048 77143731Sdougb 78170222Sdougb/*% 'Type' for dst_read_key() */ 79143731Sdougb#define DST_TYPE_KEY 0x1000000 /* KEY key */ 80143731Sdougb#define DST_TYPE_PRIVATE 0x2000000 81143731Sdougb#define DST_TYPE_PUBLIC 0x4000000 82143731Sdougb 83143731Sdougb/*** 84143731Sdougb *** Functions 85143731Sdougb ***/ 86143731Sdougb 87143731Sdougbisc_result_t 88143731Sdougbdst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); 89170222Sdougb/*%< 90143731Sdougb * Initializes the DST subsystem. 91143731Sdougb * 92143731Sdougb * Requires: 93170222Sdougb * \li "mctx" is a valid memory context 94170222Sdougb * \li "ectx" is a valid entropy context 95143731Sdougb * 96143731Sdougb * Returns: 97170222Sdougb * \li ISC_R_SUCCESS 98170222Sdougb * \li ISC_R_NOMEMORY 99143731Sdougb * 100143731Sdougb * Ensures: 101170222Sdougb * \li DST is properly initialized. 102143731Sdougb */ 103143731Sdougb 104143731Sdougbvoid 105143731Sdougbdst_lib_destroy(void); 106170222Sdougb/*%< 107143731Sdougb * Releases all resources allocated by DST. 108143731Sdougb */ 109143731Sdougb 110143731Sdougbisc_boolean_t 111143731Sdougbdst_algorithm_supported(unsigned int alg); 112170222Sdougb/*%< 113143731Sdougb * Checks that a given algorithm is supported by DST. 114143731Sdougb * 115143731Sdougb * Returns: 116170222Sdougb * \li ISC_TRUE 117170222Sdougb * \li ISC_FALSE 118143731Sdougb */ 119143731Sdougb 120143731Sdougbisc_result_t 121143731Sdougbdst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); 122170222Sdougb/*%< 123143731Sdougb * Creates a context to be used for a sign or verify operation. 124143731Sdougb * 125143731Sdougb * Requires: 126170222Sdougb * \li "key" is a valid key. 127170222Sdougb * \li "mctx" is a valid memory context. 128170222Sdougb * \li dctxp != NULL && *dctxp == NULL 129143731Sdougb * 130143731Sdougb * Returns: 131170222Sdougb * \li ISC_R_SUCCESS 132170222Sdougb * \li ISC_R_NOMEMORY 133143731Sdougb * 134143731Sdougb * Ensures: 135170222Sdougb * \li *dctxp will contain a usable context. 136143731Sdougb */ 137143731Sdougb 138143731Sdougbvoid 139143731Sdougbdst_context_destroy(dst_context_t **dctxp); 140170222Sdougb/*%< 141143731Sdougb * Destroys all memory associated with a context. 142143731Sdougb * 143143731Sdougb * Requires: 144170222Sdougb * \li *dctxp != NULL && *dctxp == NULL 145143731Sdougb * 146143731Sdougb * Ensures: 147170222Sdougb * \li *dctxp == NULL 148143731Sdougb */ 149143731Sdougb 150143731Sdougbisc_result_t 151143731Sdougbdst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 152170222Sdougb/*%< 153143731Sdougb * Incrementally adds data to the context to be used in a sign or verify 154143731Sdougb * operation. 155143731Sdougb * 156143731Sdougb * Requires: 157170222Sdougb * \li "dctx" is a valid context 158170222Sdougb * \li "data" is a valid region 159143731Sdougb * 160143731Sdougb * Returns: 161170222Sdougb * \li ISC_R_SUCCESS 162170222Sdougb * \li DST_R_SIGNFAILURE 163170222Sdougb * \li all other errors indicate failure 164143731Sdougb */ 165143731Sdougb 166143731Sdougbisc_result_t 167143731Sdougbdst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 168170222Sdougb/*%< 169143731Sdougb * Computes a signature using the data and key stored in the context. 170143731Sdougb * 171143731Sdougb * Requires: 172170222Sdougb * \li "dctx" is a valid context. 173170222Sdougb * \li "sig" is a valid buffer. 174143731Sdougb * 175143731Sdougb * Returns: 176170222Sdougb * \li ISC_R_SUCCESS 177170222Sdougb * \li DST_R_VERIFYFAILURE 178170222Sdougb * \li all other errors indicate failure 179143731Sdougb * 180143731Sdougb * Ensures: 181170222Sdougb * \li "sig" will contain the signature 182143731Sdougb */ 183143731Sdougb 184143731Sdougbisc_result_t 185143731Sdougbdst_context_verify(dst_context_t *dctx, isc_region_t *sig); 186170222Sdougb/*%< 187143731Sdougb * Verifies the signature using the data and key stored in the context. 188143731Sdougb * 189143731Sdougb * Requires: 190170222Sdougb * \li "dctx" is a valid context. 191170222Sdougb * \li "sig" is a valid region. 192143731Sdougb * 193143731Sdougb * Returns: 194170222Sdougb * \li ISC_R_SUCCESS 195170222Sdougb * \li all other errors indicate failure 196143731Sdougb * 197143731Sdougb * Ensures: 198170222Sdougb * \li "sig" will contain the signature 199143731Sdougb */ 200143731Sdougb 201143731Sdougbisc_result_t 202143731Sdougbdst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, 203143731Sdougb isc_buffer_t *secret); 204170222Sdougb/*%< 205143731Sdougb * Computes a shared secret from two (Diffie-Hellman) keys. 206143731Sdougb * 207143731Sdougb * Requires: 208170222Sdougb * \li "pub" is a valid key that can be used to derive a shared secret 209170222Sdougb * \li "priv" is a valid private key that can be used to derive a shared secret 210170222Sdougb * \li "secret" is a valid buffer 211143731Sdougb * 212143731Sdougb * Returns: 213170222Sdougb * \li ISC_R_SUCCESS 214170222Sdougb * \li any other result indicates failure 215143731Sdougb * 216143731Sdougb * Ensures: 217170222Sdougb * \li If successful, secret will contain the derived shared secret. 218143731Sdougb */ 219143731Sdougb 220143731Sdougbisc_result_t 221143731Sdougbdst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, 222143731Sdougb const char *directory, isc_mem_t *mctx, dst_key_t **keyp); 223170222Sdougb/*%< 224143731Sdougb * Reads a key from permanent storage. The key can either be a public or 225143731Sdougb * private key, and is specified by name, algorithm, and id. If a private key 226143731Sdougb * is specified, the public key must also be present. If directory is NULL, 227143731Sdougb * the current directory is assumed. 228143731Sdougb * 229143731Sdougb * Requires: 230170222Sdougb * \li "name" is a valid absolute dns name. 231170222Sdougb * \li "id" is a valid key tag identifier. 232170222Sdougb * \li "alg" is a supported key algorithm. 233170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. 234143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 235170222Sdougb * \li "mctx" is a valid memory context. 236170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 237143731Sdougb * 238143731Sdougb * Returns: 239170222Sdougb * \li ISC_R_SUCCESS 240170222Sdougb * \li any other result indicates failure 241143731Sdougb * 242143731Sdougb * Ensures: 243170222Sdougb * \li If successful, *keyp will contain a valid key. 244143731Sdougb */ 245143731Sdougb 246143731Sdougbisc_result_t 247143731Sdougbdst_key_fromnamedfile(const char *filename, int type, isc_mem_t *mctx, 248143731Sdougb dst_key_t **keyp); 249170222Sdougb/*%< 250143731Sdougb * Reads a key from permanent storage. The key can either be a public or 251143731Sdougb * key, and is specified by filename. If a private key is specified, the 252143731Sdougb * public key must also be present. 253143731Sdougb * 254143731Sdougb * Requires: 255170222Sdougb * \li "filename" is not NULL 256170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 257143731Sdougb * DST_TYPE_KEY look for a KEY record otherwise DNSKEY 258170222Sdougb * \li "mctx" is a valid memory context 259170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 260143731Sdougb * 261143731Sdougb * Returns: 262170222Sdougb * \li ISC_R_SUCCESS 263170222Sdougb * \li any other result indicates failure 264143731Sdougb * 265143731Sdougb * Ensures: 266170222Sdougb * \li If successful, *keyp will contain a valid key. 267143731Sdougb */ 268143731Sdougb 269170222Sdougb 270143731Sdougbisc_result_t 271170222Sdougbdst_key_read_public(const char *filename, int type, 272170222Sdougb isc_mem_t *mctx, dst_key_t **keyp); 273170222Sdougb/*%< 274170222Sdougb * Reads a public key from permanent storage. The key must be a public key. 275170222Sdougb * 276170222Sdougb * Requires: 277170222Sdougb * \li "filename" is not NULL 278170222Sdougb * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY 279170222Sdougb * \li "mctx" is a valid memory context 280170222Sdougb * \li "keyp" is not NULL and "*keyp" is NULL. 281170222Sdougb * 282170222Sdougb * Returns: 283170222Sdougb * \li ISC_R_SUCCESS 284170222Sdougb * \li DST_R_BADKEYTYPE if the key type is not the expected one 285170222Sdougb * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key 286170222Sdougb * \li any other result indicates failure 287170222Sdougb * 288170222Sdougb * Ensures: 289170222Sdougb * \li If successful, *keyp will contain a valid key. 290170222Sdougb */ 291170222Sdougb 292170222Sdougbisc_result_t 293143731Sdougbdst_key_tofile(const dst_key_t *key, int type, const char *directory); 294170222Sdougb/*%< 295143731Sdougb * Writes a key to permanent storage. The key can either be a public or 296143731Sdougb * private key. Public keys are written in DNS format and private keys 297143731Sdougb * are written as a set of base64 encoded values. If directory is NULL, 298143731Sdougb * the current directory is assumed. 299143731Sdougb * 300143731Sdougb * Requires: 301170222Sdougb * \li "key" is a valid key. 302170222Sdougb * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union 303143731Sdougb * 304143731Sdougb * Returns: 305170222Sdougb * \li ISC_R_SUCCESS 306170222Sdougb * \li any other result indicates failure 307143731Sdougb */ 308143731Sdougb 309143731Sdougbisc_result_t 310143731Sdougbdst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, 311143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 312170222Sdougb/*%< 313143731Sdougb * Converts a DNS KEY record into a DST key. 314143731Sdougb * 315143731Sdougb * Requires: 316170222Sdougb * \li "name" is a valid absolute dns name. 317170222Sdougb * \li "source" is a valid buffer. There must be at least 4 bytes available. 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, and the consumed 327143731Sdougb * pointer in data will be advanced. 328143731Sdougb */ 329143731Sdougb 330143731Sdougbisc_result_t 331143731Sdougbdst_key_todns(const dst_key_t *key, isc_buffer_t *target); 332170222Sdougb/*%< 333143731Sdougb * Converts a DST key into a DNS KEY record. 334143731Sdougb * 335143731Sdougb * Requires: 336170222Sdougb * \li "key" is a valid key. 337170222Sdougb * \li "target" is a valid buffer. There must be at least 4 bytes unused. 338143731Sdougb * 339143731Sdougb * Returns: 340170222Sdougb * \li ISC_R_SUCCESS 341170222Sdougb * \li any other result indicates failure 342143731Sdougb * 343143731Sdougb * Ensures: 344170222Sdougb * \li If successful, the used pointer in 'target' is advanced by at least 4. 345143731Sdougb */ 346143731Sdougb 347143731Sdougbisc_result_t 348143731Sdougbdst_key_frombuffer(dns_name_t *name, unsigned int alg, 349143731Sdougb unsigned int flags, unsigned int protocol, 350143731Sdougb dns_rdataclass_t rdclass, 351143731Sdougb isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); 352170222Sdougb/*%< 353143731Sdougb * Converts a buffer containing DNS KEY RDATA into a DST key. 354143731Sdougb * 355143731Sdougb * Requires: 356170222Sdougb *\li "name" is a valid absolute dns name. 357170222Sdougb *\li "alg" is a supported key algorithm. 358170222Sdougb *\li "source" is a valid buffer. 359170222Sdougb *\li "mctx" is a valid memory context. 360170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 361143731Sdougb * 362143731Sdougb * Returns: 363170222Sdougb *\li ISC_R_SUCCESS 364170222Sdougb * \li any other result indicates failure 365143731Sdougb * 366143731Sdougb * Ensures: 367170222Sdougb *\li If successful, *keyp will contain a valid key, and the consumed 368143731Sdougb * pointer in source will be advanced. 369143731Sdougb */ 370143731Sdougb 371143731Sdougbisc_result_t 372143731Sdougbdst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); 373170222Sdougb/*%< 374143731Sdougb * Converts a DST key into DNS KEY RDATA format. 375143731Sdougb * 376143731Sdougb * Requires: 377170222Sdougb *\li "key" is a valid key. 378170222Sdougb *\li "target" is a valid buffer. 379143731Sdougb * 380143731Sdougb * Returns: 381170222Sdougb *\li ISC_R_SUCCESS 382170222Sdougb * \li any other result indicates failure 383143731Sdougb * 384143731Sdougb * Ensures: 385170222Sdougb *\li If successful, the used pointer in 'target' is advanced. 386143731Sdougb */ 387143731Sdougb 388143731Sdougbisc_result_t 389143731Sdougbdst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); 390170222Sdougb/*%< 391143731Sdougb * Converts a public key into a private key, reading the private key 392143731Sdougb * information from the buffer. The buffer should contain the same data 393143731Sdougb * as the .private key file would. 394143731Sdougb * 395143731Sdougb * Requires: 396170222Sdougb *\li "key" is a valid public key. 397170222Sdougb *\li "buffer" is not NULL. 398143731Sdougb * 399143731Sdougb * Returns: 400170222Sdougb *\li ISC_R_SUCCESS 401170222Sdougb * \li any other result indicates failure 402143731Sdougb * 403143731Sdougb * Ensures: 404170222Sdougb *\li If successful, key will contain a valid private key. 405143731Sdougb */ 406143731Sdougb 407193149Sdougbgss_ctx_id_t 408193149Sdougbdst_key_getgssctx(const dst_key_t *key); 409193149Sdougb/*%< 410193149Sdougb * Returns the opaque key data. 411193149Sdougb * Be cautions when using this value unless you know what you are doing. 412193149Sdougb * 413193149Sdougb * Requires: 414193149Sdougb *\li "key" is not NULL. 415193149Sdougb * 416193149Sdougb * Returns: 417193149Sdougb *\li gssctx key data, possibly NULL. 418193149Sdougb */ 419143731Sdougb 420143731Sdougbisc_result_t 421193149Sdougbdst_key_fromgssapi(dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx, 422193149Sdougb dst_key_t **keyp); 423170222Sdougb/*%< 424143731Sdougb * Converts a GSSAPI opaque context id into a DST key. 425143731Sdougb * 426143731Sdougb * Requires: 427170222Sdougb *\li "name" is a valid absolute dns name. 428193149Sdougb *\li "gssctx" is a GSSAPI context id. 429170222Sdougb *\li "mctx" is a valid memory context. 430170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 431143731Sdougb * 432143731Sdougb * Returns: 433170222Sdougb *\li ISC_R_SUCCESS 434170222Sdougb * \li any other result indicates failure 435143731Sdougb * 436143731Sdougb * Ensures: 437170222Sdougb *\li If successful, *keyp will contain a valid key and be responsible for 438143731Sdougb * the context id. 439143731Sdougb */ 440143731Sdougb 441143731Sdougbisc_result_t 442193149Sdougbdst_key_fromlabel(dns_name_t *name, int alg, unsigned int flags, 443193149Sdougb unsigned int protocol, dns_rdataclass_t rdclass, 444193149Sdougb const char *engine, const char *label, const char *pin, 445193149Sdougb isc_mem_t *mctx, dst_key_t **keyp); 446193149Sdougb 447193149Sdougbisc_result_t 448143731Sdougbdst_key_generate(dns_name_t *name, unsigned int alg, 449143731Sdougb unsigned int bits, unsigned int param, 450143731Sdougb unsigned int flags, unsigned int protocol, 451143731Sdougb dns_rdataclass_t rdclass, 452143731Sdougb isc_mem_t *mctx, dst_key_t **keyp); 453170222Sdougb/*%< 454143731Sdougb * Generate a DST key (or keypair) with the supplied parameters. The 455143731Sdougb * interpretation of the "param" field depends on the algorithm: 456170222Sdougb * \code 457143731Sdougb * RSA: exponent 458143731Sdougb * 0 use exponent 3 459143731Sdougb * !0 use Fermat4 (2^16 + 1) 460143731Sdougb * DH: generator 461143731Sdougb * 0 default - use well known prime if bits == 768 or 1024, 462143731Sdougb * otherwise use 2 as the generator. 463143731Sdougb * !0 use this value as the generator. 464143731Sdougb * DSA: unused 465143731Sdougb * HMACMD5: entropy 466143731Sdougb * 0 default - require good entropy 467143731Sdougb * !0 lack of good entropy is ok 468170222Sdougb *\endcode 469143731Sdougb * 470143731Sdougb * Requires: 471170222Sdougb *\li "name" is a valid absolute dns name. 472170222Sdougb *\li "keyp" is not NULL and "*keyp" is NULL. 473143731Sdougb * 474143731Sdougb * Returns: 475170222Sdougb *\li ISC_R_SUCCESS 476170222Sdougb * \li any other result indicates failure 477143731Sdougb * 478143731Sdougb * Ensures: 479170222Sdougb *\li If successful, *keyp will contain a valid key. 480143731Sdougb */ 481143731Sdougb 482143731Sdougbisc_boolean_t 483143731Sdougbdst_key_compare(const dst_key_t *key1, const dst_key_t *key2); 484170222Sdougb/*%< 485143731Sdougb * Compares two DST keys. 486143731Sdougb * 487143731Sdougb * Requires: 488170222Sdougb *\li "key1" is a valid key. 489170222Sdougb *\li "key2" is a valid key. 490143731Sdougb * 491143731Sdougb * Returns: 492170222Sdougb *\li ISC_TRUE 493170222Sdougb * \li ISC_FALSE 494143731Sdougb */ 495143731Sdougb 496143731Sdougbisc_boolean_t 497143731Sdougbdst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); 498170222Sdougb/*%< 499143731Sdougb * Compares the parameters of two DST keys. This is used to determine if 500143731Sdougb * two (Diffie-Hellman) keys can be used to derive a shared secret. 501143731Sdougb * 502143731Sdougb * Requires: 503170222Sdougb *\li "key1" is a valid key. 504170222Sdougb *\li "key2" is a valid key. 505143731Sdougb * 506143731Sdougb * Returns: 507170222Sdougb *\li ISC_TRUE 508170222Sdougb * \li ISC_FALSE 509143731Sdougb */ 510143731Sdougb 511143731Sdougbvoid 512218384Sdougbdst_key_attach(dst_key_t *source, dst_key_t **target); 513218384Sdougb/* 514218384Sdougb * Attach to a existing key increasing the reference count. 515218384Sdougb * 516218384Sdougb * Requires: 517218384Sdougb *\li 'source' to be a valid key. 518218384Sdougb *\li 'target' to be non-NULL and '*target' to be NULL. 519218384Sdougb */ 520218384Sdougb 521218384Sdougbvoid 522143731Sdougbdst_key_free(dst_key_t **keyp); 523170222Sdougb/*%< 524143731Sdougb * Release all memory associated with the key. 525143731Sdougb * 526143731Sdougb * Requires: 527170222Sdougb *\li "keyp" is not NULL and "*keyp" is a valid key. 528143731Sdougb * 529143731Sdougb * Ensures: 530170222Sdougb *\li All memory associated with "*keyp" will be freed. 531170222Sdougb *\li *keyp == NULL 532143731Sdougb */ 533143731Sdougb 534170222Sdougb/*%< 535143731Sdougb * Accessor functions to obtain key fields. 536143731Sdougb * 537143731Sdougb * Require: 538170222Sdougb *\li "key" is a valid key. 539143731Sdougb */ 540143731Sdougbdns_name_t * 541143731Sdougbdst_key_name(const dst_key_t *key); 542143731Sdougb 543143731Sdougbunsigned int 544143731Sdougbdst_key_size(const dst_key_t *key); 545143731Sdougb 546143731Sdougbunsigned int 547143731Sdougbdst_key_proto(const dst_key_t *key); 548143731Sdougb 549143731Sdougbunsigned int 550143731Sdougbdst_key_alg(const dst_key_t *key); 551143731Sdougb 552143731Sdougbisc_uint32_t 553143731Sdougbdst_key_flags(const dst_key_t *key); 554143731Sdougb 555143731Sdougbdns_keytag_t 556143731Sdougbdst_key_id(const dst_key_t *key); 557143731Sdougb 558143731Sdougbdns_rdataclass_t 559143731Sdougbdst_key_class(const dst_key_t *key); 560143731Sdougb 561143731Sdougbisc_boolean_t 562143731Sdougbdst_key_isprivate(const dst_key_t *key); 563143731Sdougb 564143731Sdougbisc_boolean_t 565143731Sdougbdst_key_iszonekey(const dst_key_t *key); 566143731Sdougb 567143731Sdougbisc_boolean_t 568143731Sdougbdst_key_isnullkey(const dst_key_t *key); 569143731Sdougb 570143731Sdougbisc_result_t 571143731Sdougbdst_key_buildfilename(const dst_key_t *key, int type, 572143731Sdougb const char *directory, isc_buffer_t *out); 573170222Sdougb/*%< 574143731Sdougb * Generates the filename used by dst to store the specified key. 575143731Sdougb * If directory is NULL, the current directory is assumed. 576143731Sdougb * 577143731Sdougb * Requires: 578170222Sdougb *\li "key" is a valid key 579170222Sdougb *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. 580170222Sdougb *\li "out" is a valid buffer 581143731Sdougb * 582143731Sdougb * Ensures: 583170222Sdougb *\li the file name will be written to "out", and the used pointer will 584143731Sdougb * be advanced. 585143731Sdougb */ 586143731Sdougb 587143731Sdougbisc_result_t 588143731Sdougbdst_key_sigsize(const dst_key_t *key, unsigned int *n); 589170222Sdougb/*%< 590143731Sdougb * Computes the size of a signature generated by the given key. 591143731Sdougb * 592143731Sdougb * Requires: 593170222Sdougb *\li "key" is a valid key. 594170222Sdougb *\li "n" is not NULL 595143731Sdougb * 596143731Sdougb * Returns: 597170222Sdougb *\li #ISC_R_SUCCESS 598170222Sdougb *\li DST_R_UNSUPPORTEDALG 599143731Sdougb * 600143731Sdougb * Ensures: 601170222Sdougb *\li "n" stores the size of a generated signature 602143731Sdougb */ 603143731Sdougb 604143731Sdougbisc_result_t 605143731Sdougbdst_key_secretsize(const dst_key_t *key, unsigned int *n); 606170222Sdougb/*%< 607143731Sdougb * Computes the size of a shared secret generated by the given key. 608143731Sdougb * 609143731Sdougb * Requires: 610170222Sdougb *\li "key" is a valid key. 611170222Sdougb *\li "n" is not NULL 612143731Sdougb * 613143731Sdougb * Returns: 614170222Sdougb *\li #ISC_R_SUCCESS 615170222Sdougb *\li DST_R_UNSUPPORTEDALG 616143731Sdougb * 617143731Sdougb * Ensures: 618170222Sdougb *\li "n" stores the size of a generated shared secret 619143731Sdougb */ 620143731Sdougb 621143731Sdougbisc_uint16_t 622143731Sdougbdst_region_computeid(const isc_region_t *source, unsigned int alg); 623170222Sdougb/*%< 624143731Sdougb * Computes the key id of the key stored in the provided region with the 625143731Sdougb * given algorithm. 626143731Sdougb * 627143731Sdougb * Requires: 628170222Sdougb *\li "source" contains a valid, non-NULL region. 629143731Sdougb * 630143731Sdougb * Returns: 631170222Sdougb *\li the key id 632143731Sdougb */ 633143731Sdougb 634170222Sdougbisc_uint16_t 635170222Sdougbdst_key_getbits(const dst_key_t *key); 636170222Sdougb/* 637170222Sdougb * Get the number of digest bits required (0 == MAX). 638170222Sdougb * 639170222Sdougb * Requires: 640170222Sdougb * "key" is a valid key. 641170222Sdougb */ 642170222Sdougb 643170222Sdougbvoid 644170222Sdougbdst_key_setbits(dst_key_t *key, isc_uint16_t bits); 645170222Sdougb/* 646170222Sdougb * Set the number of digest bits required (0 == MAX). 647170222Sdougb * 648170222Sdougb * Requires: 649170222Sdougb * "key" is a valid key. 650170222Sdougb */ 651170222Sdougb 652143731SdougbISC_LANG_ENDDECLS 653143731Sdougb 654143731Sdougb#endif /* DST_DST_H */ 655