contrib/bind/lib/dns/include/dns/dnssec.h

   1 /*
   2  * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: dnssec.h,v 1.32 2007/06/19 23:47:16 tbox Exp $ */
  19
  20 #ifndef DNS_DNSSEC_H
  21 #define DNS_DNSSEC_H 1
  22
  23 /*! \file dns/dnssec.h */
  24
  25 #include <isc/lang.h>
  26 #include <isc/stdtime.h>
  27
  28 #include <dns/types.h>
  29
  30 #include <dst/dst.h>
  31
  32 ISC_LANG_BEGINDECLS
  33
  34 isc_result_t
  35 dns_dnssec_keyfromrdata(dns_name_t *name, dns_rdata_t *rdata, isc_mem_t *mctx,
  36                         dst_key_t **key);
  37 /*%<
  38  *      Creates a DST key from a DNS record.  Basically a wrapper around
  39  *      dst_key_fromdns().
  40  *
  41  *      Requires:
  42  *\li           'name' is not NULL
  43  *\li           'rdata' is not NULL
  44  *\li           'mctx' is not NULL
  45  *\li           'key' is not NULL
  46  *\li           '*key' is NULL
  47  *
  48  *      Returns:
  49  *\li           #ISC_R_SUCCESS
  50  *\li           #ISC_R_NOMEMORY
  51  *\li           DST_R_INVALIDPUBLICKEY
  52  *\li           various errors from dns_name_totext
  53  */
  54
  55 isc_result_t
  56 dns_dnssec_sign(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  57                 isc_stdtime_t *inception, isc_stdtime_t *expire,
  58                 isc_mem_t *mctx, isc_buffer_t *buffer, dns_rdata_t *sigrdata);
  59 /*%<
  60  *      Generates a SIG record covering this rdataset.  This has no effect
  61  *      on existing SIG records.
  62  *
  63  *      Requires:
  64  *\li           'name' (the owner name of the record) is a valid name
  65  *\li           'set' is a valid rdataset
  66  *\li           'key' is a valid key
  67  *\li           'inception' is not NULL
  68  *\li           'expire' is not NULL
  69  *\li           'mctx' is not NULL
  70  *\li           'buffer' is not NULL
  71  *\li           'sigrdata' is not NULL
  72  *
  73  *      Returns:
  74  *\li           #ISC_R_SUCCESS
  75  *\li           #ISC_R_NOMEMORY
  76  *\li           #ISC_R_NOSPACE
  77  *\li           #DNS_R_INVALIDTIME - the expiration is before the inception
  78  *\li           #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either
  79  *                      it is not a zone key or its flags prevent
  80  *                      authentication)
  81  *\li           DST_R_*
  82  */
  83
  84 isc_result_t
  85 dns_dnssec_verify(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  86                   isc_boolean_t ignoretime, isc_mem_t *mctx,
  87                   dns_rdata_t *sigrdata);
  88
  89 isc_result_t
  90 dns_dnssec_verify2(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  91                    isc_boolean_t ignoretime, isc_mem_t *mctx,
  92                    dns_rdata_t *sigrdata, dns_name_t *wild);
  93 /*%<
  94  *      Verifies the SIG record covering this rdataset signed by a specific
  95  *      key.  This does not determine if the key's owner is authorized to
  96  *      sign this record, as this requires a resolver or database.
  97  *      If 'ignoretime' is ISC_TRUE, temporal validity will not be checked.
  98  *
  99  *      Requires:
 100  *\li           'name' (the owner name of the record) is a valid name
 101  *\li           'set' is a valid rdataset
 102  *\li           'key' is a valid key
 103  *\li           'mctx' is not NULL
 104  *\li           'sigrdata' is a valid rdata containing a SIG record
 105  *\li           'wild' if non-NULL then is a valid and has a buffer.
 106  *
 107  *      Returns:
 108  *\li           #ISC_R_SUCCESS
 109  *\li           #ISC_R_NOMEMORY
 110  *\li           #DNS_R_FROMWILDCARD - the signature is valid and is from
 111  *                      a wildcard expansion.  dns_dnssec_verify2() only.
 112  *                      'wild' contains the name of the wildcard if non-NULL.
 113  *\li           #DNS_R_SIGINVALID - the signature fails to verify
 114  *\li           #DNS_R_SIGEXPIRED - the signature has expired
 115  *\li           #DNS_R_SIGFUTURE - the signature's validity period has not begun
 116  *\li           #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either
 117  *                      it is not a zone key or its flags prevent
 118  *                      authentication)
 119  *\li           DST_R_*
 120  */
 121
 122 /*@{*/
 123 isc_result_t
 124 dns_dnssec_findzonekeys(dns_db_t *db, dns_dbversion_t *ver, dns_dbnode_t *node,
 125                         dns_name_t *name, isc_mem_t *mctx,
 126                         unsigned int maxkeys, dst_key_t **keys,
 127                         unsigned int *nkeys);
 128 isc_result_t
 129 dns_dnssec_findzonekeys2(dns_db_t *db, dns_dbversion_t *ver,
 130                          dns_dbnode_t *node, dns_name_t *name,
 131                          const char *directory, isc_mem_t *mctx,
 132                          unsigned int maxkeys, dst_key_t **keys,
 133                          unsigned int *nkeys);
 134 /*%<
 135  *      Finds a set of zone keys.
 136  *      XXX temporary - this should be handled in dns_zone_t.
 137  */
 138 /*@}*/
 139
 140 isc_result_t
 141 dns_dnssec_signmessage(dns_message_t *msg, dst_key_t *key);
 142 /*%<
 143  *      Signs a message with a SIG(0) record.  This is implicitly called by
 144  *      dns_message_renderend() if msg->sig0key is not NULL.
 145  *
 146  *      Requires:
 147  *\li           'msg' is a valid message
 148  *\li           'key' is a valid key that can be used for signing
 149  *
 150  *      Returns:
 151  *\li           #ISC_R_SUCCESS
 152  *\li           #ISC_R_NOMEMORY
 153  *\li           DST_R_*
 154  */
 155
 156 isc_result_t
 157 dns_dnssec_verifymessage(isc_buffer_t *source, dns_message_t *msg,
 158                          dst_key_t *key);
 159 /*%<
 160  *      Verifies a message signed by a SIG(0) record.  This is not
 161  *      called implicitly by dns_message_parse().  If dns_message_signer()
 162  *      is called before dns_dnssec_verifymessage(), it will return
 163  *      #DNS_R_NOTVERIFIEDYET.  dns_dnssec_verifymessage() will set
 164  *      the verified_sig0 flag in msg if the verify succeeds, and
 165  *      the sig0status field otherwise.
 166  *
 167  *      Requires:
 168  *\li           'source' is a valid buffer containing the unparsed message
 169  *\li           'msg' is a valid message
 170  *\li           'key' is a valid key
 171  *
 172  *      Returns:
 173  *\li           #ISC_R_SUCCESS
 174  *\li           #ISC_R_NOMEMORY
 175  *\li           #ISC_R_NOTFOUND - no SIG(0) was found
 176  *\li           #DNS_R_SIGINVALID - the SIG record is not well-formed or
 177  *                                 was not generated by the key.
 178  *\li           DST_R_*
 179  */
 180
 181 ISC_LANG_ENDDECLS
 182
 183 #endif /* DNS_DNSSEC_H */