1 /* $NetBSD: keystore.h,v 1.2 2025/01/26 16:25:27 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 #pragma once 17 18 /***** 19 ***** Module Info 20 *****/ 21 22 /*! \file dns/keystore.h 23 * \brief 24 * DNSSEC Key Store 25 * 26 * A key store defines where to store DNSSEC keys. 27 */ 28 29 /* Add -DDNS_KEYSTORE_TRACE=1 to CFLAGS for detailed reference tracing */ 30 31 #include <isc/lang.h> 32 #include <isc/magic.h> 33 #include <isc/mutex.h> 34 #include <isc/refcount.h> 35 36 #include <dns/types.h> 37 38 #include <dst/dst.h> 39 40 ISC_LANG_BEGINDECLS 41 42 /* Key store */ 43 struct dns_keystore { 44 unsigned int magic; 45 isc_mem_t *mctx; 46 const char *name; 47 const char *engine; 48 49 /* Internals. */ 50 isc_mutex_t lock; 51 52 /* Locked by themselves. */ 53 isc_refcount_t references; 54 55 /* Under owner's locking control. */ 56 ISC_LINK(struct dns_keystore) link; 57 58 /* Configuration values */ 59 char *directory; 60 char *pkcs11uri; 61 }; 62 63 #define DNS_KEYSTORE_MAGIC ISC_MAGIC('K', 'E', 'Y', 'S') 64 #define DNS_KEYSTORE_VALID(ks) ISC_MAGIC_VALID(ks, DNS_KEYSTORE_MAGIC) 65 66 #define DNS_KEYSTORE_KEYDIRECTORY "key-directory" 67 68 isc_result_t 69 dns_keystore_create(isc_mem_t *mctx, const char *name, const char *engine, 70 dns_keystore_t **kspp); 71 /*%< 72 * Create a key store. 73 * 74 * Requires: 75 * 76 *\li 'mctx' is a valid memory context. 77 * 78 *\li 'name' is a valid C string. 79 * 80 *\li 'engine' is the name of the OpenSSL engine to use, may be NULL. 81 * 82 *\li kspp != NULL && *kspp == NULL 83 * 84 * Returns: 85 * 86 *\li #ISC_R_SUCCESS 87 *\li #ISC_R_NOMEMORY 88 * 89 *\li Other errors are possible. 90 */ 91 92 const char * 93 dns_keystore_name(dns_keystore_t *keystore); 94 /*%< 95 * Get keystore name. 96 * 97 * Requires: 98 * 99 *\li 'keystore' is a valid keystore. 100 * 101 * Returns: 102 * 103 *\li name of 'keystore'. 104 */ 105 106 const char * 107 dns_keystore_engine(dns_keystore_t *keystore); 108 /*%< 109 * Get keystore engine. 110 * 111 * Requires: 112 * 113 *\li 'keystore' is a valid keystore. 114 * 115 * Returns: 116 * 117 *\li engine of 'keystore'. May be NULL. 118 */ 119 120 const char * 121 dns_keystore_directory(dns_keystore_t *keystore, const char *keydir); 122 /*%< 123 * Get keystore directory. If 'keystore' is NULL or 'keystore->directory' is 124 *NULL, return 'keydir'. 125 * 126 * Returns: 127 * 128 *\li directory of 'keystore'. 129 */ 130 131 void 132 dns_keystore_setdirectory(dns_keystore_t *keystore, const char *dir); 133 /*%< 134 * Set keystore directory. 135 * 136 * Requires: 137 * 138 *\li 'keystore' is a valid keystore. 139 * 140 */ 141 142 const char * 143 dns_keystore_pkcs11uri(dns_keystore_t *keystore); 144 /*%< 145 * Get keystore PKCS#11 URI. 146 * 147 * Requires: 148 * 149 *\li 'keystore' is a valid keystore. 150 * 151 * Returns: 152 * 153 *\li PKCS#11 URI of 'keystore'. 154 */ 155 156 void 157 dns_keystore_setpkcs11uri(dns_keystore_t *keystore, const char *uri); 158 /*%< 159 * Set keystore PKCS#11 URI. 160 * 161 * Requires: 162 * 163 *\li 'keystore' is a valid keystore. 164 * 165 */ 166 167 isc_result_t 168 dns_keystore_keygen(dns_keystore_t *keystore, const dns_name_t *origin, 169 const char *policy, dns_rdataclass_t rdclass, 170 isc_mem_t *mctx, uint32_t alg, int size, int flags, 171 dst_key_t **dstkey); 172 /*%< 173 * Create a DNSSEC key pair. Set keystore PKCS#11 URI. 174 * 175 * Requires: 176 * 177 *\li 'keystore' is a valid keystore. 178 * 179 *\li 'origin' is a valid DNS owner name. 180 * 181 *\li 'policy' is the name of the DNSSEC policy. 182 * 183 *\li 'mctx' is a valid memory context. 184 * 185 *\li 'dstkey' is not NULL and '*dstkey' is NULL. 186 * 187 */ 188 189 isc_result_t 190 dns_keystorelist_find(dns_keystorelist_t *list, const char *name, 191 dns_keystore_t **kspp); 192 /*%< 193 * Search for a keystore with name 'name' in 'list'. 194 * If found, '*kspp' is (strongly) attached to it. 195 * 196 * Requires: 197 * 198 *\li 'kspp' points to a NULL dns_keystore_t *. 199 * 200 * Returns: 201 * 202 *\li #ISC_R_SUCCESS A matching keystore was found. 203 *\li #ISC_R_NOTFOUND No matching keystore was found. 204 */ 205 206 #ifdef DNS_KEYSTORE_TRACE 207 /* Compatibility macros */ 208 #define dns_keystore_attach(ks, ksp) \ 209 dns_keystore__attach(ks, ksp, __func__, __FILE__, __LINE__) 210 #define dns_keystore_detach(ksp) \ 211 dns_keystore__detach(ksp, __func__, __FILE__, __LINE__) 212 #define dns_keystore_ref(ptr) \ 213 dns_keystore__ref(ptr, __func__, __FILE__, __LINE__) 214 #define dns_keystore_unref(ptr) \ 215 dns_keystore__unref(ptr, __func__, __FILE__, __LINE__) 216 217 ISC_REFCOUNT_TRACE_DECL(dns_keystore); 218 #else 219 ISC_REFCOUNT_DECL(dns_keystore); 220 #endif /* DNS_KEYSTORE_TRACE */ 221 222 ISC_LANG_ENDDECLS 223
Indexes created Sat Oct 24 00:25:45 UTC 2026