Secret Store - Wiki Parity Tech Documentation

The Parity Secret Store is core technology that enables:

Glossary

Terms that are being used on this page:

Glossary illustrated

Secret-Store-Glossary-Illustrated

Above is the illustration of Secret Store, which:

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

Following are examples of API calls that will succeed:

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:

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:

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:

To run session, execute following command:

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

Here:

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:

To run session, execute the following command:

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

Here:

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:

To run session, execute the following command:

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

Here:

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 document key shadow retrieval session, document key is not reconstructed on any node. But it requires Secret Store client either to have an access to Parity RPCs, or to run some EC calculations to decrypt the document key. It is possible to run lighter version of this session, which returns final document key (though, encrypted with requester public key) if you have enough trust in Secret Store nodes.

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

To run session, execute the following command:

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

Here:

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:

To run session, execute the following command:

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

Here:

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:

To run session, execute the following command:

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

Here:

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.