summaryrefslogtreecommitdiff
path: root/impl-mint.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2014-11-20 09:23:59 +0100
committerChristian Grothoff <christian@grothoff.org>2014-11-20 09:23:59 +0100
commit3d108294a1f4a5e1a842f30921e56054a69fecce (patch)
tree2abfd6284078bd2bd91ea86bd146c6bee8007c12 /impl-mint.rst
downloaddocs-3d108294a1f4a5e1a842f30921e56054a69fecce.tar.gz
docs-3d108294a1f4a5e1a842f30921e56054a69fecce.tar.bz2
docs-3d108294a1f4a5e1a842f30921e56054a69fecce.zip
initial import of sphinx documentation
Diffstat (limited to 'impl-mint.rst')
-rw-r--r--impl-mint.rst242
1 files changed, 242 insertions, 0 deletions
diff --git a/impl-mint.rst b/impl-mint.rst
new file mode 100644
index 0000000..969a730
--- /dev/null
+++ b/impl-mint.rst
@@ -0,0 +1,242 @@
+===================================
+The Mint Reference Implementation
+===================================
+
+
+
+--------------------
+Key update
+--------------------
+New denomination and signing keys can be uploaded to the mint
+via the HTTP interface. It is, of course, only possible to upload keys signed
+by the mint's master key.
+
+As an additional constraint, it is only possible to upload new keys while the
+mint still has one valid signing key (otherwise, MitM-attacks would be possible).
+
+Alternative: Transfer key is signed by the master key.
+
+.. http:GET:: /admin/keyup/public
+
+ Transmit the public part of the new key in plain-text.
+
+ :query denom_info: Public part of the denomination issue
+ :query transfer_pub: Public key used by the party doing the key transfer
+
+.. http:GET:: /admin/keyup/private
+
+ Transmit the private part of the new text, encrypted with the shared secret derived from the
+ ephemeral public key and the sender's private key.
+
+
+-------------------
+Database Scheme
+-------------------
+
+.. sourcecode:: postgres
+
+ CREATE TABLE purses (
+ -- The customer's withdraw public key for the purse.
+ withdraw_pub BYTEA PRIMARY KEY,
+
+ -- Purse balance (value part).
+ balance_value INT4 NOT NULL,
+
+ -- Purse balance (fractional part).
+ balance_fraction INT4 NOT NULL,
+
+ -- Purse balance (fractional).
+ balance_currency VARCHAR(4),
+
+ -- Expiration time stamp for the purse.
+ expiration INT8,
+
+ -- The blinding key (public part) for the purse, can be NULL
+ -- if funds are insufficient or the mint has not
+ -- generated it yet.
+ blinding_pub BYTEA,
+
+ -- The blinding key (private part).
+ blinding_priv BYTEA,
+
+ -- Key that was used to create the last signature on the
+ -- purse status
+ status_sign_pub BYTEA,
+
+ -- Cached status signature
+ status_sig BYTEA
+ );
+
+
+.. sourcecode:: postgres
+
+ CREATE TABLE collectable_blindcoins (
+ -- The public part of the blinding key.
+ -- Note that this is not a foreign key,
+ -- as the blinding key is removed from the purse
+ -- table once a coin has been requested with it.
+ -- Furthermore, the private part is not required
+ -- anymore.
+ blind_pub bytea PRIMARY KEY,
+
+ -- The coin blank provided by the customer.
+ blind_blank_coin BYTEA,
+
+ -- Signature over the minting request by the customer.
+ customer_sig BYTEA,
+
+ -- The signed blind blank coin.
+ blind_signed_coin BYTEA,
+
+ -- The denomination public key used to sign the
+ -- blind signed coin.
+ denom_pub BYTEA,
+
+ -- The purse that requested the minting of this
+ -- coin.
+ withdraw_pub BYTEA REFERENCES purses(withdraw_pub)
+ );
+
+
+The table `coins` stores information about coins known to the mint.
+
+.. sourcecode:: postgres
+
+ CREATE TABLE coins (
+ denom_pub BYTEA NOT NULL,
+ denom_sig BYTEA NOT NULL,
+ coin_pub BYTEA NOT NULL,
+
+ -- melting session, or NULL if not melted
+ melt_session BYTEA,
+
+ -- remaining value of the coin
+ balance_currency int4,
+ balance_value int4,
+ balance_fraction int4,
+
+ -- lock id, not NULL if not locked
+ lock int
+ );
+
+The following tables are used for refreshing.
+
+.. sourcecode:: postgres
+
+ CREATE TABLE refresh_sessions (
+ session_pub BYTEA,
+ order_sig BYTEA,
+ index_reveal INT2,
+ );
+
+ CREATE TABLE refresh_melt (
+ session_pub BYTEA REFERENCES refresh_sessions (session_pub),
+ session_sig BYTEA,
+ denom_pub BYTEA,
+ denom_sig BYTEA,
+ coin_pub BYTEA,
+ coin_sig BYTEA,
+ );
+
+ -- create links to old coins
+ CREATE TABLE refresh_link_commits (
+ session_pub BYTEA,
+ session_sig BYTEA,
+ coin_pub BYTEA,
+ transfer_pub BYTEA,
+ link_secret_enc BYTEA,
+ link_secret_hash BYTEA,
+ idx INTEGER
+ );
+
+ CREATE TABLE refresh_order (
+ -- EdDSA public key of the melting session
+ session_pub BYTEA REFERENCES refresh_sessions (session_pub),
+ -- denomination key for the newly ordered coin
+ denom_pub BYTEA,
+ -- signature from session key over coin order
+ session_sig BYTEA,
+ );
+
+ CREATE TABLE refresh_coin_commits (
+ session_pub BYTEA,
+ idx INTEGER,
+ coin_link_enc BYTEA,
+ -- The blinding key (public part) for the purse, can be NULL
+ -- if funds are insufficient or the mint has not
+ -- generated it yet.
+ blinding_pub BYTEA,
+
+ -- The blinding key (private part).
+ blinding_priv BYTEA,
+ -- The coin blank provided by the customer.
+ blind_blank_coin BYTEA,
+ -- encrypted stuff
+ coin_link_enc BYTEA,
+ );
+
+
+----------------
+Key Management
+----------------
+The command line tool `neuro-mint-keyup` updates the signing key and
+list of denominations offered by the mint. This process requires the
+mint's master key, and should be done offline in order to protect the master key.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring keys and coin types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The denominations and key expirations for the mint are specified in a configuration file.
+
+The section `[mint_keys]` containts the following entries:
+
+* `signkey_duration`: How long should one signing key be used?
+* `lookahead_sign`: For how far into the future should keys be issued? This determines the frequency
+ of offline signing with the master key.
+* `lookahead_provide`: How far into the future should the mint provide keys? This determines the attack
+ window on keys.
+* `coin_types`: Space-separated list of coin aliases that the mint should provide. The coin aliases
+ are used as the key configuration sections regarding the coin type.
+
+The configuration refers to each denomination type by an alphanumeric alias. This alias is used to identify
+the same denomination in different sections. Configuration values are assigned as `<ALIAS> = <VALUE>`
+in the respective section.
+
+* `[mint_denom_duration_withdraw]`: How long can a coin of this type be withdrawn?
+ This limits the losses incured by the mint when a denomination key is compromised.
+* `[mint_denom_duration_overlap]`: What is the overlap of the withdrawal timespan for
+ a coin type?
+* `[mint_denom_duration_spend]`: How long is a coin of the given type valid? Smaller
+ values result in lower storage costs for the mint.
+* `[mint_denom_value]`: What is the value of the coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_withdraw]`: What does it cost to withdraw this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_refresh]`: What does it cost to refresh this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_fee_deposit]`: What does it cost to refresh this coin? Given as `T : A / B`, where `T` is the currency
+ identifier, `A` and `B` are integers denoting the value (`A` is the numerator, `B` is the denominator).
+* `[mint_denom_kappa]`: How easy should cheating be for the customer when refreshing?
+
+^^^^^^^^^^^^^^^^^^^
+Key Storage Format
+^^^^^^^^^^^^^^^^^^^
+The mint's key directory contains the two subdirectories `signkeys` and `coinkeys`.
+
+The file `master.pub` stores the mint's master public key.
+
+The directory `signkeys` contains signkey files, where the name is the start date of the respective key.
+
+The `coinkeys` directory additionaly contains a subdirectory for each coin type alias. These contain
+coinkey files, where the name is again the start timestamp of the respective key.
+
+
+-------
+Purses
+-------
+Incoming transactions to the mint's provider result in the creation or update of `purses`, identified
+by their withdrawal key.
+
+The command line tool `neuro-mint-modpurse` allows create and add money to purses in the mint's database.
+
+