post-private-otp-devices.h (7484B)
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 Lesser General Public License as published by the Free Software 7 Foundation; either version 2.1, 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 Lesser General Public License for more details. 12 13 You should have received a copy of the GNU Lesser General Public License along with 14 TALER; see the file COPYING.LGPL. If not, see 15 <http://www.gnu.org/licenses/> 16 */ 17 /** 18 * @file src/include/taler/merchant/post-private-otp-devices.h 19 * @brief C interface for the POST /private/otp-devices endpoint 20 * @author Christian Grothoff 21 */ 22 #ifndef _TALER_MERCHANT__POST_PRIVATE_OTP_DEVICES_H 23 #define _TALER_MERCHANT__POST_PRIVATE_OTP_DEVICES_H 24 25 #include <taler/merchant/common.h> 26 27 28 /** 29 * Handle for a POST /private/otp-devices request. 30 */ 31 struct TALER_MERCHANT_PostPrivateOtpDevicesHandle; 32 33 34 /** 35 * Response details for a POST /private/otp-devices request. 36 */ 37 struct TALER_MERCHANT_PostPrivateOtpDevicesResponse 38 { 39 40 /** 41 * HTTP response details. 42 */ 43 struct TALER_MERCHANT_HttpResponse hr; 44 45 }; 46 47 48 /** 49 * Possible options we can set for the POST /private/otp-devices request. 50 */ 51 enum TALER_MERCHANT_PostPrivateOtpDevicesOption 52 { 53 /** 54 * End of list of options. 55 */ 56 TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_OPTION_END = 0, 57 58 /** 59 * Set the initial OTP counter value (for HOTP). 60 */ 61 TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_OPTION_OTP_CTR 62 63 }; 64 65 66 /** 67 * Value for an option for the POST /private/otp-devices request. 68 */ 69 struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue 70 { 71 72 /** 73 * Type of the option being set. 74 */ 75 enum TALER_MERCHANT_PostPrivateOtpDevicesOption option; 76 77 /** 78 * Specific option value. 79 */ 80 union 81 { 82 83 /** 84 * Value if @e option is 85 * #TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_OPTION_OTP_CTR. 86 */ 87 uint64_t otp_ctr; 88 89 } details; 90 91 }; 92 93 94 /** 95 * Set up POST /private/otp-devices operation. 96 * Note that you must explicitly start the operation after 97 * possibly setting options. 98 * 99 * @param ctx the context 100 * @param url base URL of the merchant backend 101 * @param otp_device_id identifier for the new OTP device 102 * @param otp_device_description human-readable description 103 * @param otp_key base32-encoded OTP secret key 104 * @param otp_algorithm OTP algorithm to use 105 * @return handle to operation 106 */ 107 struct TALER_MERCHANT_PostPrivateOtpDevicesHandle * 108 TALER_MERCHANT_post_private_otp_devices_create ( 109 struct GNUNET_CURL_Context *ctx, 110 const char *url, 111 const char *otp_device_id, 112 const char *otp_device_description, 113 const char *otp_key, 114 enum TALER_MerchantConfirmationAlgorithm otp_algorithm); 115 116 117 /** 118 * Terminate the list of the options. 119 * 120 * @return the terminating object of struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue 121 */ 122 #define TALER_MERCHANT_post_private_otp_devices_option_end_() \ 123 (const struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue) \ 124 { \ 125 .option = TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_OPTION_END \ 126 } 127 128 /** 129 * Set the initial counter value (for HOTP). 130 * 131 * @param c the counter value 132 * @return representation of the option as a struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue 133 */ 134 #define TALER_MERCHANT_post_private_otp_devices_option_otp_ctr(c) \ 135 (const struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue) \ 136 { \ 137 .option = \ 138 TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_OPTION_OTP_CTR, \ 139 .details.otp_ctr = (c) \ 140 } 141 142 143 /** 144 * Set the requested options for the operation. 145 * 146 * If any option fail other options may be or may be not applied. 147 * 148 * @param ppoh the request to set the options for 149 * @param num_options length of the @a options array 150 * @param options an array of options 151 * @return #GNUNET_OK on success, 152 * #GNUNET_NO on failure, 153 * #GNUNET_SYSERR on internal error 154 */ 155 enum GNUNET_GenericReturnValue 156 TALER_MERCHANT_post_private_otp_devices_set_options_ ( 157 struct TALER_MERCHANT_PostPrivateOtpDevicesHandle *ppoh, 158 unsigned int num_options, 159 const struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue *options); 160 161 162 /** 163 * Set the requested options for the operation. 164 * 165 * If any option fail other options may be or may be not applied. 166 * 167 * It should be used with helpers that create required options, for example: 168 * 169 * TALER_MERCHANT_post_private_otp_devices_set_options ( 170 * ppoh, 171 * TALER_MERCHANT_post_private_otp_devices_option_otp_ctr (42)); 172 * 173 * @param ppoh the request to set the options for 174 * @param ... the list of the options, each option must be created 175 * by helpers TALER_MERCHANT_post_private_otp_devices_option_NAME(VALUE) 176 * @return #GNUNET_OK on success, 177 * #GNUNET_NO on failure, 178 * #GNUNET_SYSERR on internal error 179 */ 180 #define TALER_MERCHANT_post_private_otp_devices_set_options(ppoh,...) \ 181 TALER_MERCHANT_post_private_otp_devices_set_options_ ( \ 182 ppoh, \ 183 TALER_MERCHANT_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 184 ((const struct TALER_MERCHANT_PostPrivateOtpDevicesOptionValue[]) \ 185 {__VA_ARGS__, TALER_MERCHANT_post_private_otp_devices_option_end_ () \ 186 } \ 187 )) 188 189 190 #ifndef TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_RESULT_CLOSURE 191 /** 192 * Type of the closure used by 193 * the #TALER_MERCHANT_PostPrivateOtpDevicesCallback. 194 */ 195 #define TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_RESULT_CLOSURE void 196 #endif /* TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_RESULT_CLOSURE */ 197 198 /** 199 * Callback for a POST /private/otp-devices request. 200 * 201 * @param cls closure 202 * @param odr response details 203 */ 204 typedef void 205 (*TALER_MERCHANT_PostPrivateOtpDevicesCallback)( 206 TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_RESULT_CLOSURE *cls, 207 const struct TALER_MERCHANT_PostPrivateOtpDevicesResponse *odr); 208 209 210 /** 211 * Start POST /private/otp-devices operation. 212 * 213 * @param[in,out] ppoh operation to start 214 * @param cb function to call with the merchant's result 215 * @param cb_cls closure for @a cb 216 * @return status code, #TALER_EC_NONE on success 217 */ 218 enum TALER_ErrorCode 219 TALER_MERCHANT_post_private_otp_devices_start ( 220 struct TALER_MERCHANT_PostPrivateOtpDevicesHandle *ppoh, 221 TALER_MERCHANT_PostPrivateOtpDevicesCallback cb, 222 TALER_MERCHANT_POST_PRIVATE_OTP_DEVICES_RESULT_CLOSURE *cb_cls); 223 224 225 /** 226 * Cancel POST /private/otp-devices operation. This function must not be 227 * called by clients after the TALER_MERCHANT_PostPrivateOtpDevicesCallback 228 * has been invoked (as in those cases it'll be called internally by the 229 * implementation already). 230 * 231 * @param[in] ppoh operation to cancel 232 */ 233 void 234 TALER_MERCHANT_post_private_otp_devices_cancel ( 235 struct TALER_MERCHANT_PostPrivateOtpDevicesHandle *ppoh); 236 237 238 #endif /* _TALER_MERCHANT__POST_PRIVATE_OTP_DEVICES_H */