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 LDNS_ED25519 = 15, /* RFC 8080 */ 59 LDNS_ED448 = 16, /* RFC 8080 */ 60 LDNS_INDIRECT = 252, 61 LDNS_PRIVATEDNS = 253, 62 LDNS_PRIVATEOID = 254 63 }; 64 typedef enum ldns_enum_algorithm ldns_algorithm; 65 66 /** 67 * Hashing algorithms used in the DS record 68 */ 69 enum ldns_enum_hash 70 { 71 LDNS_SHA1 = 1, /* RFC 4034 */ 72 LDNS_SHA256 = 2, /* RFC 4509 */ 73 LDNS_HASH_GOST = 3, /* RFC 5933 */ 74 LDNS_SHA384 = 4 /* RFC 6605 */ 75 }; 76 typedef enum ldns_enum_hash ldns_hash; 77 78 /** 79 * Algorithms used in dns for signing 80 */ 81 enum ldns_enum_signing_algorithm 82 { 83 LDNS_SIGN_RSAMD5 = LDNS_RSAMD5, 84 LDNS_SIGN_RSASHA1 = LDNS_RSASHA1, 85 #if LDNS_BUILD_CONFIG_USE_DSA 86 LDNS_SIGN_DSA = LDNS_DSA, 87 #endif /* LDNS_BUILD_CONFIG_USE_DSA */ 88 LDNS_SIGN_RSASHA1_NSEC3 = LDNS_RSASHA1_NSEC3, 89 LDNS_SIGN_RSASHA256 = LDNS_RSASHA256, 90 LDNS_SIGN_RSASHA512 = LDNS_RSASHA512, 91 #if LDNS_BUILD_CONFIG_USE_DSA 92 LDNS_SIGN_DSA_NSEC3 = LDNS_DSA_NSEC3, 93 #endif /* LDNS_BUILD_CONFIG_USE_DSA */ 94 LDNS_SIGN_ECC_GOST = LDNS_ECC_GOST, 95 LDNS_SIGN_ECDSAP256SHA256 = LDNS_ECDSAP256SHA256, 96 LDNS_SIGN_ECDSAP384SHA384 = LDNS_ECDSAP384SHA384, 97 #if LDNS_BUILD_CONFIG_USE_ED25519 98 LDNS_SIGN_ED25519 = LDNS_ED25519, 99 #endif /* LDNS_BUILD_CONFIG_USE_ED25519 */ 100 #if LDNS_BUILD_CONFIG_USE_ED448 101 LDNS_SIGN_ED448 = LDNS_ED448, 102 #endif /* LDNS_BUILD_CONFIG_USE_ED448 */ 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 LDNS_SIGN_HMACSHA224 = 162, /* ditto */ 107 LDNS_SIGN_HMACSHA384 = 164, /* ditto */ 108 LDNS_SIGN_HMACSHA512 = 165 /* ditto */ 109 }; 110 typedef enum ldns_enum_signing_algorithm ldns_signing_algorithm; 111 112 /** 113 * General key structure, can contain all types of keys that 114 * are used in DNSSEC. Mostly used to store private keys, since 115 * public keys can also be stored in a \ref ldns_rr with type 116 * \ref LDNS_RR_TYPE_DNSKEY. 117 * 118 * This structure can also store some variables that influence the 119 * signatures generated by signing with this key, for instance the 120 * inception date. 121 */ 122 struct ldns_struct_key { 123 ldns_signing_algorithm _alg; 124 /** Whether to use this key when signing */ 125 bool _use; 126 /** Storage pointers for the types of keys supported */ 127 /* TODO remove unions? */ 128 struct { 129 #if LDNS_BUILD_CONFIG_HAVE_SSL 130 #ifndef S_SPLINT_S 131 /* The key can be an OpenSSL EVP Key 132 */ 133 EVP_PKEY *key; 134 #endif 135 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 136 /** 137 * The key can be an HMAC key 138 */ 139 struct { 140 unsigned char *key; 141 size_t size; 142 } hmac; 143 /** the key structure can also just point to some external 144 * key data 145 */ 146 void *external_key; 147 } _key; 148 /** Depending on the key we can have extra data */ 149 union { 150 /** Some values that influence generated signatures */ 151 struct { 152 /** The TTL of the rrset that is currently signed */ 153 uint32_t orig_ttl; 154 /** The inception date of signatures made with this key. */ 155 uint32_t inception; 156 /** The expiration date of signatures made with this key. */ 157 uint32_t expiration; 158 /** The keytag of this key. */ 159 uint16_t keytag; 160 /** The dnssec key flags as specified in RFC4035, like ZSK and KSK */ 161 uint16_t flags; 162 } dnssec; 163 } _extra; 164 /** Owner name of the key */ 165 ldns_rdf *_pubkey_owner; 166 }; 167 typedef struct ldns_struct_key ldns_key; 168 169 /** 170 * Same as rr_list, but now for keys 171 */ 172 struct ldns_struct_key_list 173 { 174 size_t _key_count; 175 ldns_key **_keys; 176 }; 177 typedef struct ldns_struct_key_list ldns_key_list; 178 179 180 /** 181 * Creates a new empty key list 182 * \return a new ldns_key_list structure pointer 183 */ 184 ldns_key_list *ldns_key_list_new(void); 185 186 /** 187 * Creates a new empty key structure 188 * \return a new ldns_key * structure 189 */ 190 ldns_key *ldns_key_new(void); 191 192 /** 193 * Creates a new key based on the algorithm 194 * 195 * \param[in] a The algorithm to use 196 * \param[in] size the number of bytes for the keysize 197 * \return a new ldns_key structure with the key 198 */ 199 ldns_key *ldns_key_new_frm_algorithm(ldns_signing_algorithm a, uint16_t size); 200 201 /** 202 * Creates a new priv key based on the 203 * contents of the file pointed by fp. 204 * 205 * The file should be in Private-key-format v1.x. 206 * 207 * \param[out] k the new ldns_key structure 208 * \param[in] fp the file pointer to use 209 * \return an error or LDNS_STATUS_OK 210 */ 211 ldns_status ldns_key_new_frm_fp(ldns_key **k, FILE *fp); 212 213 /** 214 * Creates a new private key based on the 215 * contents of the file pointed by fp 216 * 217 * The file should be in Private-key-format v1.x. 218 * 219 * \param[out] k the new ldns_key structure 220 * \param[in] fp the file pointer to use 221 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes) 222 * \return an error or LDNS_STATUS_OK 223 */ 224 ldns_status ldns_key_new_frm_fp_l(ldns_key **k, FILE *fp, int *line_nr); 225 226 #if LDNS_BUILD_CONFIG_HAVE_SSL 227 /** 228 * Read the key with the given id from the given engine and store it 229 * in the given ldns_key structure. The algorithm type is set 230 * 231 * \param[out] key the new ldns_key structure 232 * \param[in] e the engine from which to read the key 233 * \param[in] key_id the id of the key with which to lookup the key in the engine 234 * \param[in] a the algorithm to set for this key 235 * \return an error or LDNS_STATUS_OK 236 */ 237 ldns_status ldns_key_new_frm_engine(ldns_key **key, ENGINE *e, char *key_id, ldns_algorithm a); 238 239 240 /** 241 * frm_fp helper function. This function parses the 242 * remainder of the (RSA) priv. key file generated from bind9 243 * \param[in] fp the file to parse 244 * \return NULL on failure otherwise a RSA structure 245 */ 246 RSA *ldns_key_new_frm_fp_rsa(FILE *fp); 247 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 257 258 # if LDNS_BUILD_CONFIG_USE_DSA 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 267 /** 268 * frm_fp helper function. This function parses the 269 * remainder of the (DSA) priv. key file 270 * \param[in] fp the file to parse 271 * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes) 272 * \return NULL on failure otherwise a RSA structure 273 */ 274 DSA *ldns_key_new_frm_fp_dsa_l(FILE *fp, int *line_nr); 275 # endif /* LDNS_BUILD_CONFIG_USE_DSA */ 276 277 /** 278 * frm_fp helper function. This function parses the 279 * remainder of the (HMAC-MD5) key file 280 * This function allocated a buffer that needs to be freed 281 * \param[in] fp the file to parse 282 * \param[out] hmac_size the number of bits in the resulting buffer 283 * \return NULL on failure otherwise a newly allocated char buffer 284 */ 285 unsigned char *ldns_key_new_frm_fp_hmac(FILE *fp, size_t *hmac_size); 286 287 /** 288 * frm_fp helper function. This function parses the 289 * remainder of the (HMAC-MD5) key file 290 * This function allocated a buffer that needs to be freed 291 * \param[in] fp the file to parse 292 * \param[in] line_nr pointer to an integer containing the current line number (for error reporting purposes) 293 * \param[out] hmac_size the number of bits in the resulting buffer 294 * \return NULL on failure otherwise a newly allocated char buffer 295 */ 296 unsigned char *ldns_key_new_frm_fp_hmac_l(FILE *fp, int *line_nr, size_t *hmac_size); 297 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 298 299 /* access write functions */ 300 /** 301 * Set the key's algorithm 302 * \param[in] k the key 303 * \param[in] l the algorithm 304 */ 305 void ldns_key_set_algorithm(ldns_key *k, ldns_signing_algorithm l); 306 307 #if LDNS_BUILD_CONFIG_HAVE_SSL 308 /** 309 * Set the key's evp key 310 * \param[in] k the key 311 * \param[in] e the evp key 312 */ 313 void ldns_key_set_evp_key(ldns_key *k, EVP_PKEY *e); 314 315 /** 316 * Set the key's rsa data. 317 * The rsa data should be freed by the user. 318 * \param[in] k the key 319 * \param[in] r the rsa data 320 */ 321 void ldns_key_set_rsa_key(ldns_key *k, RSA *r); 322 323 # if LDNS_BUILD_CONFIG_USE_DSA 324 /** 325 * Set the key's dsa data 326 * The dsa data should be freed by the user. 327 * \param[in] k the key 328 * \param[in] d the dsa data 329 */ 330 void ldns_key_set_dsa_key(ldns_key *k, DSA *d); 331 # endif /* LDNS_BUILD_CONFIG_USE_DSA */ 332 333 /** 334 * Assign the key's rsa data 335 * The rsa data will be freed automatically when the key is freed. 336 * \param[in] k the key 337 * \param[in] r the rsa data 338 */ 339 void ldns_key_assign_rsa_key(ldns_key *k, RSA *r); 340 341 # if LDNS_BUILD_CONFIG_USE_DSA 342 /** 343 * Assign the key's dsa data 344 * The dsa data will be freed automatically when the key is freed. 345 * \param[in] k the key 346 * \param[in] d the dsa data 347 */ 348 void ldns_key_assign_dsa_key(ldns_key *k, DSA *d); 349 # endif /* LDNS_BUILD_CONFIG_USE_DSA */ 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 count 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 467 # if LDNS_BUILD_CONFIG_USE_DSA 468 /** 469 * returns the (openssl) DSA struct contained in the key 470 */ 471 DSA *ldns_key_dsa_key(const ldns_key *k); 472 # endif /* LDNS_BUILD_CONFIG_USE_DSA */ 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 expiration 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