GuidesAPI ReferenceChangelogDiscussions
Woleet.io

Seal data

👍

Too busy to read the documentation?

You will find here very simple curl and shell code samples demonstrating the basic usage of the Woleet API.

To seal a file, you simply request the Woleet API to create a proof of seal of this file. You do this by creating a signature anchor, which allows at the same time to create the proof, monitor the creation process and retrieve the proof receipt at the end.

But before, you need to compute the SHA256 hash of your file (its 'digital fingerprint').

Let's do it using a simple shell command using openssl to do the computation:

$ cat <your file> | openssl dgst -sha256 |  cut -d " " -f 2

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Now that you have the SHA256 hash of your file, you need to sign the hash: the signature must be compatible with the bitcoin signature scheme (ECDSA).

The easiest way to generate the signature is to use Woleet.ID Server (aka WIDS): this application allows you to manage the identities of your users and seals, as well as their associated signature keys. It provides an API allowing to sign any hash or message using these keys.

Once installed and configured, you need to:

  • take note of the base URL of the signature endpoints of the server
  • generate an API token that you will use to authenticate
    This is out of scope of this procedure, so please see the related documentation for details.

📘

What else can I use?

There is plenty of tools you can use to generate bitcoin compatible/ECDSA signatures.

Let's do it using a simple curl command to do a GET request:

curl --oauth2-bearer <WIDS API token> https://<WIDS signature endpoints base URL>/sign?hashToSign=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

{
  "pubKey":"17wD8dR42yPvMqngaVhftypFxfYNpvPj42",
  "signedHash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "signature":"ID5Vd2re4VtcPxhZ+TKDOOd3wBuwpRW6VoxdQElamqH/VACfxy6QKTHyio4CNg3IkKtL7WfLyLywR9vVuE4muRE=",
  "identityURL":<WIDS identity URL>
}

👍

Include the identity of the seal to the signed data

You can ask for the identity of the seal (or a part of it) to be included in the signed data by adding the optional parameter identityToSign=ALL. This allows for verification tools to display the identity of the seal even if the identity server is down at the time of verification, and to verify that this identity matches the one known on the identity server.
If you do so, the data that is actually signed is no longer the content of the hashToSign parameter, but a hash equals to SHA256(signedHash + signedIdentity + signedIssuerDomain) (these 3 parameters can be found in the returned JSON).

Now you have the signature and its associated public key and identity URL, you can create the signature anchor by providing them to the anchor creation endpoint of the Woleet API.

Let's do it using a simple curl command to do a POST request:

curl --request POST \
  -u <email>:<password> \
  --url https://api.woleet.io/v1/anchor \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"name":"My anchor","signedHash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","signature":"ID5Vd2re4VtcPxhZ+TKDOOd3wBuwpRW6VoxdQElamqH/VACfxy6QKTHyio4CNg3IkKtL7WfLyLywR9vVuE4muRE=","pubKey":"17wD8dR42yPvMqngaVhftypFxfYNpvPj42","identityURL":<WIDS identity URL>}'

{
  "id":"331674c8-0563-45f4-b363-e6cebc0625bb",
  "created":1591631377577,
  "lastModified":1591631377577,
  "name":"My anchor",
  "signedHash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "pubKey":"17wD8dR42yPvMqngaVhftypFxfYNpvPj42",
  "signature":"ID5Vd2re4VtcPxhZ+TKDOOd3wBuwpRW6VoxdQElamqH/VACfxy6QKTHyio4CNg3IkKtL7WfLyLywR9vVuE4muRE=",
  "identityURL":<WIDS identity URL>,
  "status":"WAIT"
}

Your signature anchor is created!

Its identifier can be found in the id attribute of the JSON object returned in the body of the response.

Note that its status is WAIT, meaning that the seal is waiting to be anchored in the bitcoin blockchain. The Woleet platform batches anchoring requests, so you will have to wait a mean time of 3 hours to get your proof of existence.

You can probe your anchor status at any time with a simple GET request.
If you have a backend server, it is highly recommended to use our callback service to be informed in realtime:

curl --request GET \
  -u <email>:<password>
  --url https://api.woleet.io/v1/anchor/331674c8-0563-45f4-b363-e6cebc0625bb \
  --header 'accept: application/json'
  
{
  "id":"331674c8-0563-45f4-b363-e6cebc0625bb",
  "created":1591631377577,
  "lastModified":1591631377577,
  "name":"My anchor",
  "hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "status":"CONFIRMED"
}

When the status is SENT (sent to the bitcoin blockchain) or CONFIRMED (confirmed 6 times by the bitcoin blockchain) you can (and really should) retrieve your proof of seal:

curl --request GET \
  --url https://api.woleet.io/v1/receipt/331674c8-0563-45f4-b363-e6cebc0625bb \
  --header 'accept: application/json'
  
{
  "signature" : { ... },
  "targetHash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "merkleRoot":"ec4a21d9b4f4c60e34700012bfe0b3dacd46d928e9ff7cb12bbc1e8dc567093b",
  "proof":[{"left":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},
  {"right":"164ea6ef8984a1be9a9064e40f58e1e99f82aa9ecff29bd1a07bee74965f7a49"},
  {"left":"19d54943a3ae4172fef2856f953d1eb988e7b512c9b9d06c53e225ae94c231c0"},
  {"right":"06f5f7540b35461cd1b9366a9e765c9165bd99c6679cb49d2c67bfae851c54cf"},
  {"left":"a3ce3262b6c61042fd7097c19b3af3acc72ceb63dcf53ef2017f184ec4740c78"},
  {"right":"4a15851b48ffdafe0212c7e489b1859cee3d7a53dde40393711ec957020f7b02"}],
  "anchors":[{"sourceId":"096e1f0f2406210db9b1ba0a1d08615ed8e4bebbdf444c541a21a028ed6829eb",
 "type":"BTCOpReturn"}],
  "type":"ChainpointSHA256v2",
  "@context":"https://w3id.org/chainpoint/v2"
}

You get your proof of seal! Keep it along the proven file: you need both to verify the proof.

You are all set!

📘

What about Java, Javascript, Node, Python and PHP code samples?

For other programming languages, you can generate sample code using our actionable API Reference.