Home | History | Annotate | Line # | Download | only in dns 
      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 
     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