1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: dst.h,v 1.10 2020/02/23 23:40:21 jsg Exp $ */ 18 19 #ifndef DST_DST_H 20 #define DST_DST_H 1 21 22 /*! \file dst/dst.h */ 23 24 #include <dns/types.h> 25 #include <dns/log.h> 26 #include <dns/name.h> 27 #include <dns/secalg.h> 28 #include <dns/ds.h> 29 30 /*** 31 *** Types 32 ***/ 33 34 /*% 35 * The dst_key structure is opaque. Applications should use the accessor 36 * functions provided to retrieve key attributes. If an application needs 37 * to set attributes, new accessor functions will be written. 38 */ 39 40 typedef struct dst_key dst_key_t; 41 typedef struct dst_context dst_context_t; 42 43 /* DST algorithm codes */ 44 #define DST_ALG_UNKNOWN 0 45 #define DST_ALG_RSAMD5 1 46 #define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ 47 #define DST_ALG_HMACSHA1 161 /* XXXMPA */ 48 #define DST_ALG_HMACSHA224 162 /* XXXMPA */ 49 #define DST_ALG_HMACSHA256 163 /* XXXMPA */ 50 #define DST_ALG_HMACSHA384 164 /* XXXMPA */ 51 #define DST_ALG_HMACSHA512 165 /* XXXMPA */ 52 #define DST_MAX_ALGS 255 53 54 /*% A buffer of this size is large enough to hold any key */ 55 #define DST_KEY_MAXSIZE 1280 56 57 /*% 58 * A buffer of this size is large enough to hold the textual representation 59 * of any key 60 */ 61 #define DST_KEY_MAXTEXTSIZE 2048 62 63 /*% 'Type' for dst_read_key() */ 64 #define DST_TYPE_KEY 0x1000000 /* KEY key */ 65 #define DST_TYPE_PRIVATE 0x2000000 66 #define DST_TYPE_PUBLIC 0x4000000 67 68 /* Key timing metadata definitions */ 69 #define DST_TIME_CREATED 0 70 #define DST_TIME_PUBLISH 1 71 #define DST_TIME_ACTIVATE 2 72 #define DST_TIME_REVOKE 3 73 #define DST_TIME_INACTIVE 4 74 #define DST_TIME_DELETE 5 75 #define DST_TIME_DSPUBLISH 6 76 #define DST_MAX_TIMES 6 77 78 /* Numeric metadata definitions */ 79 #define DST_NUM_PREDECESSOR 0 80 #define DST_NUM_SUCCESSOR 1 81 #define DST_NUM_MAXTTL 2 82 #define DST_NUM_ROLLPERIOD 3 83 #define DST_MAX_NUMERIC 3 84 85 /* 86 * Current format version number of the private key parser. 87 * 88 * When parsing a key file with the same major number but a higher minor 89 * number, the key parser will ignore any fields it does not recognize. 90 * Thus, DST_MINOR_VERSION should be incremented whenever new 91 * fields are added to the private key file (such as new metadata). 92 * 93 * When rewriting these keys, those fields will be dropped, and the 94 * format version set back to the current one.. 95 * 96 * When a key is seen with a higher major number, the key parser will 97 * reject it as invalid. Thus, DST_MAJOR_VERSION should be incremented 98 * and DST_MINOR_VERSION set to zero whenever there is a format change 99 * which is not backward compatible to previous versions of the dst_key 100 * parser, such as change in the syntax of an existing field, the removal 101 * of a currently mandatory field, or a new field added which would 102 * alter the functioning of the key if it were absent. 103 */ 104 #define DST_MAJOR_VERSION 1 105 #define DST_MINOR_VERSION 3 106 107 /*** 108 *** Functions 109 ***/ 110 111 isc_result_t 112 dst_lib_init(void); 113 /*%< 114 * Initializes the DST subsystem. 115 * 116 * Requires: 117 * 118 * Returns: 119 * \li ISC_R_SUCCESS 120 * \li ISC_R_NOMEMORY 121 * \li DST_R_NOENGINE 122 * 123 * Ensures: 124 * \li DST is properly initialized. 125 */ 126 127 void 128 dst_lib_destroy(void); 129 /*%< 130 * Releases all resources allocated by DST. 131 */ 132 133 isc_boolean_t 134 dst_algorithm_supported(unsigned int alg); 135 /*%< 136 * Checks that a given algorithm is supported by DST. 137 * 138 * Returns: 139 * \li ISC_TRUE 140 * \li ISC_FALSE 141 */ 142 143 isc_result_t 144 dst_context_create3(dst_key_t *key, 145 isc_logcategory_t *category, isc_boolean_t useforsigning, 146 dst_context_t **dctxp); 147 148 /*%< 149 * Creates a context to be used for a sign or verify operation. 150 * 151 * Requires: 152 * \li "key" is a valid key. 153 * \li dctxp != NULL && *dctxp == NULL 154 * 155 * Returns: 156 * \li ISC_R_SUCCESS 157 * \li ISC_R_NOMEMORY 158 * 159 * Ensures: 160 * \li *dctxp will contain a usable context. 161 */ 162 163 void 164 dst_context_destroy(dst_context_t **dctxp); 165 /*%< 166 * Destroys all memory associated with a context. 167 * 168 * Requires: 169 * \li *dctxp != NULL && *dctxp == NULL 170 * 171 * Ensures: 172 * \li *dctxp == NULL 173 */ 174 175 isc_result_t 176 dst_context_adddata(dst_context_t *dctx, const isc_region_t *data); 177 /*%< 178 * Incrementally adds data to the context to be used in a sign or verify 179 * operation. 180 * 181 * Requires: 182 * \li "dctx" is a valid context 183 * \li "data" is a valid region 184 * 185 * Returns: 186 * \li ISC_R_SUCCESS 187 * \li DST_R_SIGNFAILURE 188 * \li all other errors indicate failure 189 */ 190 191 isc_result_t 192 dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); 193 /*%< 194 * Computes a signature using the data and key stored in the context. 195 * 196 * Requires: 197 * \li "dctx" is a valid context. 198 * \li "sig" is a valid buffer. 199 * 200 * Returns: 201 * \li ISC_R_SUCCESS 202 * \li DST_R_VERIFYFAILURE 203 * \li all other errors indicate failure 204 * 205 * Ensures: 206 * \li "sig" will contain the signature 207 */ 208 209 isc_result_t 210 dst_context_verify(dst_context_t *dctx, isc_region_t *sig); 211 212 isc_result_t 213 dst_key_todns(const dst_key_t *key, isc_buffer_t *target); 214 /*%< 215 * Converts a DST key into a DNS KEY record. 216 * 217 * Requires: 218 * \li "key" is a valid key. 219 * \li "target" is a valid buffer. There must be at least 4 bytes unused. 220 * 221 * Returns: 222 * \li ISC_R_SUCCESS 223 * \li any other result indicates failure 224 * 225 * Ensures: 226 * \li If successful, the used pointer in 'target' is advanced by at least 4. 227 */ 228 229 isc_result_t 230 dst_key_frombuffer(unsigned int alg, unsigned int flags, unsigned int protocol, 231 isc_buffer_t *source, dst_key_t **keyp); 232 /*%< 233 * Converts a buffer containing DNS KEY RDATA into a DST key. 234 * 235 * Requires: 236 *\li "name" is a valid absolute dns name. 237 *\li "alg" is a supported key algorithm. 238 *\li "source" is a valid buffer. 239 *\li "keyp" is not NULL and "*keyp" is NULL. 240 * 241 * Returns: 242 *\li ISC_R_SUCCESS 243 * \li any other result indicates failure 244 * 245 * Ensures: 246 *\li If successful, *keyp will contain a valid key, and the consumed 247 * pointer in source will be advanced. 248 */ 249 250 void 251 dst_key_attach(dst_key_t *source, dst_key_t **target); 252 /* 253 * Attach to a existing key increasing the reference count. 254 * 255 * Requires: 256 *\li 'source' to be a valid key. 257 *\li 'target' to be non-NULL and '*target' to be NULL. 258 */ 259 260 void 261 dst_key_free(dst_key_t **keyp); 262 /*%< 263 * Decrement the key's reference counter and, when it reaches zero, 264 * release all memory associated with the key. 265 * 266 * Requires: 267 *\li "keyp" is not NULL and "*keyp" is a valid key. 268 *\li reference counter greater than zero. 269 * 270 * Ensures: 271 *\li All memory associated with "*keyp" will be freed. 272 *\li *keyp == NULL 273 */ 274 275 /*%< 276 * Accessor functions to obtain key fields. 277 * 278 * Require: 279 *\li "key" is a valid key. 280 */ 281 unsigned int 282 dst_key_size(const dst_key_t *key); 283 284 unsigned int 285 dst_key_alg(const dst_key_t *key); 286 287 isc_result_t 288 dst_key_sigsize(const dst_key_t *key, unsigned int *n); 289 /*%< 290 * Computes the size of a signature generated by the given key. 291 * 292 * Requires: 293 *\li "key" is a valid key. 294 *\li "n" is not NULL 295 * 296 * Returns: 297 *\li #ISC_R_SUCCESS 298 *\li DST_R_UNSUPPORTEDALG 299 * 300 * Ensures: 301 *\li "n" stores the size of a generated signature 302 */ 303 304 uint16_t 305 dst_region_computeid(const isc_region_t *source, unsigned int alg); 306 /*%< 307 * Computes the (revoked) key id of the key stored in the provided 308 * region with the given algorithm. 309 * 310 * Requires: 311 *\li "source" contains a valid, non-NULL region. 312 * 313 * Returns: 314 *\li the key id 315 */ 316 317 uint16_t 318 dst_key_getbits(const dst_key_t *key); 319 /*%< 320 * Get the number of digest bits required (0 == MAX). 321 * 322 * Requires: 323 * "key" is a valid key. 324 */ 325 326 void 327 dst_key_setbits(dst_key_t *key, uint16_t bits); 328 /*%< 329 * Set the number of digest bits required (0 == MAX). 330 * 331 * Requires: 332 * "key" is a valid key. 333 */ 334 335 #endif /* DST_DST_H */ 336