Secret Store - Wiki OpenEthereum Documentation

The Secret Store is a core technology that enables:

• distributed elliptic curve (EC) key pair generation - key is generated by several parties using special cryptographic protocol, so that:
  • private key portion remains unknown to every single party;
  • public key portion could be computed on every party and could be safely exposed to external entities;
  • every party hold the ‘share’ of the private key;
  • any subset of t+1 parties could unite to restore the private portion of the key;
  • any subset of less than t+1 parties could not restore the private portion of the key;
• distributed key storage - private key shares are stored separately by every party and are never exposed neither to another parties, nor to external entities;
• threshold retrieval according to blockchain permissions - all operations that are requiring private key, require at least t+1 parties to agree on ‘Permissioning contract’ state.

Glossary

Terms that are being used on this page:

• node or key server: specially configured OpenEthereum instance, which can participate in distributed EC key pair generation (or related) sessions;
• Secret Store: fully connected network of nodes, which is used to generate and store same set of keys;
• key scheme: a pair of numbers t and N, expressed as (t+1)-of-N, that is used as a parameter to key generation session:
  • N: is the current number of nodes in Secret Store;
  • t: is the key threshold, meaning that subset of t+1 nodes is required for operations, involving private portion of the key;
• server key generation session: process of single server key generation, using given server key id and key scheme;
  • server key: EC key pair that has been generated using server key generation session;
  • server key id: 256-bit value, used as unique identifier of server key;
  • server key share: is an artifact of server key generation session, that is stored on each node, participated in this session and can be used later to restore private portion of server key;
• document key generation session: process of generating single document key, used to encrypt document:
  • document: some document, that need to be externally-stored in encrypted form;
  • document encryption: process of encrypting document contents, running outside of Secret Store (i.e. it is Secret Store client who is choosing encryption algorithm and implementing encryption code);
  • document key: input key for document encryption, which is generated by Secret Store in document key generation session and is stored on nodes, encrypted by server key;
• permissioning sessions: are sessions that require access to existing server key shares to compute some values:
  • permissioning contract: blockchain contract, that is used to check if requester has permissions to run permissioning sessions with given server key;
  • document key retrieval session: process of restoring (decrypting) single document key and returning it to the requester;
  • signing session: process of computing message hash’ signature with previously generated server key;
• key servers set change session: process of migrating secret shares from ‘old’ nodes set to new nodes set, when one/some of nodes are being added/removed to/from Secret Store.

Glossary illustrated

Above is the illustration of Secret Store, which:

• consists of 3 nodes, which are connected to each other, using encrypted connections;
• contains 2 server keys:
  • server key with id = 1, generated using key scheme 3-of-3 (t is 2 and N is 3). Every node holds the share of this server key (shares are: S1_1, S1_2 and S1_3). Every node holds the public portion of this key (PUB1). All three shares are required to restore private portion of this key (PRIV1 = S1_1 + S1_2 + S1_3);
  • server key with id = 2, generated using key scheme 2-of-3 (t is 1 and N is 3). Every node holds the share of this server key (shares are: S2_1, S2_2 and S2_3). Every node holds the public portion of this key (PUB2). Any two shares are required to restore the private portion of this key (PRIV2 = S2_1 + S2_2 = S2_1 + S2_3 = S2_2 + S2_3);
• contains one document key (D2), bound to server key with id 2. D2 is stored in encrypted form and PRIV2 is required to decrypt it.

There are 4 entities, which are not a part of Secret Store:

• Alice and Bob are clients of Secret Store, which are using its API to read and store keys;
• permissioning contract, which contains rules that:
  • allow Alice to run permissioning sessions with server key with id = 1. Since server key 1 doesn’t have document key bound to it, it only makes sense for Alice to run signing sessions to sign messages with the private portion of key 1 (PRIV1);
  • allow Bob to run permissioning sessions with server key with id = 2. Since server key 2 has document key bound to it, Bob can run document key retrieval sessions (to use PRIV2 to decrypt D2 and return it, encrypted with Bob’ public key) along with signing sessions (to sign messages using PRIV2);
