contrib/bind9/lib/dns/include/dns/tsec.h

   1 /*
   2  * Copyright (C) 2009, 2010, 2012  Internet Systems Consortium, Inc. ("ISC")
   3  *
   4  * Permission to use, copy, modify, and/or distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14  * PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* $Id: tsec.h,v 1.6 2010/12/09 00:54:34 marka Exp $ */
  18
  19 #ifndef DNS_TSEC_H
  20 #define DNS_TSEC_H 1
  21
  22 /*****
  23  ***** Module Info
  24  *****/
  25
  26 /*! \file
  27  *
  28  * \brief
  29  * The TSEC (Transaction Security) module is an abstraction layer for managing
  30  * DNS transaction mechanisms such as TSIG or SIG(0).  A TSEC structure is a
  31  * mechanism-independent object containing key information specific to the
  32  * mechanism, and is expected to be used as an argument to other modules
  33  * that use transaction security in a mechanism-independent manner.
  34  *
  35  * MP:
  36  *\li   A TSEC structure is expected to be thread-specific.  No inter-thread
  37  *      synchronization is ensured in multiple access to a single TSEC
  38  *      structure.
  39  *
  40  * Resources:
  41  *\li   TBS
  42  *
  43  * Security:
  44  *\li   This module does not handle any low-level data directly, and so no
  45  *      security issue specific to this module is anticipated.
  46  */
  47
  48 #include <dns/types.h>
  49
  50 #include <dst/dst.h>
  51
  52 ISC_LANG_BEGINDECLS
  53
  54 /***
  55  *** Types
  56  ***/
  57
  58 /*%
  59  * Transaction security types.
  60  */
  61 typedef enum {
  62         dns_tsectype_none,
  63         dns_tsectype_tsig,
  64         dns_tsectype_sig0
  65 } dns_tsectype_t;
  66
  67 isc_result_t
  68 dns_tsec_create(isc_mem_t *mctx, dns_tsectype_t type, dst_key_t *key,
  69                 dns_tsec_t **tsecp);
  70 /*%<
  71  * Create a TSEC structure and stores a type-dependent key structure in it.
  72  * For a TSIG key (type is dns_tsectype_tsig), dns_tsec_create() creates a
  73  * TSIG key structure from '*key' and keeps it in the structure.  For other
  74  * types, this function simply retains '*key' in the structure.  In either
  75  * case, the ownership of '*key' is transferred to the TSEC module; the caller
  76  * must not modify or destroy it after the call to dns_tsec_create().
  77  *
  78  * Requires:
  79  *
  80  *\li   'mctx' is a valid memory context.
  81  *
  82  *\li   'type' is a valid value of dns_tsectype_t (see above).
  83  *
  84  *\li   'key' is a valid key.
  85  *
  86  *\li   tsecp != NULL && *tsecp == NULL.
  87  *
  88  * Returns:
  89  *
  90  *\li   #ISC_R_SUCCESS                          On success.
  91  *
  92  *\li   Anything else                           Failure.
  93  */
  94
  95 void
  96 dns_tsec_destroy(dns_tsec_t **tsecp);
  97 /*%<
  98  * Destroy the TSEC structure.  The stored key is also detached or destroyed.
  99  *
 100  * Requires
 101  *
 102  *\li   '*tsecp' is a valid TSEC structure.
 103  *
 104  * Ensures
 105  *
 106  *\li   *tsecp == NULL.
 107  *
 108  */
 109
 110 dns_tsectype_t
 111 dns_tsec_gettype(dns_tsec_t *tsec);
 112 /*%<
 113  * Return the TSEC type of '*tsec'.
 114  *
 115  * Requires
 116  *
 117  *\li   'tsec' is a valid TSEC structure.
 118  *
 119  */
 120
 121 void
 122 dns_tsec_getkey(dns_tsec_t *tsec, void *keyp);
 123 /*%<
 124  * Return the TSEC key of '*tsec' in '*keyp'.
 125  *
 126  * Requires
 127  *
 128  *\li   keyp != NULL
 129  *
 130  * Ensures
 131  *
 132  *\li   *tsecp points to a valid key structure depending on the TSEC type.
 133  */
 134
 135 ISC_LANG_ENDDECLS
 136
 137 #endif /* DNS_TSEC_H */