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