• node (NODE4), that is not currently a part of Secret Store.

Following are examples of API calls that will succeed:

• Alice runs server key generation session to generate a new server key with id = 3;
• Alice runs server and document key generation session to generate new server key with id = 4 and simultaneously bound document key to it;
• Alice runs document key storing session to bound new document key to server key 1;
• Alice runs Schnorr signing session to sign message using private portion of server key 1 (PRIV1);
• Bob runs document key shadow retrieval session to retrieve document key, bound to server key 2, without revealing it to any of nodes;
• Bob runs document key retrieval session to retrieve document key, bound to server key 2;
• administrator runs nodes set change session to add NODE4 to the Secret Store so that it will receive additional shares of both server keys.

Secret Store configuration

Please see Secret Store configuration for detailed description of configuration options.

Server key generation session

To generate server key, you should carefully select following parameters:

• server key id: if you’re planning to link document key to this server key later, it would be good to use document contents hash as this identifier. Otherwise, it could be a random value. In both cases, please note that this value is unique and can not be changed later;
• server key id signature: it is the server key id, signed with author’ private key. Only author of server key could bind document key to this server key later. This signature could be generated by secretstore_signRawHash RPC method (please see the method description if you’re planning to generate the signature by other means);
• key threshold (t): it is up to you to select the threshold, but following must be taken into account:
  • t must always be less than N;
  • since N could decrease when nodes are going offline, or are excluded from Secret Store, it should not be too close to N-1;
  • since any t+1 subset of nodes are able to restore the private portion of server key, t should not be too close to zero. Otherwise there could be a chance that there are enough adversary nodes to access your private data;
  • t equal to zero means that every node holds the private portion of server key and there are no advantages in using Secret Store over simple holding the key in safe place;
  • (possibly to be reconsidered) if you’re planning to use this key to generate ECDSA signatures, t must be chosen so that following is always true 2*t < N (please also read note about N decreasing).

To run session, execute following command (here and below we will use HTTP API of SecretStore for examples):

curl -X POST http://localhost:8082/shadow/0000000000000000000000000000000000000000000000000000000000000003/bd22d48735e5d711fffa03d9a987366acd50359a7a27f2fb0480e5339a44bf155b36ee1f2f860f4fcbb1171cf68dd59ac5f95d407137cafec4898f3e562fa9d700/1

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000003: is the hex-encoded server key id;
• bd22d48735e5d711fffa03d9a987366acd50359a7a27f2fb0480e5339a44bf155b36ee1f2f860f4fcbb1171cf68dd59ac5f95d407137cafec4898f3e562fa9d700: is the hex-encoded signed server key id;
• 1: is the key threshold value.

If session was successful, HTTP response code is 200 and body is the hex-encoded public portion of server key:

"0xe54804602b1b5675f429f64233c2a9461f4d00d146441c0c7296cddbb7f50e1eef91d88f92585b050aa2feca8e206d8d763d118ce45b9ebcd238893ca85e6092"

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Internal error: session with the same id is already registered\""

Please note, that while it is only t+1 nodes are required to restore the private portion of server key, all N nodes are required to generate server key. This assures us that we will be able to restore the private, even if N is decreased by some reason. So this means that all Secret Store nodes must be online and connected to each other in order to run this session.

Implementation is based on ECDKG: A Distributed Key Generation Protocol Based on Elliptic Curve Discrete Logarithm.

Document key storing session

(subject to change)

After running server key generation session, you have an option to bind externally-generated document key to server key. You should prepare following parameters:

• server key id: it is the same id, that was used in server key generation session;
• server key id signature: it is the server key id, signed by the same entity (author) that has signed signed server key id in server key generation session;
• ‘common point’ and ‘encrypted point’: is the document key, externally encrypted by public server key, using special procedure (RPCs for generating these values are coming). For now, please look at the OpenEthereum code encrypt_secret.

To run session, execute following command:

