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