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