curl -X POST http://localhost:8082/shadow/0000000000000000000000000000000000000000000000000000000000000000/de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00/368244efaf441c2dabf7a723355a97b3b86f27bdb2827ae6f34ddece5132efd37af4ba808957b7113b4296bc4ae9ec7be38f9de6bae00504e775883a50d4658a/b7ad0603946987f1a154ae7f074e45da224eaa83704aac16a2d43a675d219654cf087b5d7aacce0790a65abbc1a495b26e71a5c6e9a4a71b543bf0048935bc13

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000000: is the hex-encoded server key id;
• de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00: is the hex-encoded signed server key id;
• 368244efaf441c2dabf7a723355a97b3b86f27bdb2827ae6f34ddece5132efd37af4ba808957b7113b4296bc4ae9ec7be38f9de6bae00504e775883a50d4658a: is the hex-encoded common point portion of encrypted document key;
• b7ad0603946987f1a154ae7f074e45da224eaa83704aac16a2d43a675d219654cf087b5d7aacce0790a65abbc1a495b26e71a5c6e9a4a71b543bf0048935bc13: is the hex-encoded encrypted point portion of encrypted document key.

If session was successful, HTTP response code is 200 and the body is empty. If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Document not found\""

Please note that all Secret Store nodes must be online and connected to each other to run this session. Also, please note that there’s could be at most one document key, bound to single server key. And it can be only bound once (i.e. you could only run document key storing session once for given server key id).

Implementation is based on ECDKG: A Distributed Key Generation Protocol Based on Elliptic Curve Discrete Logarithm.

Server and document key generation session

While it is possible (and more secure, if you’re not trusting to Secret Store nodes) to run separate server key generation and document key storing sessions, you could generate both keys simultaneously. In this case, document key is generated by one of the participating nodes.

To run session, you should carefully select following parameters:

• server key id: see server key generation session for details;
• server key id signature: it is the server key id, signed with requester private key;
• key threshold (t): see server key generation session for details.

To run session, execute the following command:

curl -X POST http://localhost:8082/0000000000000000000000000000000000000000000000000000000000000003/bd22d48735e5d711fffa03d9a987366acd50359a7a27f2fb0480e5339a44bf155b36ee1f2f860f4fcbb1171cf68dd59ac5f95d407137cafec4898f3e562fa9d700/1

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000003: is the hex-encoded server key id;
• bd22d48735e5d711fffa03d9a987366acd50359a7a27f2fb0480e5339a44bf155b36ee1f2f860f4fcbb1171cf68dd59ac5f95d407137cafec4898f3e562fa9d700: is the hex-encoded signed server key id;
• 1: is the key threshold value.

If session was successful, HTTP response code is 200 and body is the hex-encoded document key, encrypted with requester public key (ECIES encryption is used):

"0x04bfc447952f4d1818a49f6b30bbf42ef26d6a25844ea2d11cb93a8a7ac385de6c162edbd1c2b785061456b35075e620bd3991a7df5967a594c87bd199caf90810a463e02da8b3415d471495ad37fa069d287a830e72f27b565fc3f28b5888c1e16c4435ef801bc6ffd680767b82a3102268f53796b9fa61117138bd5c72bb5e0556d6d9e17ce850d499e344ae68c1b04cbde3077e9d2a4ba9cceb057d2d609133c479aa891adf38c3511424c2cbc86764"

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Internal error: session with the same id is already registered\""

Please note that all Secret Store nodes must be online and connected to each other to run this session.

Technically, document key is the point on EC. One possible way of encrypting the document is to use the X coordinate of this point (or some derived value) as a key for some symmetric encryption algorithm (AES).

Implementation is based on ECDKG: A Distributed Key Generation Protocol Based on Elliptic Curve Discrete Logarithm.

Permissioning sessions

The common part of all permissioning sessions is that they require at least t+1 nodes to be online, fully connected and agree upon requester access to the server key (this is called ‘consensus group’). At the beginning, consensus is established - every node asks permissioning contract if the requester has an access to the key with given id. This means, that besides having the server key share, all nodes must be fully synchronized.

