contrib/ldns/ldns/keys.h

   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 */