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