Permissioning contract

The permissioning contract has to implement a single method:

function checkPermissions(address user, bytes32 document) constant returns (bool) {}

Returning true means that the owner of user address has an access to the server key with server key id document.

The contract address is specified in acl_contract parameter of the configuration file (by default it is read from the secretstore_acl_checker entry in the Registry).

Document key shadow retrieval session

This session is a preferable way of retrieving previously generated document key. To run this session, you will need to prepare following parameters:

• server key id: the id of previously generated server key, to which document key has been bound;
• server key id signature: it is the server key id, signed with the private key of requester, having access to the server key.

To run session, execute the following command:

curl http://localhost:8082/shadow/0000000000000000000000000000000000000000000000000000000000000000/de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000000: is the hex-encoded server key id;
• de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00: is the hex-encoded signed server key id.

If session was successful, HTTP response code is 200 and body is the json object, containing hex-encoded decrypted_secret, common_point and decrypt_shadows fields:

{"decrypted_secret":"0x88adde1841690af21700e6ff37b8786733cede2ed2faf703f9d5d1a625fd45eb7e5e6efc3800d23482cbf8f1eead192b3123326aa5434c56bae2f99f3f7ca5bf","common_point":"0x2e350d872aef36f0baaf53c0b8b227240814e200e649493948e715487e09ac25957d269f97cd110e836ac48443f217c6a1ce443eecb51df8b1218c0558bd65a2","decrypt_shadows":["0x045f2f68a55d9823c5d618eda6e6687e1d16cb255ec9b4e8e91cee7910e0662e7fb696aa58cf141c44e1d26f7888cd2f3cdc817aa42ce719c2fae6ca5ae58655d161d97b791dd4734ffdd83920980107bf9f07cf49e69680068f490084e11ecd6f344d12bdfe1620ce2e36e5a77086970c9a20192e29fe8b64024ee2cd8eb48bd78595e5da81096f7f2e4165f85719b97e","0x04df05a7ae021b111777318f94ba677ed1e2b4857a3209acae25ca6a628dfe9f5f28aec46e528fd9ac8d35eb1e506851f699cb3715738106e226a4a4ab820af9310e059904a24e5851f7e28e163c35a0803ba13e4d3de9f7bea3aef94c63540193c89402080cde36aab7117b7918a11cb184bf40a08ab59a12d25a15ae581731fff1dba5889ab3b7f24e7b54d74538e342"]}

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Access denied\""

To reconstruct document key, Secret Store client must pass values of these fields to secretstore_shadowDecrypt RPC.

Implementation is based on ECDKG: A Distributed Key Generation Protocol Based on Elliptic Curve Discrete Logarithm.

Document key retrieval session

During a document key shadow retrieval session, the document key is not reconstructed on any node. But it requires Secret Store client either to have an access to OpenEthereum RPCs, or to run some EC calculations to decrypt the document key. It is possible to run lighter version of this session, which returns the final document key (though, encrypted with the requester’s public key) if you have enough trust in Secret Store nodes.

To run this session, you will need to prepare following parameters:

• server key id: the id of previously generated server key, to which document key has been bound;
• server key id signature: it is the server key id, signed with the private key of requester, having access to the server key.

To run session, execute the following command:

curl http://localhost:8082/0000000000000000000000000000000000000000000000000000000000000000/de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000000: is the hex-encoded server key id;
• de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00: is the hex-encoded signed server key id.

If session was successful, HTTP response code is 200 and body is the hex-encoded document key, encrypted with requester public key (ECIES encryption is used):

"0x04990dbe0a4bd6ade23a588ca94c8ba1961a512129b62c23b2a5984ee58e6a925115f7681168909f45a33d7ffe8b8994416b6a707a8838c6c5bfc2d332cfa0fdeb0d1bb0c098d4e7ea690d76abbfc28483665bf00aff8932f6b557efc232ed229709a9cd583bc25543ec2414c719524fa9e73b813c4258e9eb5e8fb95480175d4be89869c094590bf680783dd85da20856da3980f0d2245c4f6b2faa2c28645c355bb082f8759ecaa16b536ff483768d26"

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Access denied\""

