taler-exchange-httpd_secmod-helpers.h (9543B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2020-2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file taler-exchange-httpd_secmod-helpers.h 18 * @brief management of state with secmod helpers 19 * @author Christian Grothoff 20 * @author Özgür Kesim 21 */ 22 #ifndef TALER_EXCHANGE_HTTP_SECMOD_HELPERS_H 23 #define TALER_EXCHANGE_HTTP_SECMOD_HELPERS_H 24 25 #include "taler-exchange-httpd.h" 26 #include <jansson.h> 27 28 /** 29 * Setup SECMOD helper state. 30 * 31 * @return #GNUNET_OK on success 32 */ 33 enum GNUNET_GenericReturnValue 34 TEH_SECMOD_setup_key_helpers (void); 35 36 37 /** 38 * Synchronize helper state. Polls the key helper for updates. 39 */ 40 void 41 TEH_SECMOD_sync_key_helpers (void); 42 43 44 /** 45 * Destroy SECMOD helper module state. 46 */ 47 void 48 TEH_SECMOD_destroy_key_helpers (void); 49 50 51 /** 52 * Check if we have at least one SECMOD for denomination public keys. 53 * 54 * @return true if we have one 55 */ 56 bool 57 TEH_SECMOD_have_denom_sm_pub (void); 58 59 /** 60 * Check if we have at least one SECMOD for exchange signing keys. 61 * 62 * @return true if we have one 63 */ 64 bool 65 TEH_SECMOD_have_esign_sm_pub (void); 66 67 68 /** 69 * Return JSON with all of the offline security module public keys. 70 * 71 * @return JSON object 72 */ 73 json_t * 74 TEH_SECMOD_get_sm_pubs_as_json (void); 75 76 77 /** 78 * Information about a denomination on offer by the denomination helper. 79 */ 80 struct HelperDenomination 81 { 82 83 /** 84 * When will the helper start to use this key for signing? 85 */ 86 struct GNUNET_TIME_Timestamp start_time; 87 88 /** 89 * For how long will the helper allow signing? 0 if 90 * the key was revoked or purged. 91 */ 92 struct GNUNET_TIME_Relative validity_duration; 93 94 /** 95 * Hash of the full denomination key. 96 */ 97 struct TALER_DenominationHashP h_denom_pub; 98 99 /** 100 * Signature over this key from the security module's key. 101 */ 102 struct TALER_SecurityModuleSignatureP sm_sig; 103 104 /** 105 * The (full) public key. 106 */ 107 struct TALER_DenominationPublicKey denom_pub; 108 109 /** 110 * Details depend on the @e denom_pub.cipher type. 111 */ 112 union 113 { 114 115 /** 116 * Hash of the RSA key. 117 */ 118 struct TALER_RsaPubHashP h_rsa; 119 120 /** 121 * Hash of the CS key. 122 */ 123 struct TALER_CsPubHashP h_cs; 124 125 } h_details; 126 127 /** 128 * Name in configuration section for this denomination type. 129 */ 130 char *section_name; 131 132 }; 133 134 135 /** 136 * Iterate over all known denomination keys. 137 * 138 * @param cb function to call 139 * @param cb_cls closure to pass to @a cb 140 */ 141 void 142 TEH_SECMOD_iterate_denom_keys ( 143 GNUNET_CONTAINER_MultiHashMapIteratorCallback cb, 144 void *cb_cls); 145 146 147 /** 148 * Information about a signing key on offer by the esign helper. 149 */ 150 struct HelperSignkey 151 { 152 /** 153 * When will the helper start to use this key for signing? 154 */ 155 struct GNUNET_TIME_Timestamp start_time; 156 157 /** 158 * For how long will the helper allow signing? 0 if 159 * the key was revoked or purged. 160 */ 161 struct GNUNET_TIME_Relative validity_duration; 162 163 /** 164 * The public key. 165 */ 166 struct TALER_ExchangePublicKeyP exchange_pub; 167 168 /** 169 * Signature over this key from the security module's key. 170 */ 171 struct TALER_SecurityModuleSignatureP sm_sig; 172 173 }; 174 175 176 /** 177 * Iterate over all known exchange signing keys. 178 * 179 * @param cb function to call 180 * @param cb_cls closure to pass to @a cb 181 */ 182 void 183 TEH_SECMOD_iterate_esign_keys ( 184 GNUNET_CONTAINER_PeerMapIterator cb, 185 void *cb_cls); 186 187 188 /** 189 * Load fees and expiration times (!) for the denomination type configured for 190 * the denomination matching @a h_denom_pub. 191 * 192 * @param h_denom_pub hash of the denomination public key 193 * to use to derive the section name of the configuration to use 194 * @param[out] denom_pub set to the denomination public key (to be freed by caller!) 195 * @param[out] meta denomination type data to complete 196 * @return #GNUNET_OK on success, 197 * #GNUNET_NO if @a h_denom_pub is not known 198 * #GNUNET_SYSERR on hard errors 199 */ 200 enum GNUNET_GenericReturnValue 201 TEH_SECMOD_denom_load_meta ( 202 const struct TALER_DenominationHashP *h_denom_pub, 203 struct TALER_DenominationPublicKey *denom_pub, 204 struct TALER_EXCHANGEDB_DenominationKeyMetaData *meta); 205 206 207 /** 208 * Load expiration times for the given onling signing key. 209 * 210 * @param exchange_pub the online signing key 211 * @param[out] meta set to meta data about the key 212 * @return #GNUNET_OK on success 213 */ 214 enum GNUNET_GenericReturnValue 215 TEH_SECMOD_esign_load_meta (const struct TALER_ExchangePublicKeyP *exchange_pub, 216 struct TALER_EXCHANGEDB_SignkeyMetaData *meta); 217 218 219 /** 220 * Information needed to derive the CS r_pub. 221 */ 222 struct TEH_SECMOD_CsDeriveData 223 { 224 /** 225 * Hash of key to sign with. 226 */ 227 const struct TALER_DenominationHashP *h_denom_pub; 228 229 /** 230 * Nonce to use. 231 */ 232 const struct GNUNET_CRYPTO_CsSessionNonce *nonce; 233 }; 234 235 236 /** 237 * Request to derive a bunch of CS @a r_pubs using the 238 * denominations and nonces from @a cdds. 239 * 240 * @param cdds array to compute @a r_pubs from 241 * @param cdds_length length of the @a cdds array 242 * @param for_melt true if this is for a melt operation 243 * @param[out] r_pubs array where to write the result; must be of length @a cdds_length 244 * @return #TALER_EC_NONE on success 245 */ 246 enum TALER_ErrorCode 247 TEH_SECMOD_denom_cs_batch_r_pub_simple ( 248 unsigned int cdds_length, 249 const struct TEH_SECMOD_CsDeriveData cdds[static cdds_length], 250 bool for_melt, 251 struct GNUNET_CRYPTO_CSPublicRPairP r_pubs[static cdds_length]); 252 253 254 /** 255 * Request to derive a bunch of CS @a r_pubs using the 256 * denominations and nonces from @a cdds. 257 * 258 * @param num number of input elements 259 * @param h_denom_pubs array @a num of hashes of keys to sign with 260 * @param nonces array @a num of nonces to use 261 * @param for_melt true if this is for a melt operation 262 * @param[out] r_pubs array where to write the result; must be of length @a num 263 * @param[out] err_idx in case of error, the index into @e cdds that caused it 264 * @return #TALER_EC_NONE on success 265 */ 266 enum TALER_ErrorCode 267 TEH_SECMOD_denom_cs_batch_r_pub ( 268 size_t num, 269 const struct TALER_DenominationHashP h_denom_pubs[static num], 270 const struct GNUNET_CRYPTO_CsSessionNonce nonces[static num], 271 bool for_melt, 272 struct GNUNET_CRYPTO_CSPublicRPairP r_pubs[static num], 273 size_t *err_idx); 274 275 276 /** 277 * Information needed to create a blind signature. 278 */ 279 struct TEH_SECMOD_CoinSignData 280 { 281 /** 282 * Hash of key to sign with. 283 */ 284 const struct TALER_DenominationHashP *h_denom_pub; 285 286 /** 287 * Blinded planchet to sign over. 288 */ 289 const struct TALER_BlindedPlanchet *bp; 290 }; 291 292 293 /** 294 * Request to sign @a csds. 295 * 296 * @param csds array with data to blindly sign (and keys to sign with) 297 * @param csds_length length of @a csds array 298 * @param for_melt true if this is for a melt operation 299 * @param[out] bss array set to the blind signature on success; must be of length @a csds_length 300 * @return #TALER_EC_NONE on success 301 */ 302 enum TALER_ErrorCode 303 TEH_SECMOD_denom_batch_sign ( 304 unsigned int csds_length, 305 const struct TEH_SECMOD_CoinSignData csds[static csds_length], 306 bool for_melt, 307 struct TALER_BlindedDenominationSignature bss[static csds_length]); 308 309 310 /** 311 * Request to sign @a purpose. Note that this function does NOT check if @a 312 * pub is actually signed by our offline tool. Thus, clients should usually 313 * use TEH_keys_exchange_sign() and related APIs that include this check. 314 * 315 * @param purpose message to sign 316 * @param[out] pub set to public key used to sign 317 * @param[out] sig set to resulting signature 318 * @return #TALER_EC_NONE on success 319 */ 320 enum TALER_ErrorCode 321 TEH_SECMOD_exchange_sign ( 322 const struct GNUNET_CRYPTO_SignaturePurpose *purpose, 323 struct TALER_ExchangePublicKeyP *pub, 324 struct TALER_ExchangeSignatureP *sig); 325 326 327 /** 328 * Check if we lost the private denomination key for the 329 * denomination @a h_denom_pub 330 * 331 * @param h_denom_pub hash over the public key 332 * @return true if we lost the private key 333 */ 334 bool 335 TEH_SECMOD_denom_priv_check_lost ( 336 const struct TALER_DenominationHashP *h_denom_pub); 337 338 339 /** 340 * Revoke the public key associated with @a h_denom_pub. 341 * This function should be called AFTER the database was 342 * updated, as it also triggers #TEH_keys_update_states(). 343 * 344 * Note that the actual revocation happens asynchronously and 345 * may thus fail silently. To verify that the revocation succeeded, 346 * clients must watch for the associated change to the key state. 347 * 348 * @param h_denom_pub hash of the public key to revoke 349 */ 350 void 351 TEH_SECMOD_denom_revoke ( 352 const struct TALER_DenominationHashP *h_denom_pub); 353 354 355 /** 356 * Revoke the given exchange's signing key. 357 * This function should be called AFTER the database was 358 * updated, as it also triggers #TEH_keys_update_states(). 359 * 360 * Note that the actual revocation happens asynchronously and 361 * may thus fail silently. To verify that the revocation succeeded, 362 * clients must watch for the associated change to the key state. 363 * 364 * @param exchange_pub key to revoke 365 */ 366 void 367 TEH_SECMOD_esign_revoke ( 368 const struct TALER_ExchangePublicKeyP *exchange_pub); 369 370 371 #endif