1 /*
2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3  *
4  * SPDX-License-Identifier: MPL-2.0
5  *
6  * This Source Code Form is subject to the terms of the Mozilla Public
7  * License, v. 2.0. If a copy of the MPL was not distributed with this
8  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
9  *
10  * See the COPYRIGHT file distributed with this work for additional
11  * information regarding copyright ownership.
12  */
13 
14 #ifndef DNS_TSEC_H
15 #define DNS_TSEC_H 1
16 
17 /*****
18 ***** Module Info
19 *****/
20 
21 /*! \file
22  *
23  * \brief
24  * The TSEC (Transaction Security) module is an abstraction layer for managing
25  * DNS transaction mechanisms such as TSIG or SIG(0).  A TSEC structure is a
26  * mechanism-independent object containing key information specific to the
27  * mechanism, and is expected to be used as an argument to other modules
28  * that use transaction security in a mechanism-independent manner.
29  *
30  * MP:
31  *\li	A TSEC structure is expected to be thread-specific.  No inter-thread
32  *	synchronization is ensured in multiple access to a single TSEC
33  *	structure.
34  *
35  * Resources:
36  *\li	TBS
37  *
38  * Security:
39  *\li	This module does not handle any low-level data directly, and so no
40  *	security issue specific to this module is anticipated.
41  */
42 
43 #include <dns/types.h>
44 
45 #include <dst/dst.h>
46 
47 ISC_LANG_BEGINDECLS
48 
49 /***
50  *** Types
51  ***/
52 
53 /*%
54  * Transaction security types.
55  */
56 typedef enum {
57 	dns_tsectype_none,
58 	dns_tsectype_tsig,
59 	dns_tsectype_sig0
60 } dns_tsectype_t;
61 
62 isc_result_t
63 dns_tsec_create(isc_mem_t *mctx, dns_tsectype_t type, dst_key_t *key,
64 		dns_tsec_t **tsecp);
65 /*%<
66  * Create a TSEC structure and stores a type-dependent key structure in it.
67  * For a TSIG key (type is dns_tsectype_tsig), dns_tsec_create() creates a
68  * TSIG key structure from '*key' and keeps it in the structure.  For other
69  * types, this function simply retains '*key' in the structure.  In either
70  * case, the ownership of '*key' is transferred to the TSEC module; the caller
71  * must not modify or destroy it after the call to dns_tsec_create().
72  *
73  * Requires:
74  *
75  *\li	'mctx' is a valid memory context.
76  *
77  *\li	'type' is a valid value of dns_tsectype_t (see above).
78  *
79  *\li	'key' is a valid key.
80  *
81  *\li	tsecp != NULL && *tsecp == NULL.
82  *
83  * Returns:
84  *
85  *\li	#ISC_R_SUCCESS				On success.
86  *
87  *\li	Anything else				Failure.
88  */
89 
90 void
91 dns_tsec_destroy(dns_tsec_t **tsecp);
92 /*%<
93  * Destroy the TSEC structure.  The stored key is also detached or destroyed.
94  *
95  * Requires
96  *
97  *\li	'*tsecp' is a valid TSEC structure.
98  *
99  * Ensures
100  *
101  *\li	*tsecp == NULL.
102  *
103  */
104 
105 dns_tsectype_t
106 dns_tsec_gettype(dns_tsec_t *tsec);
107 /*%<
108  * Return the TSEC type of '*tsec'.
109  *
110  * Requires
111  *
112  *\li	'tsec' is a valid TSEC structure.
113  *
114  */
115 
116 void
117 dns_tsec_getkey(dns_tsec_t *tsec, void *keyp);
118 /*%<
119  * Return the TSEC key of '*tsec' in '*keyp'.
120  *
121  * Requires
122  *
123  *\li	keyp != NULL
124  *
125  * Ensures
126  *
127  *\li	*tsecp points to a valid key structure depending on the TSEC type.
128  */
129 
130 ISC_LANG_ENDDECLS
131 
132 #endif /* DNS_TSEC_H */
133