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