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