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