Implementation is based on ECDKG: A Distributed Key Generation Protocol Based on Elliptic Curve Discrete Logarithm.

Schnorr signing session

For computing Schnorr signature of given message hash, you will need to prepare following parameters:

• server key id: the id of previously generated server key;
• server key id signature: it is the server key id, signed with the private key of requester, having access to the server key;
• message hash: is the 256-bit hash of the message that is need to be signed.

To run session, execute the following command:

curl http://localhost:8082/schnorr/0000000000000000000000000000000000000000000000000000000000000000/de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00/0000000000000000000000000000000000000000000000000000000000000001

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000000: is the hex-encoded server key id;
• de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00: is the hex-encoded signed server key id;
• 0000000000000000000000000000000000000000000000000000000000000001: is the message hash to be signed.

If session was successful, HTTP response code is 200 and body is the hex-encoded Schnorr signature (serialized as c || s), encrypted with requester public key (ECIES encryption is used):

"0x0410fe210ffdd38611b252e24c61b610d6ea8ec70f9f7186184441871839562cc18c94174af0c804973ce88a6f07ec7604b4b91821a6ca68ca348d16cd647fba494f8132ff36ad4654abd5cba6fb1fd98cacc12aaf3a0fe70010be91f5ab7b69db8f80e528be3baba70341721d6058ad66665363033f0cee963476da746e843d4006170ab549fa82f14eec7b420d542c3415a61fc3075f39e1529bc4e6f54f1170496393485f6ef271ad8b587c8fae8a18"

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Access denied\""

Implementation is based on Efficient Multi-Party Digital Signature using Adaptive Secret Sharing for Low-Power Devices in Wireless Networks.

ECDSA signing session

For computing ECDSA signature of given message hash, you will need to prepare following parameters:

• server key id: the id of previously generated server key;
• server key id signature: it is the server key id, signed with the private key of requester, having access to the server key;
• message hash: is the 256-bit hash of the message that is need to be signed.

To run session, execute the following command:

curl http://localhost:8082/ecdsa/0000000000000000000000000000000000000000000000000000000000000000/de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00/0000000000000000000000000000000000000000000000000000000000000001

Here:

• http://localhost:8082: is the address on which node is listening for incoming requests;
• 0000000000000000000000000000000000000000000000000000000000000000: is the hex-encoded server key id;
• de12681e0b8f7a428f12a6694a5f7e1324deef3d627744d95d51b862afc13799251831b3611ae436c452b54cdf5c4e78b361a396ae183e8b4c34519e895e623c00: is the hex-encoded signed server key id;
• 0000000000000000000000000000000000000000000000000000000000000001: is the message hash to be signed.

If session was successful, HTTP response code is 200 and body is the hex-encoded ECDSA signature (serialized as r || s || v), encrypted with requester public key (ECIES encryption is used):

"0x0410fe210ffdd38611b252e24c61b610d6ea8ec70f9f7186184441871839562cc18c94174af0c804973ce88a6f07ec7604b4b91821a6ca68ca348d16cd647fba494f8132ff36ad4654abd5cba6fb1fd98cacc12aaf3a0fe70010be91f5ab7b69db8f80e528be3baba70341721d6058ad66665363033f0cee963476da746e843d4006170ab549fa82f14eec7b420d542c3415a61fc3075f39e1529bc4e6f54f1170496393485f6ef271ad8b587c8fae8a18"

If error has occurred during session, HTTP response code is in errors range and body is the description of the error:

"\"Access denied\""

(possibly to be reconsidered) Please note, that when generating key to be used in this session, choose threshold t so that the following is always true 2*t < N.

Implementation is based on A robust threshold elliptic curve digital signature providing a new verifiable secret sharing scheme.