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 */
138