get-management-keys.h (6712B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-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 include/taler/taler-exchange/get-management-keys.h 18 * @brief C interface for GET /management/keys 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_MANAGEMENT_KEYS_H 22 #define _TALER_EXCHANGE__GET_MANAGEMENT_KEYS_H 23 24 #include <taler/taler-exchange/common.h> 25 26 /** 27 * Handle for an operation to GET /management/keys. 28 */ 29 struct TALER_EXCHANGE_GetManagementKeysHandle; 30 31 32 /** 33 * @brief Future signing public key of the exchange. 34 */ 35 struct TALER_EXCHANGE_FutureSigningPublicKey 36 { 37 /** 38 * The signing public key. 39 */ 40 struct TALER_ExchangePublicKeyP key; 41 42 /** 43 * Signature by the security module affirming it owns this key. 44 */ 45 struct TALER_SecurityModuleSignatureP signkey_secmod_sig; 46 47 /** 48 * Validity start time. 49 */ 50 struct GNUNET_TIME_Timestamp valid_from; 51 52 /** 53 * Validity expiration time (how long the exchange may use it). 54 */ 55 struct GNUNET_TIME_Timestamp valid_until; 56 57 /** 58 * Validity expiration time for legal disputes. 59 */ 60 struct GNUNET_TIME_Timestamp valid_legal; 61 }; 62 63 64 /** 65 * @brief Public information about a future denomination key of the exchange. 66 */ 67 struct TALER_EXCHANGE_FutureDenomPublicKey 68 { 69 /** 70 * The public key. 71 */ 72 struct TALER_DenominationPublicKey key; 73 74 /** 75 * Signature by the security module affirming it owns this key. 76 */ 77 struct TALER_SecurityModuleSignatureP denom_secmod_sig; 78 79 /** 80 * Timestamp indicating when the denomination key becomes valid. 81 */ 82 struct GNUNET_TIME_Timestamp valid_from; 83 84 /** 85 * Timestamp indicating when the denomination key can no longer 86 * be used for new withdrawals. 87 */ 88 struct GNUNET_TIME_Timestamp withdraw_valid_until; 89 90 /** 91 * Timestamp indicating when coins of this denomination become invalid. 92 */ 93 struct GNUNET_TIME_Timestamp expire_deposit; 94 95 /** 96 * When do signatures with this denomination key become invalid? 97 * After this point these signatures cannot be used in legal disputes. 98 */ 99 struct GNUNET_TIME_Timestamp expire_legal; 100 101 /** 102 * The value of this denomination. 103 */ 104 struct TALER_Amount value; 105 106 /** 107 * The applicable fee for withdrawing a coin of this denomination. 108 */ 109 struct TALER_Amount fee_withdraw; 110 111 /** 112 * The applicable fee to spend a coin of this denomination. 113 */ 114 struct TALER_Amount fee_deposit; 115 116 /** 117 * The applicable fee to melt/refresh a coin of this denomination. 118 */ 119 struct TALER_Amount fee_refresh; 120 121 /** 122 * The applicable fee to refund a coin of this denomination. 123 */ 124 struct TALER_Amount fee_refund; 125 126 }; 127 128 129 /** 130 * @brief Information about future keys from the exchange. 131 */ 132 struct TALER_EXCHANGE_FutureKeys 133 { 134 /** 135 * Array of the exchange's future online signing keys. 136 */ 137 struct TALER_EXCHANGE_FutureSigningPublicKey *sign_keys; 138 139 /** 140 * Array of the exchange's future denomination keys. 141 */ 142 struct TALER_EXCHANGE_FutureDenomPublicKey *denom_keys; 143 144 /** 145 * Public key of the signkey security module. 146 */ 147 struct TALER_SecurityModulePublicKeyP signkey_secmod_public_key; 148 149 /** 150 * Public key of the RSA denomination security module. 151 */ 152 struct TALER_SecurityModulePublicKeyP denom_secmod_public_key; 153 154 /** 155 * Public key of the CS denomination security module. 156 */ 157 struct TALER_SecurityModulePublicKeyP denom_secmod_cs_public_key; 158 159 /** 160 * Offline master public key used by this exchange. 161 */ 162 struct TALER_MasterPublicKeyP master_pub; 163 164 /** 165 * Length of the @e sign_keys array. 166 */ 167 unsigned int num_sign_keys; 168 169 /** 170 * Length of the @e denom_keys array. 171 */ 172 unsigned int num_denom_keys; 173 174 }; 175 176 177 /** 178 * Response from a GET /management/keys request. 179 */ 180 struct TALER_EXCHANGE_GetManagementKeysResponse 181 { 182 /** 183 * HTTP response data. 184 */ 185 struct TALER_EXCHANGE_HttpResponse hr; 186 187 /** 188 * Response details depending on the HTTP status. 189 */ 190 union 191 { 192 /** 193 * Details if HTTP status is #MHD_HTTP_OK. 194 */ 195 struct 196 { 197 /** 198 * Information about the various future keys used by the exchange. 199 */ 200 struct TALER_EXCHANGE_FutureKeys keys; 201 202 } ok; 203 } details; 204 205 }; 206 207 #ifndef TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE 208 /** 209 * Type of the closure used by 210 * the #TALER_EXCHANGE_GetManagementKeysCallback. 211 */ 212 #define TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE void 213 #endif /* TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE */ 214 215 /** 216 * Type of the function that receives the result of a 217 * GET /management/keys request. 218 * 219 * @param cls closure 220 * @param result result returned by the HTTP server 221 */ 222 typedef void 223 (*TALER_EXCHANGE_GetManagementKeysCallback)( 224 TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE *cls, 225 const struct TALER_EXCHANGE_GetManagementKeysResponse *result); 226 227 228 /** 229 * Set up GET /management/keys operation. 230 * Note that you must explicitly start the operation after setup. 231 * 232 * @param ctx the context 233 * @param url base URL of the exchange 234 * @return handle to operation 235 */ 236 struct TALER_EXCHANGE_GetManagementKeysHandle * 237 TALER_EXCHANGE_get_management_keys_create ( 238 struct GNUNET_CURL_Context *ctx, 239 const char *url); 240 241 242 /** 243 * Start GET /management/keys operation. 244 * 245 * @param[in,out] gmkh operation to start 246 * @param cb function to call with the exchange's result 247 * @param cb_cls closure for @a cb 248 * @return status code, #TALER_EC_NONE on success 249 */ 250 enum TALER_ErrorCode 251 TALER_EXCHANGE_get_management_keys_start ( 252 struct TALER_EXCHANGE_GetManagementKeysHandle *gmkh, 253 TALER_EXCHANGE_GetManagementKeysCallback cb, 254 TALER_EXCHANGE_GET_MANAGEMENT_KEYS_RESULT_CLOSURE *cb_cls); 255 256 257 /** 258 * Cancel GET /management/keys operation. This function must not be called 259 * by clients after the TALER_EXCHANGE_GetManagementKeysCallback has been 260 * invoked (as in those cases it'll be called internally by the 261 * implementation already). 262 * 263 * @param[in] gmkh operation to cancel 264 */ 265 void 266 TALER_EXCHANGE_get_management_keys_cancel ( 267 struct TALER_EXCHANGE_GetManagementKeysHandle *gmkh); 268 269 270 #endif /* _TALER_EXCHANGE__GET_MANAGEMENT_KEYS_H */