"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/lib/dns/include/dst/dst.h" (4 Sep 2020, 30498 Bytes) of package /linux/misc/dns/bind9/9.17.5/bind-9.17.5.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "dst.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 9.17.4_vs_9.17.5.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef DST_DST_H
   13 #define DST_DST_H 1
   14 
   15 /*! \file dst/dst.h */
   16 
   17 #include <inttypes.h>
   18 #include <stdbool.h>
   19 
   20 #include <isc/lang.h>
   21 #include <isc/stdtime.h>
   22 
   23 #include <dns/ds.h>
   24 #include <dns/dsdigest.h>
   25 #include <dns/log.h>
   26 #include <dns/name.h>
   27 #include <dns/secalg.h>
   28 #include <dns/types.h>
   29 
   30 #include <dst/gssapi.h>
   31 
   32 ISC_LANG_BEGINDECLS
   33 
   34 /***
   35  *** Types
   36  ***/
   37 
   38 /*%
   39  * The dst_key structure is opaque.  Applications should use the accessor
   40  * functions provided to retrieve key attributes.  If an application needs
   41  * to set attributes, new accessor functions will be written.
   42  */
   43 
   44 typedef struct dst_key     dst_key_t;
   45 typedef struct dst_context dst_context_t;
   46 
   47 /*%
   48  * Key states for the DNSSEC records related to a key: DNSKEY, RRSIG (ksk),
   49  * RRSIG (zsk), and DS.
   50  *
   51  * DST_KEY_STATE_HIDDEN:      Records of this type are not published in zone.
   52  *                            This may be because the key parts were never
   53  *                            introduced in the zone, or because the key has
   54  *                            retired and has no records of this type left in
   55  *                            the zone.
   56  * DST_KEY_STATE_RUMOURED:    Records of this type are published in zone, but
   57  *                            not long enough to ensure all resolvers know
   58  *                            about it.
   59  * DST_KEY_STATE_OMNIPRESENT: Records of this type are published in zone long
   60  *                            enough so that all resolvers that know about
   61  *                            these records, no longer have outdated data.
   62  * DST_KEY_STATE_UNRETENTIVE: Records of this type have been removed from the
   63  *                            zone, but there may be resolvers that still have
   64  *                            have predecessor records cached.  Note that RRSIG
   65  *                            records in this state may actually still be in the
   66  *                            zone because they are reused, but retired RRSIG
   67  *                            records will never be refreshed: A successor key
   68  *                            is used to create signatures.
   69  * DST_KEY_STATE_NA:          The state is not applicable for this record type.
   70  */
   71 typedef enum dst_key_state {
   72     DST_KEY_STATE_HIDDEN = 0,
   73     DST_KEY_STATE_RUMOURED = 1,
   74     DST_KEY_STATE_OMNIPRESENT = 2,
   75     DST_KEY_STATE_UNRETENTIVE = 3,
   76     DST_KEY_STATE_NA = 4
   77 } dst_key_state_t;
   78 
   79 /* DST algorithm codes */
   80 #define DST_ALG_UNKNOWN      0
   81 #define DST_ALG_RSA      1 /* Used for parsing RSASHA1, RSASHA256 and RSASHA512 */
   82 #define DST_ALG_RSAMD5       1
   83 #define DST_ALG_DH       2
   84 #define DST_ALG_DSA      3
   85 #define DST_ALG_ECC      4
   86 #define DST_ALG_RSASHA1      5
   87 #define DST_ALG_NSEC3DSA     6
   88 #define DST_ALG_NSEC3RSASHA1 7
   89 #define DST_ALG_RSASHA256    8
   90 #define DST_ALG_RSASHA512    10
   91 #define DST_ALG_ECCGOST      12
   92 #define DST_ALG_ECDSA256     13
   93 #define DST_ALG_ECDSA384     14
   94 #define DST_ALG_ED25519      15
   95 #define DST_ALG_ED448        16
   96 #define DST_ALG_HMACMD5      157
   97 #define DST_ALG_GSSAPI       160
   98 #define DST_ALG_HMACSHA1     161 /* XXXMPA */
   99 #define DST_ALG_HMACSHA224   162 /* XXXMPA */
  100 #define DST_ALG_HMACSHA256   163 /* XXXMPA */
  101 #define DST_ALG_HMACSHA384   164 /* XXXMPA */
  102 #define DST_ALG_HMACSHA512   165 /* XXXMPA */
  103 #define DST_ALG_INDIRECT     252
  104 #define DST_ALG_PRIVATE      254
  105 #define DST_MAX_ALGS         256
  106 
  107 /*% A buffer of this size is large enough to hold any key */
  108 #define DST_KEY_MAXSIZE 1280
  109 
  110 /*%
  111  * A buffer of this size is large enough to hold the textual representation
  112  * of any key
  113  */
  114 #define DST_KEY_MAXTEXTSIZE 2048
  115 
  116 /*% 'Type' for dst_read_key() */
  117 #define DST_TYPE_KEY     0x1000000 /* KEY key */
  118 #define DST_TYPE_PRIVATE 0x2000000
  119 #define DST_TYPE_PUBLIC  0x4000000
  120 #define DST_TYPE_STATE   0x8000000
  121 
  122 /* Key timing metadata definitions */
  123 #define DST_TIME_CREATED     0
  124 #define DST_TIME_PUBLISH     1
  125 #define DST_TIME_ACTIVATE    2
  126 #define DST_TIME_REVOKE      3
  127 #define DST_TIME_INACTIVE    4
  128 #define DST_TIME_DELETE      5
  129 #define DST_TIME_DSPUBLISH   6
  130 #define DST_TIME_SYNCPUBLISH 7
  131 #define DST_TIME_SYNCDELETE  8
  132 #define DST_TIME_DNSKEY      9
  133 #define DST_TIME_ZRRSIG      10
  134 #define DST_TIME_KRRSIG      11
  135 #define DST_TIME_DS      12
  136 #define DST_TIME_DSDELETE    13
  137 #define DST_MAX_TIMES        13
  138 
  139 /* Numeric metadata definitions */
  140 #define DST_NUM_PREDECESSOR 0
  141 #define DST_NUM_SUCCESSOR   1
  142 #define DST_NUM_MAXTTL      2
  143 #define DST_NUM_ROLLPERIOD  3
  144 #define DST_NUM_LIFETIME    4
  145 #define DST_MAX_NUMERIC     4
  146 
  147 /* Boolean metadata definitions */
  148 #define DST_BOOL_KSK    0
  149 #define DST_BOOL_ZSK    1
  150 #define DST_MAX_BOOLEAN 1
  151 
  152 /* Key state metadata definitions */
  153 #define DST_KEY_DNSKEY    0
  154 #define DST_KEY_ZRRSIG    1
  155 #define DST_KEY_KRRSIG    2
  156 #define DST_KEY_DS    3
  157 #define DST_KEY_GOAL      4
  158 #define DST_MAX_KEYSTATES 4
  159 
  160 /*
  161  * Current format version number of the private key parser.
  162  *
  163  * When parsing a key file with the same major number but a higher minor
  164  * number, the key parser will ignore any fields it does not recognize.
  165  * Thus, DST_MINOR_VERSION should be incremented whenever new
  166  * fields are added to the private key file (such as new metadata).
  167  *
  168  * When rewriting these keys, those fields will be dropped, and the
  169  * format version set back to the current one..
  170  *
  171  * When a key is seen with a higher major number, the key parser will
  172  * reject it as invalid.  Thus, DST_MAJOR_VERSION should be incremented
  173  * and DST_MINOR_VERSION set to zero whenever there is a format change
  174  * which is not backward compatible to previous versions of the dst_key
  175  * parser, such as change in the syntax of an existing field, the removal
  176  * of a currently mandatory field, or a new field added which would
  177  * alter the functioning of the key if it were absent.
  178  */
  179 #define DST_MAJOR_VERSION 1
  180 #define DST_MINOR_VERSION 3
  181 
  182 /***
  183  *** Functions
  184  ***/
  185 isc_result_t
  186 dst_lib_init(isc_mem_t *mctx, const char *engine);
  187 /*%<
  188  * Initializes the DST subsystem.
  189  *
  190  * Requires:
  191  * \li  "mctx" is a valid memory context
  192  *
  193  * Returns:
  194  * \li  ISC_R_SUCCESS
  195  * \li  ISC_R_NOMEMORY
  196  * \li  DST_R_NOENGINE
  197  *
  198  * Ensures:
  199  * \li  DST is properly initialized.
  200  */
  201 
  202 void
  203 dst_lib_destroy(void);
  204 /*%<
  205  * Releases all resources allocated by DST.
  206  */
  207 
  208 bool
  209 dst_algorithm_supported(unsigned int alg);
  210 /*%<
  211  * Checks that a given algorithm is supported by DST.
  212  *
  213  * Returns:
  214  * \li  true
  215  * \li  false
  216  */
  217 
  218 bool
  219 dst_ds_digest_supported(unsigned int digest_type);
  220 /*%<
  221  * Checks that a given digest algorithm is supported by DST.
  222  *
  223  * Returns:
  224  * \li  true
  225  * \li  false
  226  */
  227 
  228 isc_result_t
  229 dst_context_create(dst_key_t *key, isc_mem_t *mctx, isc_logcategory_t *category,
  230            bool useforsigning, int maxbits, dst_context_t **dctxp);
  231 /*%<
  232  * Creates a context to be used for a sign or verify operation.
  233  *
  234  * Requires:
  235  * \li  "key" is a valid key.
  236  * \li  "mctx" is a valid memory context.
  237  * \li  dctxp != NULL && *dctxp == NULL
  238  *
  239  * Returns:
  240  * \li  ISC_R_SUCCESS
  241  * \li  ISC_R_NOMEMORY
  242  *
  243  * Ensures:
  244  * \li  *dctxp will contain a usable context.
  245  */
  246 
  247 void
  248 dst_context_destroy(dst_context_t **dctxp);
  249 /*%<
  250  * Destroys all memory associated with a context.
  251  *
  252  * Requires:
  253  * \li  *dctxp != NULL && *dctxp == NULL
  254  *
  255  * Ensures:
  256  * \li  *dctxp == NULL
  257  */
  258 
  259 isc_result_t
  260 dst_context_adddata(dst_context_t *dctx, const isc_region_t *data);
  261 /*%<
  262  * Incrementally adds data to the context to be used in a sign or verify
  263  * operation.
  264  *
  265  * Requires:
  266  * \li  "dctx" is a valid context
  267  * \li  "data" is a valid region
  268  *
  269  * Returns:
  270  * \li  ISC_R_SUCCESS
  271  * \li  DST_R_SIGNFAILURE
  272  * \li  all other errors indicate failure
  273  */
  274 
  275 isc_result_t
  276 dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig);
  277 /*%<
  278  * Computes a signature using the data and key stored in the context.
  279  *
  280  * Requires:
  281  * \li  "dctx" is a valid context.
  282  * \li  "sig" is a valid buffer.
  283  *
  284  * Returns:
  285  * \li  ISC_R_SUCCESS
  286  * \li  DST_R_VERIFYFAILURE
  287  * \li  all other errors indicate failure
  288  *
  289  * Ensures:
  290  * \li  "sig" will contain the signature
  291  */
  292 
  293 isc_result_t
  294 dst_context_verify(dst_context_t *dctx, isc_region_t *sig);
  295 
  296 isc_result_t
  297 dst_context_verify2(dst_context_t *dctx, unsigned int maxbits,
  298             isc_region_t *sig);
  299 /*%<
  300  * Verifies the signature using the data and key stored in the context.
  301  *
  302  * 'maxbits' specifies the maximum number of bits permitted in the RSA
  303  * exponent.
  304  *
  305  * Requires:
  306  * \li  "dctx" is a valid context.
  307  * \li  "sig" is a valid region.
  308  *
  309  * Returns:
  310  * \li  ISC_R_SUCCESS
  311  * \li  all other errors indicate failure
  312  *
  313  * Ensures:
  314  * \li  "sig" will contain the signature
  315  */
  316 
  317 isc_result_t
  318 dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
  319               isc_buffer_t *secret);
  320 /*%<
  321  * Computes a shared secret from two (Diffie-Hellman) keys.
  322  *
  323  * Requires:
  324  * \li  "pub" is a valid key that can be used to derive a shared secret
  325  * \li  "priv" is a valid private key that can be used to derive a shared secret
  326  * \li  "secret" is a valid buffer
  327  *
  328  * Returns:
  329  * \li  ISC_R_SUCCESS
  330  * \li  any other result indicates failure
  331  *
  332  * Ensures:
  333  * \li  If successful, secret will contain the derived shared secret.
  334  */
  335 
  336 isc_result_t
  337 dst_key_getfilename(dns_name_t *name, dns_keytag_t id, unsigned int alg,
  338             int type, const char *directory, isc_mem_t *mctx,
  339             isc_buffer_t *buf);
  340 /*%<
  341  * Generates a key filename for the name, algorithm, and
  342  * id, and places it in the buffer 'buf'. If directory is NULL, the
  343  * current directory is assumed.
  344  *
  345  * Requires:
  346  * \li  "name" is a valid absolute dns name.
  347  * \li  "id" is a valid key tag identifier.
  348  * \li  "alg" is a supported key algorithm.
  349  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
  350  *        DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  351  * \li  "mctx" is a valid memory context.
  352  * \li  "buf" is not NULL.
  353  *
  354  * Returns:
  355  * \li  ISC_R_SUCCESS
  356  * \li  any other result indicates failure
  357  */
  358 
  359 isc_result_t
  360 dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
  361          const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
  362 /*%<
  363  * Reads a key from permanent storage.  The key can either be a public or
  364  * private key, or a key state. It specified by name, algorithm, and id.  If
  365  * a private key or key state is specified, the public key must also be
  366  * present.  If directory is NULL, the current directory is assumed.
  367  *
  368  * Requires:
  369  * \li  "name" is a valid absolute dns name.
  370  * \li  "id" is a valid key tag identifier.
  371  * \li  "alg" is a supported key algorithm.
  372  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE or the bitwise union.
  373  *        DST_TYPE_KEY look for a KEY record otherwise DNSKEY.
  374  *        DST_TYPE_STATE to also read the key state.
  375  * \li  "mctx" is a valid memory context.
  376  * \li  "keyp" is not NULL and "*keyp" is NULL.
  377  *
  378  * Returns:
  379  * \li  ISC_R_SUCCESS
  380  * \li  any other result indicates failure
  381  *
  382  * Ensures:
  383  * \li  If successful, *keyp will contain a valid key.
  384  */
  385 
  386 isc_result_t
  387 dst_key_fromnamedfile(const char *filename, const char *dirname, int type,
  388               isc_mem_t *mctx, dst_key_t **keyp);
  389 /*%<
  390  * Reads a key from permanent storage.  The key can either be a public or
  391  * private key, or a key state. It is specified by filename.  If a private key
  392  * or key state is specified, the public key must also be present.
  393  *
  394  * If 'dirname' is not NULL, and 'filename' is a relative path,
  395  * then the file is looked up relative to the given directory.
  396  * If 'filename' is an absolute path, 'dirname' is ignored.
  397  *
  398  * Requires:
  399  * \li  "filename" is not NULL
  400  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
  401  *        DST_TYPE_KEY look for a KEY record otherwise DNSKEY.
  402  *        DST_TYPE_STATE to also read the key state.
  403  * \li  "mctx" is a valid memory context
  404  * \li  "keyp" is not NULL and "*keyp" is NULL.
  405  *
  406  * Returns:
  407  * \li  ISC_R_SUCCESS
  408  * \li  any other result indicates failure
  409  *
  410  * Ensures:
  411  * \li  If successful, *keyp will contain a valid key.
  412  */
  413 
  414 isc_result_t
  415 dst_key_read_public(const char *filename, int type, isc_mem_t *mctx,
  416             dst_key_t **keyp);
  417 /*%<
  418  * Reads a public key from permanent storage.  The key must be a public key.
  419  *
  420  * Requires:
  421  * \li  "filename" is not NULL.
  422  * \li  "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY.
  423  * \li  "mctx" is a valid memory context.
  424  * \li  "keyp" is not NULL and "*keyp" is NULL.
  425  *
  426  * Returns:
  427  * \li  ISC_R_SUCCESS
  428  * \li  DST_R_BADKEYTYPE if the key type is not the expected one
  429  * \li  ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
  430  * \li  any other result indicates failure
  431  *
  432  * Ensures:
  433  * \li  If successful, *keyp will contain a valid key.
  434  */
  435 
  436 isc_result_t
  437 dst_key_read_state(const char *filename, isc_mem_t *mctx, dst_key_t **keyp);
  438 /*%<
  439  * Reads a key state from permanent storage.
  440  *
  441  * Requires:
  442  * \li  "filename" is not NULL.
  443  * \li  "mctx" is a valid memory context.
  444  * \li  "keyp" is not NULL and "*keyp" is NULL.
  445  *
  446  * Returns:
  447  * \li  ISC_R_SUCCESS
  448  * \li  ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
  449  * \li  any other result indicates failure
  450  */
  451 
  452 isc_result_t
  453 dst_key_tofile(const dst_key_t *key, int type, const char *directory);
  454 /*%<
  455  * Writes a key to permanent storage.  The key can either be a public or
  456  * private key.  Public keys are written in DNS format and private keys
  457  * are written as a set of base64 encoded values.  If directory is NULL,
  458  * the current directory is assumed.
  459  *
  460  * Requires:
  461  * \li  "key" is a valid key.
  462  * \li  "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
  463  *
  464  * Returns:
  465  * \li  ISC_R_SUCCESS
  466  * \li  any other result indicates failure
  467  */
  468 
  469 isc_result_t
  470 dst_key_fromdns(const dns_name_t *name, dns_rdataclass_t rdclass,
  471         isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  472 /*%<
  473  * Converts a DNS KEY record into a DST key.
  474  *
  475  * Requires:
  476  * \li  "name" is a valid absolute dns name.
  477  * \li  "source" is a valid buffer.  There must be at least 4 bytes available.
  478  * \li  "mctx" is a valid memory context.
  479  * \li  "keyp" is not NULL and "*keyp" is NULL.
  480  *
  481  * Returns:
  482  * \li  ISC_R_SUCCESS
  483  * \li  any other result indicates failure
  484  *
  485  * Ensures:
  486  * \li  If successful, *keyp will contain a valid key, and the consumed
  487  *  pointer in data will be advanced.
  488  */
  489 
  490 isc_result_t
  491 dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
  492 /*%<
  493  * Converts a DST key into a DNS KEY record.
  494  *
  495  * Requires:
  496  * \li  "key" is a valid key.
  497  * \li  "target" is a valid buffer.  There must be at least 4 bytes unused.
  498  *
  499  * Returns:
  500  * \li  ISC_R_SUCCESS
  501  * \li  any other result indicates failure
  502  *
  503  * Ensures:
  504  * \li  If successful, the used pointer in 'target' is advanced by at least 4.
  505  */
  506 
  507 isc_result_t
  508 dst_key_frombuffer(const dns_name_t *name, unsigned int alg, unsigned int flags,
  509            unsigned int protocol, dns_rdataclass_t rdclass,
  510            isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  511 /*%<
  512  * Converts a buffer containing DNS KEY RDATA into a DST key.
  513  *
  514  * Requires:
  515  *\li   "name" is a valid absolute dns name.
  516  *\li   "alg" is a supported key algorithm.
  517  *\li   "source" is a valid buffer.
  518  *\li   "mctx" is a valid memory context.
  519  *\li   "keyp" is not NULL and "*keyp" is NULL.
  520  *
  521  * Returns:
  522  *\li   ISC_R_SUCCESS
  523  * \li  any other result indicates failure
  524  *
  525  * Ensures:
  526  *\li   If successful, *keyp will contain a valid key, and the consumed
  527  *  pointer in source will be advanced.
  528  */
  529 
  530 isc_result_t
  531 dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
  532 /*%<
  533  * Converts a DST key into DNS KEY RDATA format.
  534  *
  535  * Requires:
  536  *\li   "key" is a valid key.
  537  *\li   "target" is a valid buffer.
  538  *
  539  * Returns:
  540  *\li   ISC_R_SUCCESS
  541  * \li  any other result indicates failure
  542  *
  543  * Ensures:
  544  *\li   If successful, the used pointer in 'target' is advanced.
  545  */
  546 
  547 isc_result_t
  548 dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
  549 /*%<
  550  * Converts a public key into a private key, reading the private key
  551  * information from the buffer.  The buffer should contain the same data
  552  * as the .private key file would.
  553  *
  554  * Requires:
  555  *\li   "key" is a valid public key.
  556  *\li   "buffer" is not NULL.
  557  *
  558  * Returns:
  559  *\li   ISC_R_SUCCESS
  560  * \li  any other result indicates failure
  561  *
  562  * Ensures:
  563  *\li   If successful, key will contain a valid private key.
  564  */
  565 
  566 gss_ctx_id_t
  567 dst_key_getgssctx(const dst_key_t *key);
  568 /*%<
  569  * Returns the opaque key data.
  570  * Be cautions when using this value unless you know what you are doing.
  571  *
  572  * Requires:
  573  *\li   "key" is not NULL.
  574  *
  575  * Returns:
  576  *\li   gssctx key data, possibly NULL.
  577  */
  578 
  579 isc_result_t
  580 dst_key_fromgssapi(const dns_name_t *name, gss_ctx_id_t gssctx, isc_mem_t *mctx,
  581            dst_key_t **keyp, isc_region_t *intoken);
  582 /*%<
  583  * Converts a GSSAPI opaque context id into a DST key.
  584  *
  585  * Requires:
  586  *\li   "name" is a valid absolute dns name.
  587  *\li   "gssctx" is a GSSAPI context id.
  588  *\li   "mctx" is a valid memory context.
  589  *\li   "keyp" is not NULL and "*keyp" is NULL.
  590  *
  591  * Returns:
  592  *\li   ISC_R_SUCCESS
  593  * \li  any other result indicates failure
  594  *
  595  * Ensures:
  596  *\li   If successful, *keyp will contain a valid key and be responsible for
  597  *  the context id.
  598  */
  599 
  600 #ifdef DST_KEY_INTERNAL
  601 isc_result_t
  602 dst_key_buildinternal(const dns_name_t *name, unsigned int alg,
  603               unsigned int bits, unsigned int flags,
  604               unsigned int protocol, dns_rdataclass_t rdclass,
  605               void *data, isc_mem_t *mctx, dst_key_t **keyp);
  606 #endif /* ifdef DST_KEY_INTERNAL */
  607 
  608 isc_result_t
  609 dst_key_fromlabel(const dns_name_t *name, int alg, unsigned int flags,
  610           unsigned int protocol, dns_rdataclass_t rdclass,
  611           const char *engine, const char *label, const char *pin,
  612           isc_mem_t *mctx, dst_key_t **keyp);
  613 
  614 isc_result_t
  615 dst_key_generate(const dns_name_t *name, unsigned int alg, unsigned int bits,
  616          unsigned int param, unsigned int flags, unsigned int protocol,
  617          dns_rdataclass_t rdclass, isc_mem_t *mctx, dst_key_t **keyp,
  618          void (*callback)(int));
  619 
  620 /*%<
  621  * Generate a DST key (or keypair) with the supplied parameters.  The
  622  * interpretation of the "param" field depends on the algorithm:
  623  * \code
  624  *  RSA:    exponent
  625  *      0   use exponent 3
  626  *      !0  use Fermat4 (2^16 + 1)
  627  *  DH: generator
  628  *      0   default - use well known prime if bits == 768 or 1024,
  629  *          otherwise use 2 as the generator.
  630  *      !0  use this value as the generator.
  631  *  DSA:    unused
  632  *  HMACMD5: entropy
  633  *      0   default - require good entropy
  634  *      !0  lack of good entropy is ok
  635  *\endcode
  636  *
  637  * Requires:
  638  *\li   "name" is a valid absolute dns name.
  639  *\li   "keyp" is not NULL and "*keyp" is NULL.
  640  *
  641  * Returns:
  642  *\li   ISC_R_SUCCESS
  643  * \li  any other result indicates failure
  644  *
  645  * Ensures:
  646  *\li   If successful, *keyp will contain a valid key.
  647  */
  648 
  649 bool
  650 dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
  651 /*%<
  652  * Compares two DST keys.  Returns true if they match, false otherwise.
  653  *
  654  * Keys ARE NOT considered to match if one of them is the revoked version
  655  * of the other.
  656  *
  657  * Requires:
  658  *\li   "key1" is a valid key.
  659  *\li   "key2" is a valid key.
  660  *
  661  * Returns:
  662  *\li   true
  663  * \li  false
  664  */
  665 
  666 bool
  667 dst_key_pubcompare(const dst_key_t *key1, const dst_key_t *key2,
  668            bool match_revoked_key);
  669 /*%<
  670  * Compares only the public portions of two DST keys.  Returns true
  671  * if they match, false otherwise.  This allows us, for example, to
  672  * determine whether a public key found in a zone matches up with a
  673  * key pair found on disk.
  674  *
  675  * If match_revoked_key is TRUE, then keys ARE considered to match if one
  676  * of them is the revoked version of the other. Otherwise, they are not.
  677  *
  678  * Requires:
  679  *\li   "key1" is a valid key.
  680  *\li   "key2" is a valid key.
  681  *
  682  * Returns:
  683  *\li   true
  684  * \li  false
  685  */
  686 
  687 bool
  688 dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
  689 /*%<
  690  * Compares the parameters of two DST keys.  This is used to determine if
  691  * two (Diffie-Hellman) keys can be used to derive a shared secret.
  692  *
  693  * Requires:
  694  *\li   "key1" is a valid key.
  695  *\li   "key2" is a valid key.
  696  *
  697  * Returns:
  698  *\li   true
  699  * \li  false
  700  */
  701 
  702 void
  703 dst_key_attach(dst_key_t *source, dst_key_t **target);
  704 /*
  705  * Attach to a existing key increasing the reference count.
  706  *
  707  * Requires:
  708  *\li 'source' to be a valid key.
  709  *\li 'target' to be non-NULL and '*target' to be NULL.
  710  */
  711 
  712 void
  713 dst_key_free(dst_key_t **keyp);
  714 /*%<
  715  * Decrement the key's reference counter and, when it reaches zero,
  716  * release all memory associated with the key.
  717  *
  718  * Requires:
  719  *\li   "keyp" is not NULL and "*keyp" is a valid key.
  720  *\li   reference counter greater than zero.
  721  *
  722  * Ensures:
  723  *\li   All memory associated with "*keyp" will be freed.
  724  *\li   *keyp == NULL
  725  */
  726 
  727 /*%<
  728  * Accessor functions to obtain key fields.
  729  *
  730  * Require:
  731  *\li   "key" is a valid key.
  732  */
  733 dns_name_t *
  734 dst_key_name(const dst_key_t *key);
  735 
  736 unsigned int
  737 dst_key_size(const dst_key_t *key);
  738 
  739 unsigned int
  740 dst_key_proto(const dst_key_t *key);
  741 
  742 unsigned int
  743 dst_key_alg(const dst_key_t *key);
  744 
  745 uint32_t
  746 dst_key_flags(const dst_key_t *key);
  747 
  748 dns_keytag_t
  749 dst_key_id(const dst_key_t *key);
  750 
  751 dns_keytag_t
  752 dst_key_rid(const dst_key_t *key);
  753 
  754 dns_rdataclass_t
  755 dst_key_class(const dst_key_t *key);
  756 
  757 bool
  758 dst_key_isprivate(const dst_key_t *key);
  759 
  760 bool
  761 dst_key_iszonekey(const dst_key_t *key);
  762 
  763 bool
  764 dst_key_isnullkey(const dst_key_t *key);
  765 
  766 isc_result_t
  767 dst_key_buildfilename(const dst_key_t *key, int type, const char *directory,
  768               isc_buffer_t *out);
  769 /*%<
  770  * Generates the filename used by dst to store the specified key.
  771  * If directory is NULL, the current directory is assumed.
  772  *
  773  * Requires:
  774  *\li   "key" is a valid key
  775  *\li   "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
  776  *\li   "out" is a valid buffer
  777  *
  778  * Ensures:
  779  *\li   the file name will be written to "out", and the used pointer will
  780  *      be advanced.
  781  */
  782 
  783 isc_result_t
  784 dst_key_sigsize(const dst_key_t *key, unsigned int *n);
  785 /*%<
  786  * Computes the size of a signature generated by the given key.
  787  *
  788  * Requires:
  789  *\li   "key" is a valid key.
  790  *\li   "n" is not NULL
  791  *
  792  * Returns:
  793  *\li   #ISC_R_SUCCESS
  794  *\li   DST_R_UNSUPPORTEDALG
  795  *
  796  * Ensures:
  797  *\li   "n" stores the size of a generated signature
  798  */
  799 
  800 isc_result_t
  801 dst_key_secretsize(const dst_key_t *key, unsigned int *n);
  802 /*%<
  803  * Computes the size of a shared secret generated by the given key.
  804  *
  805  * Requires:
  806  *\li   "key" is a valid key.
  807  *\li   "n" is not NULL
  808  *
  809  * Returns:
  810  *\li   #ISC_R_SUCCESS
  811  *\li   DST_R_UNSUPPORTEDALG
  812  *
  813  * Ensures:
  814  *\li   "n" stores the size of a generated shared secret
  815  */
  816 
  817 uint16_t
  818 dst_region_computeid(const isc_region_t *source);
  819 uint16_t
  820 dst_region_computerid(const isc_region_t *source);
  821 /*%<
  822  * Computes the (revoked) key id of the key stored in the provided
  823  * region.
  824  *
  825  * Requires:
  826  *\li   "source" contains a valid, non-NULL region.
  827  *
  828  * Returns:
  829  *\li   the key id
  830  */
  831 
  832 uint16_t
  833 dst_key_getbits(const dst_key_t *key);
  834 /*%<
  835  * Get the number of digest bits required (0 == MAX).
  836  *
  837  * Requires:
  838  *  "key" is a valid key.
  839  */
  840 
  841 void
  842 dst_key_setbits(dst_key_t *key, uint16_t bits);
  843 /*%<
  844  * Set the number of digest bits required (0 == MAX).
  845  *
  846  * Requires:
  847  *  "key" is a valid key.
  848  */
  849 
  850 void
  851 dst_key_setttl(dst_key_t *key, dns_ttl_t ttl);
  852 /*%<
  853  * Set the default TTL to use when converting the key
  854  * to a KEY or DNSKEY RR.
  855  *
  856  * Requires:
  857  *  "key" is a valid key.
  858  */
  859 
  860 dns_ttl_t
  861 dst_key_getttl(const dst_key_t *key);
  862 /*%<
  863  * Get the default TTL to use when converting the key
  864  * to a KEY or DNSKEY RR.
  865  *
  866  * Requires:
  867  *  "key" is a valid key.
  868  */
  869 
  870 isc_result_t
  871 dst_key_setflags(dst_key_t *key, uint32_t flags);
  872 /*
  873  * Set the key flags, and recompute the key ID.
  874  *
  875  * Requires:
  876  *  "key" is a valid key.
  877  */
  878 
  879 isc_result_t
  880 dst_key_getbool(const dst_key_t *key, int type, bool *valuep);
  881 /*%<
  882  * Get a member of the boolean metadata array and place it in '*valuep'.
  883  *
  884  * Requires:
  885  *  "key" is a valid key.
  886  *  "type" is no larger than DST_MAX_BOOLEAN
  887  *  "valuep" is not null.
  888  */
  889 
  890 void
  891 dst_key_setbool(dst_key_t *key, int type, bool value);
  892 /*%<
  893  * Set a member of the boolean metadata array.
  894  *
  895  * Requires:
  896  *  "key" is a valid key.
  897  *  "type" is no larger than DST_MAX_BOOLEAN
  898  */
  899 
  900 void
  901 dst_key_unsetbool(dst_key_t *key, int type);
  902 /*%<
  903  * Flag a member of the boolean metadata array as "not set".
  904  *
  905  * Requires:
  906  *  "key" is a valid key.
  907  *  "type" is no larger than DST_MAX_BOOLEAN
  908  */
  909 
  910 isc_result_t
  911 dst_key_getnum(const dst_key_t *key, int type, uint32_t *valuep);
  912 /*%<
  913  * Get a member of the numeric metadata array and place it in '*valuep'.
  914  *
  915  * Requires:
  916  *  "key" is a valid key.
  917  *  "type" is no larger than DST_MAX_NUMERIC
  918  *  "valuep" is not null.
  919  */
  920 
  921 void
  922 dst_key_setnum(dst_key_t *key, int type, uint32_t value);
  923 /*%<
  924  * Set a member of the numeric metadata array.
  925  *
  926  * Requires:
  927  *  "key" is a valid key.
  928  *  "type" is no larger than DST_MAX_NUMERIC
  929  */
  930 
  931 void
  932 dst_key_unsetnum(dst_key_t *key, int type);
  933 /*%<
  934  * Flag a member of the numeric metadata array as "not set".
  935  *
  936  * Requires:
  937  *  "key" is a valid key.
  938  *  "type" is no larger than DST_MAX_NUMERIC
  939  */
  940 
  941 isc_result_t
  942 dst_key_gettime(const dst_key_t *key, int type, isc_stdtime_t *timep);
  943 /*%<
  944  * Get a member of the timing metadata array and place it in '*timep'.
  945  *
  946  * Requires:
  947  *  "key" is a valid key.
  948  *  "type" is no larger than DST_MAX_TIMES
  949  *  "timep" is not null.
  950  */
  951 
  952 void
  953 dst_key_settime(dst_key_t *key, int type, isc_stdtime_t when);
  954 /*%<
  955  * Set a member of the timing metadata array.
  956  *
  957  * Requires:
  958  *  "key" is a valid key.
  959  *  "type" is no larger than DST_MAX_TIMES
  960  */
  961 
  962 void
  963 dst_key_unsettime(dst_key_t *key, int type);
  964 /*%<
  965  * Flag a member of the timing metadata array as "not set".
  966  *
  967  * Requires:
  968  *  "key" is a valid key.
  969  *  "type" is no larger than DST_MAX_TIMES
  970  */
  971 
  972 isc_result_t
  973 dst_key_getstate(const dst_key_t *key, int type, dst_key_state_t *statep);
  974 /*%<
  975  * Get a member of the keystate metadata array and place it in '*statep'.
  976  *
  977  * Requires:
  978  *  "key" is a valid key.
  979  *  "type" is no larger than DST_MAX_KEYSTATES
  980  *  "statep" is not null.
  981  */
  982 
  983 void
  984 dst_key_setstate(dst_key_t *key, int type, dst_key_state_t state);
  985 /*%<
  986  * Set a member of the keystate metadata array.
  987  *
  988  * Requires:
  989  *  "key" is a valid key.
  990  *  "state" is a valid state.
  991  *  "type" is no larger than DST_MAX_KEYSTATES
  992  */
  993 
  994 void
  995 dst_key_unsetstate(dst_key_t *key, int type);
  996 /*%<
  997  * Flag a member of the keystate metadata array as "not set".
  998  *
  999  * Requires:
 1000  *  "key" is a valid key.
 1001  *  "type" is no larger than DST_MAX_KEYSTATES
 1002  */
 1003 
 1004 isc_result_t
 1005 dst_key_getprivateformat(const dst_key_t *key, int *majorp, int *minorp);
 1006 /*%<
 1007  * Get the private key format version number.  (If the key does not have
 1008  * a private key associated with it, the version will be 0.0.)  The major
 1009  * version number is placed in '*majorp', and the minor version number in
 1010  * '*minorp'.
 1011  *
 1012  * Requires:
 1013  *  "key" is a valid key.
 1014  *  "majorp" is not NULL.
 1015  *  "minorp" is not NULL.
 1016  */
 1017 
 1018 void
 1019 dst_key_setprivateformat(dst_key_t *key, int major, int minor);
 1020 /*%<
 1021  * Set the private key format version number.
 1022  *
 1023  * Requires:
 1024  *  "key" is a valid key.
 1025  */
 1026 
 1027 #define DST_KEY_FORMATSIZE (DNS_NAME_FORMATSIZE + DNS_SECALG_FORMATSIZE + 7)
 1028 
 1029 void
 1030 dst_key_format(const dst_key_t *key, char *cp, unsigned int size);
 1031 /*%<
 1032  * Write the uniquely identifying information about the key (name,
 1033  * algorithm, key ID) into a string 'cp' of size 'size'.
 1034  */
 1035 
 1036 isc_buffer_t *
 1037 dst_key_tkeytoken(const dst_key_t *key);
 1038 /*%<
 1039  * Return the token from the TKEY request, if any.  If this key was
 1040  * not negotiated via TKEY, return NULL.
 1041  *
 1042  * Requires:
 1043  *  "key" is a valid key.
 1044  */
 1045 
 1046 isc_result_t
 1047 dst_key_dump(dst_key_t *key, isc_mem_t *mctx, char **buffer, int *length);
 1048 /*%<
 1049  * Allocate 'buffer' and dump the key into it in base64 format. The buffer
 1050  * is not NUL terminated. The length of the buffer is returned in *length.
 1051  *
 1052  * 'buffer' needs to be freed using isc_mem_put(mctx, buffer, length);
 1053  *
 1054  * Requires:
 1055  *  'buffer' to be non NULL and *buffer to be NULL.
 1056  *  'length' to be non NULL and *length to be zero.
 1057  *
 1058  * Returns:
 1059  *  ISC_R_SUCCESS
 1060  *  ISC_R_NOMEMORY
 1061  *  ISC_R_NOTIMPLEMENTED
 1062  *  others.
 1063  */
 1064 
 1065 isc_result_t
 1066 dst_key_restore(dns_name_t *name, unsigned int alg, unsigned int flags,
 1067         unsigned int protocol, dns_rdataclass_t rdclass,
 1068         isc_mem_t *mctx, const char *keystr, dst_key_t **keyp);
 1069 
 1070 bool
 1071 dst_key_inactive(const dst_key_t *key);
 1072 /*%<
 1073  * Determines if the private key is missing due the key being deemed inactive.
 1074  *
 1075  * Requires:
 1076  *  'key' to be valid.
 1077  */
 1078 
 1079 void
 1080 dst_key_setinactive(dst_key_t *key, bool inactive);
 1081 /*%<
 1082  * Set key inactive state.
 1083  *
 1084  * Requires:
 1085  *  'key' to be valid.
 1086  */
 1087 
 1088 void
 1089 dst_key_setexternal(dst_key_t *key, bool value);
 1090 /*%<
 1091  * Set key external state.
 1092  *
 1093  * Requires:
 1094  *  'key' to be valid.
 1095  */
 1096 
 1097 bool
 1098 dst_key_isexternal(dst_key_t *key);
 1099 /*%<
 1100  * Check if this is an external key.
 1101  *
 1102  * Requires:
 1103  *  'key' to be valid.
 1104  */
 1105 
 1106 bool
 1107 dst_key_is_unused(dst_key_t *key);
 1108 /*%<
 1109  * Check if this key is unused.
 1110  *
 1111  * Requires:
 1112  *  'key' to be valid.
 1113  */
 1114 
 1115 bool
 1116 dst_key_is_published(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *publish);
 1117 /*%<
 1118  * Check if it is safe to publish this key (e.g. put the DNSKEY in the zone).
 1119  *
 1120  * Requires:
 1121  *  'key' to be valid.
 1122  */
 1123 
 1124 bool
 1125 dst_key_is_active(dst_key_t *key, isc_stdtime_t now);
 1126 /*%<
 1127  * Check if this key is active. This means that it is creating RRSIG records
 1128  * (ZSK), or that it is used to create a chain of trust (KSK), or both (CSK).
 1129  *
 1130  * Requires:
 1131  *  'key' to be valid.
 1132  */
 1133 
 1134 bool
 1135 dst_key_is_signing(dst_key_t *key, int role, isc_stdtime_t now,
 1136            isc_stdtime_t *active);
 1137 /*%<
 1138  * Check if it is safe to use this key for signing, given the role.
 1139  *
 1140  * Requires:
 1141  *  'key' to be valid.
 1142  */
 1143 
 1144 bool
 1145 dst_key_is_revoked(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *revoke);
 1146 /*%<
 1147  * Check if this key is revoked.
 1148  *
 1149  * Requires:
 1150  *  'key' to be valid.
 1151  */
 1152 
 1153 bool
 1154 dst_key_is_removed(dst_key_t *key, isc_stdtime_t now, isc_stdtime_t *remove);
 1155 /*%<
 1156  * Check if this key is removed from the zone (e.g. the DNSKEY record should
 1157  * no longer be in the zone).
 1158  *
 1159  * Requires:
 1160  *  'key' to be valid.
 1161  */
 1162 
 1163 dst_key_state_t
 1164 dst_key_goal(dst_key_t *key);
 1165 /*%<
 1166  * Get the key goal. Should be OMNIPRESENT or HIDDEN.
 1167  * This can be used to determine if the key is being introduced or
 1168  * is on its way out.
 1169  *
 1170  * Requires:
 1171  *  'key' to be valid.
 1172  */
 1173 
 1174 void
 1175 dst_key_copy_metadata(dst_key_t *to, dst_key_t *from);
 1176 /*%<
 1177  * Copy key metadata from one key to another.
 1178  *
 1179  * Requires:
 1180  *  'to' and 'from' to be valid.
 1181  */
 1182 
 1183 ISC_LANG_ENDDECLS
 1184 
 1185 #endif /* DST_DST_H */