/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
 52ISC_LANG_BEGINDECLS
 53
 54/***
 55 *** Types
 56 ***/
 57
 58/*%
 59 * Transaction security types.
 60 */
 61typedef enum {
 62	dns_tsectype_none,
 63	dns_tsectype_tsig,
 64	dns_tsectype_sig0
 65} dns_tsectype_t;
 66
 67isc_result_t
 68dns_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
 95void
 96dns_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
110dns_tsectype_t
111dns_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
121void
122dns_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
135ISC_LANG_ENDDECLS
136
137#endif /* DNS_TSEC_H */