1 /* $NetBSD: tsec.h,v 1.5 2022/09/23 12:15:30 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 49 ISC_LANG_BEGINDECLS 50 51 /*** 52 *** Types 53 ***/ 54 55 /*% 56 * Transaction security types. 57 */ 58 typedef enum { 59 dns_tsectype_none, 60 dns_tsectype_tsig, 61 dns_tsectype_sig0 62 } dns_tsectype_t; 63 64 isc_result_t 65 dns_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 92 void 93 dns_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 107 dns_tsectype_t 108 dns_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 118 void 119 dns_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 132 ISC_LANG_ENDDECLS 133 134 #endif /* DNS_TSEC_H */ 135