1 /* 2 * 3 * keys.h 4 * 5 * priv key definitions 6 * 7 * a Net::DNS like library for C 8 * 9 * (c) NLnet Labs, 2005-2006 10 * 11 * See the file LICENSE for the license 12 */ 13 14 /** 15 * \file 16 * 17 * Addendum to \ref dnssec.h, this module contains key and algorithm definitions and functions. 18 */ 19 20 21 #ifndef LDNS_KEYS_H 22 #define LDNS_KEYS_H 23 24 #ifdef HAVE_SSL 25 #include <openssl/ssl.h> 26 #endif /* HAVE_SSL */ 27 #include <ldns/dnssec.h> 28 #include <ldns/util.h> 29 #include <errno.h> 30 31 extern ldns_lookup_table ldns_signing_algorithms[]; 32 33 #define LDNS_KEY_ZONE_KEY 0x0100 /* rfc 4034 */ 34 #define LDNS_KEY_SEP_KEY 0x0001 /* rfc 4034 */ 35 #define LDNS_KEY_REVOKE_KEY 0x0080 /* rfc 5011 */ 36 37 /** 38 * Algorithms used in dns 39 */ 40 enum ldns_enum_algorithm 41 { 42 LDNS_RSAMD5 = 1, /* RFC 4034,4035 */ 43 LDNS_DH = 2, 44 LDNS_DSA = 3, 45 LDNS_ECC = 4, 46 LDNS_RSASHA1 = 5, 47 LDNS_DSA_NSEC3 = 6, 48 LDNS_RSASHA1_NSEC3 = 7, 49 LDNS_RSASHA256 = 8, /* RFC 5702 */ 50 LDNS_RSASHA512 = 10, /* RFC 5702 */ 51 LDNS_GOST = 249, /* not official */ 52 LDNS_INDIRECT = 252, 53 LDNS_PRIVATEDNS = 253, 54 LDNS_PRIVATEOID = 254 55 }; 56 typedef enum ldns_enum_algorithm ldns_algorithm; 57 58 /** 59 * Hashing algorithms used in the DS record 60 */ 61 enum ldns_enum_hash 62 { 63 LDNS_SHA1 = 1, /* RFC 4034 */ 64 LDNS_SHA256 = 2, /* RFC 4509 */ 65 LDNS_HASH_GOST94 = 203 /* not official */ 66 }; 67 typedef enum ldns_enum_hash ldns_hash; 68 69 /** 70 * Algorithms used in dns for signing 71 */ 72 enum ldns_enum_signing_algorithm 73 { 74 LDNS_SIGN_RSAMD5 = LDNS_RSAMD5, 75 LDNS_SIGN_RSASHA1 = LDNS_RSASHA1, 76 LDNS_SIGN_DSA = LDNS_DSA, 77 LDNS_SIGN_RSASHA1_NSEC3 = LDNS_RSASHA1_NSEC3, 78 LDNS_SIGN_RSASHA256 = LDNS_RSASHA256, 79 LDNS_SIGN_RSASHA512 = LDNS_RSASHA512, 80 LDNS_SIGN_DSA_NSEC3 = LDNS_DSA_NSEC3, 81 LDNS_SIGN_GOST = LDNS_GOST, 82 LDNS_SIGN_HMACMD5 = 157, /* not official! This type is for TSIG, not DNSSEC */ 83 LDNS_SIGN_HMACSHA1 = 158, /* not official! This type is for TSIG, not DNSSEC */ 84 LDNS_SIGN_HMACSHA256 = 159 /* ditto */ 85 }; 86 typedef enum ldns_enum_signing_algorithm ldns_signing_algorithm; 87 88 /** 89 * General key structure, can contain all types of keys that 90 * are used in DNSSEC. Mostly used to store private keys, since 91 * public keys can also be stored in a \ref ldns_rr with type 92 * \ref LDNS_RR_TYPE_DNSKEY. 93 * 94 * This structure can also store some variables that influence the 95 * signatures generated by signing with this key, for instance the 96 * inception date. 97 */ 98 struct ldns_struct_key { 99 ldns_signing_algorithm _alg; 100 /** Whether to use this key when signing */ 101 bool _use; 102 /** Storage pointers for the types of keys supported */ 103 /* TODO remove unions? */ 104 struct { 105 #ifdef HAVE_SSL 106 #ifndef S_SPLINT_S 107 /* The key can be an OpenSSL EVP Key 108 */ 109 EVP_PKEY *key; 110 #endif 111 #endif /* HAVE_SSL */ 112 /** 113 * The key can be an HMAC key 114 */ 115 struct { 116 unsigned char *key; 117 size_t size; 118 } hmac; 119 /** the key structure can also just point to some external 120 * key data 121 */ 122 void *external_key; 123 } _key; 124 /** Depending on the key we can have extra data */ 125 union { 126 /** Some values that influence generated signatures */ 127 struct { 128 /** The TTL of the rrset that is currently signed */ 129 uint32_t orig_ttl; 130 /** The inception date of signatures made with this key. */ 131 uint32_t inception; 132 /** The expiration date of signatures made with this key. */ 133 uint32_t expiration; 134 /** The keytag of this key. */ 135 uint16_t keytag; 136 /** The dnssec key flags as specified in RFC4035, like ZSK and KSK */ 137 uint16_t flags; 138 } dnssec; 139 } _extra; 140 /** Owner name of the key */ 141 ldns_rdf *_pubkey_owner; 142 }; 143 typedef struct ldns_struct_key ldns_key; 144 145 /** 146 * Same as rr_list, but now for keys 147 */ 148 struct ldns_struct_key_list 149 { 150 size_t _key_count; 151 ldns_key **_keys; 152 }; 153 typedef struct ldns_struct_key_list ldns_key_list; 154 155 156 /** 157 * Creates a new empty key list 158 * \return a new ldns_key_list structure pointer 159 */ 160 ldns_key_list *ldns_key_list_new(); 161 162 /** 163 * Creates a new empty key structure 164 * \return a new ldns_key * structure 165 */ 166 ldns_key *ldns_key_new(); 167 168 /** 169 * Creates a new key based on the algorithm 170 * 171 * \param[in] a The algorithm to use 172 * \param[in] size the number of bytes for the keysize 173 * \return a new ldns_key structure with the key 174 */ 175 ldns_key *ldns_key_new_frm_algorithm(ldns_signing_algorithm a, uint16_t size); 176 177 /** 178 * Creates a new priv key based on the 179 * contents of the file pointed by fp. 180 * 181 * The file should be in Private-key-format v1.2. 182 * 183 * \param[out] k the new ldns_key structure 184 * \param[in] fp the file pointer to use 185 * \return an error or LDNS_STATUS_OK 186 */ 187 ldns_status ldns_key_new_frm_fp(ldns_key **k, FILE *fp); 188 189 /** 190 * Creates a new private key based on the 191 * contents of the file pointed by fp 192 * 193 * The file should be in Private-key-format v1.2. 194 * 195 * \param[out] k the new ldns_key structure 196 * \param[in] fp the file pointer to use 197 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes) 198 * \return an error or LDNS_STATUS_OK 199 */ 200 ldns_status ldns_key_new_frm_fp_l(ldns_key **k, FILE *fp, int *line_nr); 201 202 #ifdef HAVE_SSL 203 /** 204 * Read the key with the given id from the given engine and store it 205 * in the given ldns_key structure. The algorithm type is set 206 */ 207 ldns_status ldns_key_new_frm_engine(ldns_key **key, ENGINE *e, char *key_id, ldns_algorithm); 208 209 210 /** 211 * frm_fp helper function. This function parses the 212 * remainder of the (RSA) priv. key file generated from bind9 213 * \param[in] fp the file to parse 214 * \return NULL on failure otherwise a RSA structure 215 */ 216 RSA *ldns_key_new_frm_fp_rsa(FILE *fp); 217 #endif /* HAVE_SSL */ 218 219 #ifdef HAVE_SSL 220 /** 221 * frm_fp helper function. This function parses the 222 * remainder of the (RSA) priv. key file generated from bind9 223 * \param[in] fp the file to parse 224 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes) 225 * \return NULL on failure otherwise a RSA structure 226 */ 227 RSA *ldns_key_new_frm_fp_rsa_l(FILE *fp, int *line_nr); 228 #endif /* HAVE_SSL */ 229 230 #ifdef HAVE_SSL 231 /** 232 * frm_fp helper function. This function parses the 233 * remainder of the (DSA) priv. key file 234 * \param[in] fp the file to parse 235 * \return NULL on failure otherwise a RSA structure 236 */ 237 DSA *ldns_key_new_frm_fp_dsa(FILE *fp); 238 #endif /* HAVE_SSL */ 239 240 #ifdef HAVE_SSL 241 /** 242 * frm_fp helper function. This function parses the 243 * remainder of the (DSA) priv. key file 244 * \param[in] fp the file to parse 245 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes) 246 * \return NULL on failure otherwise a RSA structure 247 */ 248 DSA *ldns_key_new_frm_fp_dsa_l(FILE *fp, int *line_nr); 249 #endif /* HAVE_SSL */ 250 251 #ifdef HAVE_SSL 252 /** 253 * frm_fp helper function. This function parses the 254 * remainder of the (HMAC-MD5) key file 255 * This function allocated a buffer that needs to be freed 256 * \param[in] fp the file to parse 257 * \param[out] hmac_size the number of bits in the resulting buffer 258 * \return NULL on failure otherwise a newly allocated char buffer 259 */ 260 unsigned char *ldns_key_new_frm_fp_hmac(FILE *fp, size_t *hmac_size); 261 #endif 262 263 #ifdef HAVE_SSL 264 /** 265 * frm_fp helper function. This function parses the 266 * remainder of the (HMAC-MD5) key file 267 * This function allocated a buffer that needs to be freed 268 * \param[in] fp the file to parse 269 * \param[in] line_nr pointer to an integer containing the current line number (for error reporting purposes) 270 * \param[out] hmac_size the number of bits in the resulting buffer 271 * \return NULL on failure otherwise a newly allocated char buffer 272 */ 273 unsigned char *ldns_key_new_frm_fp_hmac_l(FILE *fp, int *line_nr, size_t *hmac_size); 274 #endif /* HAVE_SSL */ 275 276 /* acces write functions */ 277 /** 278 * Set the key's algorithm 279 * \param[in] k the key 280 * \param[in] l the algorithm 281 */ 282 void ldns_key_set_algorithm(ldns_key *k, ldns_signing_algorithm l); 283 #ifdef HAVE_SSL 284 /** 285 * Set the key's evp key 286 * \param[in] k the key 287 * \param[in] e the evp key 288 */ 289 void ldns_key_set_evp_key(ldns_key *k, EVP_PKEY *e); 290 291 /** 292 * Set the key's rsa data 293 * \param[in] k the key 294 * \param[in] r the rsa data 295 */ 296 void ldns_key_set_rsa_key(ldns_key *k, RSA *r); 297 /** 298 * Set the key's dsa data 299 * \param[in] k the key 300 * \param[in] d the dsa data 301 */ 302 void ldns_key_set_dsa_key(ldns_key *k, DSA *d); 303 304 /** 305 * Get the PKEY id for GOST, loads GOST into openssl as a side effect. 306 * Only available if GOST is compiled into the library and openssl. 307 * \return the gost id for EVP_CTX creation. 308 */ 309 int ldns_key_EVP_load_gost_id(void); 310 #endif /* HAVE_SSL */ 311 312 /** 313 * Set the key's hmac data 314 * \param[in] k the key 315 * \param[in] hmac the raw key data 316 */ 317 void ldns_key_set_hmac_key(ldns_key *k, unsigned char *hmac); 318 319 /** 320 * Set the key id data. This is used if the key points to 321 * some externally stored key data 322 * 323 * Only the pointer is set, the data there is not copied, 324 * and must be freed manually; ldns_key_deep_free() does 325 * *not* free this data 326 * \param[in] key the key 327 * \param[in] external_key key id data 328 */ 329 void ldns_key_set_external_key(ldns_key *key, void *external_key); 330 331 /** 332 * Set the key's hmac size 333 * \param[in] k the key 334 * \param[in] hmac_size the size of the hmac data 335 */ 336 void ldns_key_set_hmac_size(ldns_key *k, size_t hmac_size); 337 /** 338 * Set the key's original ttl 339 * \param[in] k the key 340 * \param[in] t the ttl 341 */ 342 void ldns_key_set_origttl(ldns_key *k, uint32_t t); 343 /** 344 * Set the key's inception date (seconds after epoch) 345 * \param[in] k the key 346 * \param[in] i the inception 347 */ 348 void ldns_key_set_inception(ldns_key *k, uint32_t i); 349 /** 350 * Set the key's expiration date (seconds after epoch) 351 * \param[in] k the key 352 * \param[in] e the expiration 353 */ 354 void ldns_key_set_expiration(ldns_key *k, uint32_t e); 355 /** 356 * Set the key's pubkey owner 357 * \param[in] k the key 358 * \param[in] r the owner 359 */ 360 void ldns_key_set_pubkey_owner(ldns_key *k, ldns_rdf *r); 361 /** 362 * Set the key's key tag 363 * \param[in] k the key 364 * \param[in] tag the keytag 365 */ 366 void ldns_key_set_keytag(ldns_key *k, uint16_t tag); 367 /** 368 * Set the key's flags 369 * \param[in] k the key 370 * \param[in] flags the flags 371 */ 372 void ldns_key_set_flags(ldns_key *k, uint16_t flags); 373 /** 374 * Set the keylist's key count to count 375 * \param[in] key the key 376 * \param[in] count the cuont 377 */ 378 void ldns_key_list_set_key_count(ldns_key_list *key, size_t count); 379 380 /** 381 * pushes a key to a keylist 382 * \param[in] key_list the key_list to push to 383 * \param[in] key the key to push 384 * \return false on error, otherwise true 385 */ 386 bool ldns_key_list_push_key(ldns_key_list *key_list, ldns_key *key); 387 388 /** 389 * returns the number of keys in the key list 390 * \param[in] key_list the key_list 391 * \return the numbers of keys in the list 392 */ 393 size_t ldns_key_list_key_count(const ldns_key_list *key_list); 394 395 /** 396 * returns a pointer to the key in the list at the given position 397 * \param[in] key the key 398 * \param[in] nr the position in the list 399 * \return the key 400 */ 401 ldns_key *ldns_key_list_key(const ldns_key_list *key, size_t nr); 402 403 #ifdef HAVE_SSL 404 /** 405 * returns the (openssl) RSA struct contained in the key 406 * \param[in] k the key to look in 407 * \return the RSA * structure in the key 408 */ 409 RSA *ldns_key_rsa_key(const ldns_key *k); 410 /** 411 * returns the (openssl) EVP struct contained in the key 412 * \param[in] k the key to look in 413 * \return the RSA * structure in the key 414 */ 415 EVP_PKEY *ldns_key_evp_key(const ldns_key *k); 416 #endif /* HAVE_SSL */ 417 418 /** 419 * returns the (openssl) DSA struct contained in the key 420 */ 421 #ifdef HAVE_SSL 422 DSA *ldns_key_dsa_key(const ldns_key *k); 423 #endif /* HAVE_SSL */ 424 425 /** 426 * return the signing alg of the key 427 * \param[in] k the key 428 * \return the algorithm 429 */ 430 ldns_signing_algorithm ldns_key_algorithm(const ldns_key *k); 431 /** 432 * set the use flag 433 * \param[in] k the key 434 * \param[in] v the boolean value to set the _use field to 435 */ 436 void ldns_key_set_use(ldns_key *k, bool v); 437 /** 438 * return the use flag 439 * \param[in] k the key 440 * \return the boolean value of the _use field 441 */ 442 bool ldns_key_use(const ldns_key *k); 443 /** 444 * return the hmac key data 445 * \param[in] k the key 446 * \return the hmac key data 447 */ 448 unsigned char *ldns_key_hmac_key(const ldns_key *k); 449 /** 450 * return the key id key data 451 * \param[in] k the key 452 * \return the key id data 453 */ 454 void *ldns_key_external_key(const ldns_key *k); 455 /** 456 * return the hmac key size 457 * \param[in] k the key 458 * \return the hmac key size 459 */ 460 size_t ldns_key_hmac_size(const ldns_key *k); 461 /** 462 * return the original ttl of the key 463 * \param[in] k the key 464 * \return the original ttl 465 */ 466 uint32_t ldns_key_origttl(const ldns_key *k); 467 /** 468 * return the key's inception date 469 * \param[in] k the key 470 * \return the inception date 471 */ 472 uint32_t ldns_key_inception(const ldns_key *k); 473 /** 474 * return the key's expiration date 475 * \param[in] k the key 476 * \return the experiration date 477 */ 478 uint32_t ldns_key_expiration(const ldns_key *k); 479 /** 480 * return the keytag 481 * \param[in] k the key 482 * \return the keytag 483 */ 484 uint16_t ldns_key_keytag(const ldns_key *k); 485 /** 486 * return the public key's owner 487 * \param[in] k the key 488 * \return the owner 489 */ 490 ldns_rdf *ldns_key_pubkey_owner(const ldns_key *k); 491 /** 492 * Set the 'use' flag for all keys in the list 493 * \param[in] keys The key_list 494 * \param[in] v The value to set the use flags to 495 */ 496 void 497 ldns_key_list_set_use(ldns_key_list *keys, bool v); 498 499 /** 500 * return the flag of the key 501 * \param[in] k the key 502 * \return the flag 503 */ 504 uint16_t ldns_key_flags(const ldns_key *k); 505 506 /** 507 * pops the last rr from a keylist 508 * \param[in] key_list the rr_list to pop from 509 * \return NULL if nothing to pop. Otherwise the popped RR 510 */ 511 ldns_key *ldns_key_list_pop_key(ldns_key_list *key_list); 512 513 /** 514 * converts a ldns_key to a public key rr 515 * If the key data exists at an external point, the corresponding 516 * rdata field must still be added with ldns_rr_rdf_push() to the 517 * result rr of this function 518 * 519 * \param[in] k the ldns_key to convert 520 * \return ldns_rr representation of the key 521 */ 522 ldns_rr *ldns_key2rr(const ldns_key *k); 523 524 /** 525 * print a private key to the file ouput 526 * 527 * \param[in] output the FILE descriptor where to print to 528 * \param[in] k the ldns_key to print 529 */ 530 void ldns_key_print(FILE *output, const ldns_key *k); 531 532 /** 533 * frees a key structure, but not its internal data structures 534 * 535 * \param[in] key the key object to free 536 */ 537 void ldns_key_free(ldns_key *key); 538 539 /** 540 * frees a key structure and all its internal data structures, except 541 * the data set by ldns_key_set_external_key() 542 * 543 * \param[in] key the key object to free 544 */ 545 void ldns_key_deep_free(ldns_key *key); 546 547 /** 548 * Frees a key list structure 549 * \param[in] key_list the key list object to free 550 */ 551 void ldns_key_list_free(ldns_key_list *key_list); 552 553 /** 554 * Instantiates a DNSKEY or DS RR from file. 555 * \param[in] filename the file to read the record from 556 * \return the corresponding RR, or NULL if the parsing failed 557 */ 558 ldns_rr * ldns_read_anchor_file(const char *filename); 559 560 /** 561 * Returns the 'default base name' for key files; 562 * IE. K\<zone\>+\<alg\>+\<keytag\> 563 * (without the .key or .private) 564 * The memory for this is allocated by this function, 565 * and should be freed by the caller 566 * 567 * \param[in] key the key to get the file name from 568 * \returns A string containing the file base name 569 */ 570 char *ldns_key_get_file_base_name(ldns_key *key); 571 572 /** 573 * See if a key algorithm is supported 574 * \param[in] algo the signing algorithm number. 575 * \returns true if supported. 576 */ 577 int ldns_key_algo_supported(int algo); 578 579 #endif /* LDNS_KEYS_H */ 580