diff options
Diffstat (limited to 'src/include/taler_signatures.h')
| -rw-r--r-- | src/include/taler_signatures.h | 257 |
1 files changed, 187 insertions, 70 deletions
diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h index 8363c23dd..4e9418966 100644 --- a/src/include/taler_signatures.h +++ b/src/include/taler_signatures.h @@ -40,53 +40,47 @@ */ #define TALER_CNC_KAPPA 3 +/*********************************************/ +/* Mint offline signatures (with master key) */ +/*********************************************/ /** - * Purpose for signing public keys signed - * by the mint master key. + * Purpose for signing public keys signed by the mint master key. */ -#define TALER_SIGNATURE_MINT_SIGNING_KEY_VALIDITY 1 +#define TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY 1 /** - * Purpose for denomination keys signed - * by the mint master key. + * Purpose for denomination keys signed by the mint master key. */ -#define TALER_SIGNATURE_MINT_DENOMINATION_KEY_VALIDITY 2 +#define TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY 2 -/** - * Purpose for the state of a reserve, - * signed by the mint's signing key. - */ -#define TALER_SIGNATURE_MINT_RESERVE_STATUS 3 -/** - * Signature where the reserve key - * confirms a withdraw request. - */ -#define TALER_SIGNATURE_RESERVE_WITHDRAW_REQUEST 4 +/*********************************************/ +/* Mint online signatures (with signing key) */ +/*********************************************/ /** - * Signature using a coin key confirming the melting of - * a coin. + * Purpose for the state of a reserve, signed by the mint's signing + * key. */ -#define TALER_SIGNATURE_COIN_MELT 5 +#define TALER_SIGNATURE_MINT_RESERVE_STATUS 32 /** - * Signature where the mint (current signing key) - * confirms the no-reveal index for cut-and-choose and - * the validity of the melted coins. + * Signature where the Mint confirms a deposit request. */ -#define TALER_SIGNATURE_MINT_MELT_RESPONSE 6 +#define TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT 33 /** - * Signature where the Mint confirms a deposit request. + * Signature where the mint (current signing key) confirms the + * no-reveal index for cut-and-choose and the validity of the melted + * coins. */ -#define TALER_SIGNATURE_COIN_DEPOSIT 7 +#define TALER_SIGNATURE_MINT_CONFIRM_MELT 34 /** * Signature where the Mint confirms the full /keys response set. */ -#define TALER_SIGNATURE_MINT_KEY_SET 8 +#define TALER_SIGNATURE_MINT_KEY_SET 35 /***********************/ @@ -94,26 +88,34 @@ /***********************/ /** - * Signature where the merchant confirms a contract + * Signature where the merchant confirms a contract (to the customer). */ #define TALER_SIGNATURE_MERCHANT_CONTRACT 101 +/** + * Signature where the merchant confirms a refund (of a coin). + */ +#define TALER_SIGNATURE_MERCHANT_REFUND 102 + + /*********************/ /* Wallet signatures */ /*********************/ /** - * Signature made by the wallet of a user to confirm a deposit permission - * FIXME: this is #TALER_SIGNATURE_COIN_DEPOSIT already! + * Signature where the reserve key confirms a withdraw request. */ -#define TALER_SIGNATURE_WALLET_DEPOSIT 201 +#define TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW 200 /** - * Signature made by the wallet of a user to confirm a incremental - * deposit permission. - * FIXME: this MIGHT also be #TALER_SIGNATURE_COIN_DEPOSIT already! + * Signature made by the wallet of a user to confirm a deposit of a coin. */ -#define TALER_SIGNATURE_WALLET_DEPOSIT_INCREMENTAL 202 +#define TALER_SIGNATURE_WALLET_COIN_DEPOSIT 201 + +/** + * Signature using a coin key confirming the melting of a coin. + */ +#define TALER_SIGNATURE_WALLET_COIN_MELT 202 @@ -127,7 +129,8 @@ struct TALER_WithdrawRequestPS { /** - * Purpose must be #TALER_SIGNATURE_RESERVE_WITHDRAW_REQUEST. + * Purpose must be #TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. + * Used with an EdDSA signature of a `struct TALER_ReservePublicKeyP`. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -165,7 +168,8 @@ struct TALER_WithdrawRequestPS struct TALER_DepositRequestPS { /** - * Purpose must be #TALER_SIGNATURE_WALLET_DEPOSIT + * Purpose must be #TALER_SIGNATURE_WALLET_COIN_DEPOSIT. + * Used for an ECDSA signature with the `union TALER_CoinSpendPublicKeyP`. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -180,20 +184,68 @@ struct TALER_DepositRequestPS struct GNUNET_HashCode h_wire; /** + * Time when this request was generated. Used, for example, to + * assess when (roughly) the income was achieved for tax purposes. + * Note that the Mint will only check that the timestamp is not "too + * far" into the future (i.e. several days). The fact that the + * timestamp falls within the validity period of the coin's + * denomination key is irrelevant for the validity of the deposit + * request, as obviously the customer and merchant could conspire to + * set any timestamp. Also, the Mint must accept very old deposit + * requests, as the merchant might have been unable to transmit the + * deposit request in a timely fashion (so back-dating is not + * prevented). + */ + struct GNUNET_TIME_AbsoluteNBO timestamp; + + /** + * How much time does the merchant have to issue a refund request? + * Zero if refunds are not allowed. After this time, the coin + * cannot be refunded. + */ + struct GNUNET_TIME_AbsoluteNBO refund_deadline; + + /** * Merchant-generated transaction ID to detect duplicate - * transactions. + * transactions. The merchant must communicate a merchant-unique ID + * to the customer for each transaction. Note that different coins + * that are part of the same transaction can use the same + * transaction ID. The transaction ID is useful for later disputes, + * and the merchant's contract offer (@e h_contract) with the + * customer should include the offer's term and transaction ID + * signed with a key from the merchant. */ uint64_t transaction_id GNUNET_PACKED; /** - * Amount to be deposited, including fee. + * Amount to be deposited, including deposit fee charged by the + * mint. This is the total amount that the coin's value at the mint + * will be reduced by. */ struct TALER_AmountNBO amount_with_fee; - /* FIXME: we should probably also include the value of - the depositing fee here as well! */ /** - * The coin's public key. + * Depositing fee charged by the mint. This must match the Mint's + * denomination key's depositing fee. If the client puts in an + * invalid deposit fee (too high or too low) that does not match the + * Mint's denomination key, the deposit operation is invalid and + * will be rejected by the mint. The @e amount_with_fee minus the + * @e deposit_fee is the amount that will be transferred to the + * account identified by @e h_wire. + */ + struct TALER_AmountNBO deposit_fee; + + /** + * The Merchant's public key. Allows the merchant to later refund + * the transaction. All zeros if nobody is allowed to refund the + * transaction later. + */ + struct TALER_MerchantPublicKeyP merchant; + + /** + * The coin's public key. This is the value that must have been + * signed (blindly) by the Mint. The deposit request is to be + * signed by the corresponding private key (using ECDSA). */ union TALER_CoinSpendPublicKeyP coin_pub; @@ -207,7 +259,8 @@ struct TALER_DepositRequestPS struct TALER_DepositConfirmationPS { /** - * Purpose must be #TALER_SIGNATURE_COIN_DEPOSIT + * Purpose must be #TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT. Signed + * by a `struct TALER_MintPublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -228,20 +281,36 @@ struct TALER_DepositConfirmationPS uint64_t transaction_id GNUNET_PACKED; /** - * Amount to be deposited, including fee. + * Time when this confirmation was generated. */ - struct TALER_AmountNBO amount_with_fee; + struct GNUNET_TIME_AbsoluteNBO timestamp; + + /** + * How much time does the @e merchant have to issue a refund + * request? Zero if refunds are not allowed. After this time, the + * coin cannot be refunded. Note that the wire transfer will not be + * performed by the mint until the refund deadline. This value + * is taken from the original deposit request. + */ + struct GNUNET_TIME_AbsoluteNBO refund_deadline; - /* FIXME: we should probably also include the value of - the depositing fee here as well! */ + /** + * Amount to be deposited, excluding fee. Calculated from the + * amount with fee and the fee from the deposit request. + */ + struct TALER_AmountNBO amount_without_fee; /** - * The coin's public key. + * The coin's public key. This is the value that must have been + * signed (blindly) by the Mint. The deposit request is to be + * signed by the corresponding private key (using ECDSA). */ union TALER_CoinSpendPublicKeyP coin_pub; /** - * The Merchant's public key. + * The Merchant's public key. Allows the merchant to later refund + * the transaction. All zeros if nobody is allowed to refund the + * transaction later. */ struct TALER_MerchantPublicKeyP merchant; @@ -249,13 +318,14 @@ struct TALER_DepositConfirmationPS /** - * Message signed by a coin to indicate that the coin should - * be melted. + * Message signed by a coin to indicate that the coin should be + * melted. */ struct TALER_RefreshMeltCoinAffirmationPS { /** - * Purpose is #TALER_SIGNATURE_COIN_MELT. + * Purpose is #TALER_SIGNATURE_WALLET_COIN_MELT. + * Used for an ECDSA signature with the `union TALER_CoinSpendPublicKeyP`. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -274,11 +344,21 @@ struct TALER_RefreshMeltCoinAffirmationPS */ struct TALER_AmountNBO amount_with_fee; - /* FIXME: we should probably also include the value of - the melting fee here as well! */ + /** + * Melting fee charged by the mint. This must match the Mint's + * denomination key's melting fee. If the client puts in an invalid + * melting fee (too high or too low) that does not match the Mint's + * denomination key, the melting operation is invalid and will be + * rejected by the mint. The @e amount_with_fee minus the @e + * melt_fee is the amount that will be credited to the melting + * session. + */ + struct TALER_AmountNBO melt_fee; /** - * The coin's public key. + * The coin's public key. This is the value that must have been + * signed (blindly) by the Mint. The deposit request is to be + * signed by the corresponding private key (using ECDSA). */ union TALER_CoinSpendPublicKeyP coin_pub; }; @@ -293,7 +373,8 @@ struct TALER_RefreshMeltCoinAffirmationPS struct TALER_RefreshMeltConfirmationPS { /** - * Purpose is #TALER_SIGNATURE_MINT_MELT_RESPONSE. + * Purpose is #TALER_SIGNATURE_MINT_CONFIRM_MELT. Signed + * by a `struct TALER_MintPublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -303,7 +384,8 @@ struct TALER_RefreshMeltConfirmationPS struct GNUNET_HashCode session_hash; /** - * Index that the client will not have to reveal. + * Index that the client will not have to reveal, in NBO. + * Must be smaller than #TALER_CNC_KAPPA. */ uint16_t noreveal_index GNUNET_PACKED; }; @@ -322,7 +404,7 @@ struct TALER_MintSigningKeyValidityPS struct TALER_MasterSignatureP signature; /** - * Purpose is #TALER_SIGNATURE_MINT_SIGNING_KEY_VALIDITY. + * Purpose is #TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -338,14 +420,25 @@ struct TALER_MintSigningKeyValidityPS struct GNUNET_TIME_AbsoluteNBO start; /** - * When does this signing key expire? Note: This is - * currently when the Mint will definitively stop using it. - * This does not mean that all signatures with tkey key are - * afterwards invalid. + * When does this signing key expire? Note: This is currently when + * the Mint will definitively stop using it. Signatures made with + * the key remain valid until @e end. When checking validity periods, + * clients should allow for some overlap between keys and tolerate + * the use of either key during the overlap time (due to the + * possibility of clock skew). */ struct GNUNET_TIME_AbsoluteNBO expire; /** + * When do signatures with this signing key become invalid? After + * this point, these signatures cannot be used in (legal) disputes + * anymore, as the Mint is then allowed to destroy its side of the + * evidence. @e end is expected to be significantly larger than @e + * expire (by a year or more). + */ + struct GNUNET_TIME_AbsoluteNBO end; + + /** * The public online signing key that the mint will use * between @e start and @e expire. */ @@ -362,7 +455,8 @@ struct TALER_MintKeySetPS { /** - * Purpose is #TALER_SIGNATURE_MINT_KEY_SET + * Purpose is #TALER_SIGNATURE_MINT_KEY_SET. Signed + * by a `struct TALER_MintPublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -372,7 +466,11 @@ struct TALER_MintKeySetPS struct GNUNET_TIME_AbsoluteNBO list_issue_date; /** - * Hash over the "inner" JSON with the key set. + * Hash over the "inner" JSON with the key set. FIXME: The use of + * JSON as what is being signed here is a bit of a hack, as the + * result depends on the JSON indentation and being canonical. + * We should consider using a more well-defined binary format to + * sign. (#3739) */ struct GNUNET_HashCode hc; }; @@ -385,13 +483,12 @@ struct TALER_MintKeySetPS struct TALER_DenominationKeyValidityPS { /** - * Signature over this struct to affirm the validity - * of the key. + * Signature over this struct to affirm the validity of the key. */ struct TALER_MasterSignatureP signature; /** - * Purpose is #TALER_SIGNATURE_MINT_DENOMINATION_KEY_VALIDITY. + * Purpose is #TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -407,8 +504,16 @@ struct TALER_DenominationKeyValidityPS struct GNUNET_TIME_AbsoluteNBO start; /** - * The mint will sign fresh coins between @e start and - * this time. + * The mint will sign fresh coins between @e start and this time. + * @e expire_withdraw will be somewhat larger than @e start to + * ensure a sufficiently large anonymity set, while also allowing + * the Mint to limit the financial damage in case of a key being + * compromised. Thus, mints with low volume are expected to have a + * longer withdraw period (@e expire_withdraw - @e start) than mints + * with high transaction volume. The period may also differ between + * types of coins. A mint may also have a few denomination keys + * with the same value with overlapping validity periods, to address + * issues such as clock skew. */ struct GNUNET_TIME_AbsoluteNBO expire_withdraw; @@ -418,11 +523,22 @@ struct TALER_DenominationKeyValidityPS * mint will refuse transactions involving this key as it will * "drop" the table with double-spending information (shortly after) * this time. Note that wallets should refresh coins significantly - * before this time to be on the safe side. + * before this time to be on the safe side. @e expire_spend must be + * significantly larger than @e expire_withdraw (by months or even + * years). */ struct GNUNET_TIME_AbsoluteNBO expire_spend; /** + * When do signatures with this denomination key become invalid? + * After this point, these signatures cannot be used in (legal) + * disputes anymore, as the Mint is then allowed to destroy its side + * of the evidence. @e expire_legal is expected to be significantly + * larger than @e expire_spend (by a year or more). + */ + struct GNUNET_TIME_AbsoluteNBO expire_legal; + + /** * The value of the coins signed with this denomination key. */ struct TALER_AmountNBO value; @@ -446,7 +562,8 @@ struct TALER_DenominationKeyValidityPS struct TALER_AmountNBO fee_refresh; /** - * Hash code of the denomination public key. + * Hash code of the denomination public key. (Used to avoid having + * the variable-size RSA key this struct.) */ struct GNUNET_HashCode denom_hash; |