diff options
author | Marcello Stanisci <marcello.stanisci@inria.fr> | 2016-10-07 15:20:11 +0200 |
---|---|---|
committer | Marcello Stanisci <marcello.stanisci@inria.fr> | 2016-10-07 15:20:11 +0200 |
commit | 4bfab9803e89e3095dd4bc751887337ebd9d7e07 (patch) | |
tree | 8d755ea4a1cd5912101873cbb454f964d7c4fb57 | |
parent | ba45e62debcdec917b260d362481d12d9b9c909c (diff) | |
download | docs-4bfab9803e89e3095dd4bc751887337ebd9d7e07.tar.gz docs-4bfab9803e89e3095dd4bc751887337ebd9d7e07.tar.bz2 docs-4bfab9803e89e3095dd4bc751887337ebd9d7e07.zip |
porting exchange API to new style
-rw-r--r-- | api-common.rst | 110 | ||||
-rw-r--r-- | api-exchange.rst | 66 |
2 files changed, 114 insertions, 62 deletions
diff --git a/api-common.rst b/api-common.rst index de02d483..f41b9a46 100644 --- a/api-common.rst +++ b/api-common.rst @@ -142,22 +142,23 @@ as other binary data in Crockford Base32 encoding. Timestamps ^^^^^^^^^^ - Timestamps are represented in JSON as a string literal `"\\/Date(x)\\/"`, - where `x` is the decimal representation of the number of seconds past the - Unix Epoch (January 1, 1970). The escaped slash (`\\/`) is interpreted in - JSON simply as a normal slash, but distinguishes the timestamp from a normal - string literal. We use the type "date" in the documentation below. - Additionally, the special strings "\\/never\\/" and "\\/forever\\/" are - recognized to represent the end of time. +Timestamps are represented in JSON as a string literal `"\\/Date(x)\\/"`, +where `x` is the decimal representation of the number of seconds past the +Unix Epoch (January 1, 1970). The escaped slash (`\\/`) is interpreted in +JSON simply as a normal slash, but distinguishes the timestamp from a normal +string literal. We use the type "date" in the documentation below. +Additionally, the special strings "\\/never\\/" and "\\/forever\\/" are +recognized to represent the end of time. .. _public\ key: -Public Keys -^^^^^^^^^^^ +Keys +^^^^ .. _`tsref-type-EddsaPublicKey`: .. _`tsref-type-EddsaPrivateKey`: +.. _`tsref-type-CoinPublicKey`: .. code-block:: tsref @@ -174,6 +175,17 @@ Public Keys // RSA public key converted to Crockford `Base32`_. type RsaPublicKey = string; +.. _blinded-coin: + +Blinded coin +^^^^^^^^^^^^ + +.. _`tsref-type-CoinEnvelope`: + +.. code-block:: tsref + + // Blinded coin's `public EdDSA key <eddsa-coin-pub>`_, `base32`_ encoded + type CoinEnvelope = string; .. _signature: @@ -303,10 +315,16 @@ uses 512-bit hash codes (64 bytes). uint8_t hash[64]; // usually SHA-512 }; +.. _reserve-pub: +.. sourcecode:: c + struct TALER_ReservePublicKeyP { uint8_t eddsa_pub[32]; }; +.. _reserve-priv: +.. sourcecode:: c + struct TALER_ReservePrivateKeyP { uint8_t eddsa_priv[32]; }; @@ -315,6 +333,9 @@ uses 512-bit hash codes (64 bytes). uint8_t eddsa_signature[64]; }; +.. _merchant-pub: +.. sourcecode:: c + struct TALER_MerchantPublicKeyP { uint8_t eddsa_pub[32]; }; @@ -331,14 +352,23 @@ uses 512-bit hash codes (64 bytes). uint8_t ecdhe_priv[32]; }; +.. _sign-key-pub: +.. sourcecode:: c + struct TALER_ExchangePublicKeyP { uint8_t eddsa_pub[32]; }; +.. _sign-key-priv: +.. sourcecode:: c + struct TALER_ExchangePrivateKeyP { uint8_t eddsa_priv[32]; }; +.. _eddsa-sig: +.. sourcecode:: c + struct TALER_ExchangeSignatureP { uint8_t eddsa_signature[64]; }; @@ -355,11 +385,17 @@ uses 512-bit hash codes (64 bytes). uint8_t eddsa_signature[64]; }; +.. _eddsa-coin-pub: +.. sourcecode:: c + union TALER_CoinSpendPublicKeyP { uint8_t eddsa_pub[32]; uint8_t ecdhe_pub[32]; }; +.. _coin-priv: +.. sourcecode:: c + union TALER_CoinSpendPrivateKeyP { uint8_t eddsa_priv[32]; uint8_t ecdhe_priv[32]; @@ -372,8 +408,6 @@ uses 512-bit hash codes (64 bytes). struct TALER_TransferSecretP { uint8_t key[sizeof (struct GNUNET_HashCode)]; }; - - struct TALER_LinkSecretP { uint8_t key[sizeof (struct GNUNET_HashCode)]; }; @@ -420,6 +454,7 @@ The following list contains all the data structure that can be signed in Taler. Their definition is typically found in `src/include/taler_signatures.h`, within the :ref:`exchange's codebase <exchange-repo>`. +.. _TALER_WithdrawRequestPS: .. sourcecode:: c struct TALER_WithdrawRequestPS { @@ -434,6 +469,9 @@ within the :ref:`exchange's codebase <exchange-repo>`. struct GNUNET_HashCode h_coin_envelope; }; +.. _TALER_DepositRequestPS: +.. sourcecode:: c + struct TALER_DepositRequestPS { /** * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_DEPOSIT @@ -450,6 +488,9 @@ within the :ref:`exchange's codebase <exchange-repo>`. union TALER_CoinSpendPublicKeyP coin_pub; }; +.. _TALER_DepositConfirmationPS: +.. sourcecode:: c + struct TALER_DepositConfirmationPS { /** * purpose.purpose = TALER_SIGNATURE_WALLET_CONFIRM_DEPOSIT @@ -465,6 +506,9 @@ within the :ref:`exchange's codebase <exchange-repo>`. struct TALER_MerchantPublicKeyP merchant; }; +.. _TALER_RefreshMeltCoinAffirmationPS: +.. sourcecode:: c + struct TALER_RefreshMeltCoinAffirmationPS { /** * purpose.purpose = TALER_SIGNATURE_WALLET_COIN_MELT @@ -476,6 +520,9 @@ within the :ref:`exchange's codebase <exchange-repo>`. union TALER_CoinSpendPublicKeyP coin_pub; }; +.. _TALER_RefreshMeltConfirmationPS: +.. sourcecode:: c + struct TALER_RefreshMeltConfirmationPS { /** * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT @@ -607,18 +654,35 @@ within the :ref:`exchange's codebase <exchange-repo>`. struct TALER_AmountNBO total_amount; struct TALER_AmountNBO max_fee; struct GNUNET_HashCode h_contract; - }; + }; struct TALER_ConfirmWirePS { - /** - * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE - */ - struct GNUNET_CRYPTO_EccSignaturePurpose purpose; - struct GNUNET_HashCode h_wire; - struct GNUNET_HashCode h_contract; - struct TALER_WireTransferIdentifierRawP wtid; - struct TALER_CoinSpendPublicKeyP coin_pub; - uint64_t transaction_id; - struct GNUNET_TIME_AbsoluteNBO execution_time; - struct TALER_AmountNBO coin_contribution; + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_HashCode h_wire; + struct GNUNET_HashCode h_contract; + struct TALER_WireTransferIdentifierRawP wtid; + struct TALER_CoinSpendPublicKeyP coin_pub; + uint64_t transaction_id; + struct GNUNET_TIME_AbsoluteNBO execution_time; + struct TALER_AmountNBO coin_contribution; + }; + +.. _TALER_RefundRequestPS: +.. sourcecode:: c + + struct TALER_RefundRequestPS { + /** + * purpose.purpose = TALER_SIGNATURE_MERCHANT_REFUND + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_HashCode h_contract GNUNET_PACKED; + uint64_t transaction_id GNUNET_PACKED; + struct TALER_CoinSpendPublicKeyP coin_pub; + struct TALER_MerchantPublicKeyP merchant; + uint64_t rtransaction_id GNUNET_PACKED; + struct TALER_AmountNBO refund_amount; + struct TALER_AmountNBO refund_fee; }; diff --git a/api-exchange.rst b/api-exchange.rst index 9bf1eb40..3891306e 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -357,12 +357,10 @@ exchange. // Transfer details uniquely identifying the transfer, only present if type is "DEPOSIT". transfer_details?: any; - // `base32`_ encoding of `TALER_WithdrawRequestPS`_. This field appears only if `type` - // is "WITHDRAW". + // `base32`_ encoding of `TALER_WithdrawRequestPS`_ with purpose TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW. This field appears only if `type` is "WITHDRAW". details?: string; // Signature over the transaction `details`. - // Purpose: TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW signature?: EddsaSignature; } @@ -413,14 +411,12 @@ exchange. // denomination private key coin_ev: CoinEnvelope; - // public (EdDSA) key of the reserve from which the coin should be + // `public (EdDSA) key <reserve-pub>`_ of the reserve from which the coin should be // withdrawn. The total amount deducted will be the coin's value plus the // withdrawal fee as specified with the denomination information. reserve_pub: EddsaPublicKey; - // Signature (binary-only) of purpose - // `TALER_SIGNATURE_WALLET_RESERVE_WITHDRAW` created with the reserves's - // private key + // Signature of `TALER_WithdrawRequestPS`_ created with the `reserves's private key <reserve-priv>`_ reserve_sig: EddsaSignature; } @@ -500,7 +496,7 @@ denomination. // The merchant's account details. This must be a JSON object whose format // must correspond to one of the supported wire transfer formats of the exchange. // See `wireformats`_. - wire: WireFormat; + wire: Object; // SHA-512 hash of the merchant's payment details from `wire`. Although // strictly speaking redundant, this helps detect inconsistencies. @@ -510,7 +506,7 @@ denomination. // details are never disclosed to the exchange. H_contract: HashCode; - // coin's public key, both ECDHE and EdDSA. + // `coin's public key <eddsa-coin-pub>`_, both ECDHE and EdDSA. coin_pub: CoinPublicKey; // denomination RSA key with which the coin is signed @@ -530,7 +526,7 @@ denomination. // 64-bit transaction id for the transaction between merchant and customer transaction_id: number; - // EdDSA public key of the merchant, so that the client can identify the + // EdDSA `public key of the merchant <merchant-pub>`_, so that the client can identify the // merchant for refund requests. merchant_pub: EddsaPublicKey; @@ -538,9 +534,7 @@ denomination. // exchange, possibly zero if refunds are not allowed. refund_deadline: Timestamp; - // The EdDSA signature (binary-only) made with purpose - // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` made by the customer with the coin's - // private key. + // Signature of `TALER_DepositRequestPS`_, made by the customer with the `coin's private key <coin-priv>`_ coin_sig: EddsaSignature; } @@ -555,14 +549,14 @@ denomination. // The string constant "DEPOSIT_OK" status: string; - // the EdDSA :ref:`signature` (binary-only) with purpose - // `TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT` using a current signing key of the - // exchange affirming the successful deposit and that the exchange will transfer the - // funds after the refund deadline, or as soon as possible if the refund - // deadline is zero. + // the EdDSA signature of `TALER_DepositConfirmation`_ using a current + // `signing key of the exchange <sign-key-priv>`_ affirming the successful + // deposit and that the exchange will transfer the funds after the refund + // deadline, or as soon as possible if the refund deadline is zero. sig: EddsaSignature; - // public EdDSA key of the exchange that was used to generate the signature. + // `public EdDSA key of the exchange <sign-key-pub>`_ that was used to + // generate the signature. // Should match one of the exchange's signing keys from /keys. It is given // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. @@ -581,6 +575,7 @@ denomination. history: CoinSpendHistoryItem[]; } + .. _`tsref-type-CoinSpendHistoryItem`: .. _CoinSpendHistoryItem: .. code-block:: tsref @@ -596,20 +591,14 @@ denomination. // the coin's denomination value. amount: Amount; - // base32 binary encoding of the transaction data as a - // `TALER_DepositRequestPS` or `TALER_RefreshMeltCoinAffirmationPS` - // or `TALER_RefundRequestPS` - // struct described in :ref:`Signatures`. Its `purpose` should match our - // `type`, `amount_with_fee`, should match our `amount`, and its `size` - // should be consistent with the respective struct type. + // `base32`_ binary encoding of the transaction data as a + // `TALER_DepositRequestPS`_ or `TALER_RefreshMeltCoinAffirmationPS`_ + // or `TALER_RefundRequestPS`_ details: string; - // the EdDSA :ref:`signature` (binary-only) made with purpose - // `TALER_SIGNATURE_WALLET_COIN_DEPOSIT` or - // `TALER_SIGNATURE_WALLET_COIN_MELT` or - // `TALER_SIGNATURE_MERCHANT_REFUND` over the transaction's details. + // `EdDSA Signature <eddsa-sig>`_ of what we got in `details`. // Note that in the case of a 'refund', the signature is made with - // the public key of the merchant, and not that of the coin. + // the `public key of the merchant <merchant-pub>`_, and not `that of the coin <eddsa-coin-pub>`_ signature: EddsaSignature; } @@ -664,7 +653,7 @@ the API during normal operation. // For each of the `n` new coins, `kappa` transfer keys. // coin_evs[j][k] is the k-th blank (of kappa) for the k-th new coin (of n). - coin_evs: CoinBlank[][] + coin_evs: CoinBlank[][]; // FIXME TBD // `kappa` transfer public keys (ephemeral ECDHE keys) transfer_pubs: EddsaPublicKey[]; @@ -682,16 +671,16 @@ the API during normal operation. .. code-block:: tsref interface MeltCoin { - // Coin public key, uniquely identifies the coin + // `Coin public key <eddsa-coin-pub>`_, uniquely identifies the coin coin_pub: string; // The denomination public key allows the exchange to determine total coin value. denom_pub: RsaPublicKey; - // Signature over the coin public key by the denomination. + // Signature over the `coin public key <eddsa-coin-pub>`_ by the denomination. denom_sig: RsaSignature; - // Signature by the coin over the session public key + // Signature by the `coin <coin-priv>`_ over the session public key (FIXME: put link to some C definition of this key?) confirm_sig: EddsaSignature; // Amount of the value of the coin that should be melted as part of @@ -716,12 +705,11 @@ the API during normal operation. // Which of the `kappa` indices does the client not have to reveal. noreveal_index: number; - // binary-only Signature_ for purpose `TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT` - // whereby the exchange affirms the successful melt and confirming the - // `noreveal_index` + // Signature of `TALER_RefreshMeltConfirmationPS`_ whereby the exchange + // affirms the successful melt and confirming the `noreveal_index` exchange_sig: EddsaSignature; - // public EdDSA key of the exchange that was used to generate the signature. + // `public EdDSA key <sign-key-pub>`_ of the exchange that was used to generate the signature. // Should match one of the exchange's signing keys from /keys. Again given // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. @@ -823,7 +811,7 @@ the API during normal operation. object: string; // Information about each melted coin - refresh_melt_info: OldCoinInfo; + refresh_melt_info: OldCoinInfo; // FIXME // array with RSA denomination public keys of the coins the original // refresh request asked to be exchangeed |