1. Overview

With the Blockchain Proof API it is easy to prove or disprove existence of data at a certain point in time. Behind the scenes it stores entries using the Factom (bitcoin), Multichain or Ethereum blockchain by means of our generic blockchain API.

The flow is generally as follows:
1. Make sure a configuration is present
2. Register content by uploading a file, some content, or providing a Stream Location from the Storage API. When you upload content you have to tell the API whether the data has already been hashed or not. If not, or when uploading a file or stream location, the API will take care of the hashing
3. Verify content by uploading a file, some content, or providing a Stream Location from the Storage API. When you upload content you have to tell the API whether the data has already been hashed or not. If not, or when uploading a file or stream location, the API will take care of the hashing. You will get back whether the content has been registered previously or not

Full API Documentation: https://docs.sphereon.com/api/blockchain-proof/0.10/html
Interactive testing: A web based test console is available in the Sphereon API Store at https://store.sphereon.com

1.1. Version information

Version : 0.10

1.2. Contact information

Contact : Sphereon DevOps Team
Contact Email : dev@sphereon.com

1.4. URI scheme

Host : gw.api.cloud.sphereon.com
BasePath : /blockchain/proof/0.10
Schemes : HTTPS

1.5. Tags

  • Configuration : Configuration related API’s

  • Registration : Registration related API’s

  • Verification : Verification related API’s

  • existence-controller : Existence Controller

2. Introduction

The Sphereon Proof API provides blockchain backed Proof of Existence API, where the blockchain is hidden away for the most part. The key benefits are:

  • Prove or disprove the existence of any file or content at a specific time

  • Prove a file or content has been tampered with

  • Easy registration and verification of documents by only working with files

  • Register hashes of your own content, by leaving everything up to us, or providing the hash yourself

  • Registration integration in your own Line of Business application or DMS for instance, whilst verifying from another system

  • Backed by public, private or permissioned blockchains like Factom (bitcoin), Ethereum, Multichain, Hyperledger

  • You don’t have to worry about leaking confidential information on a public blockchain. Merely hashes are being used

  • Use this API to register hashes and use our easy-blockchain API to create links to and from the information to create powerful integrations

2.1. Privacy and file storage

Since we only register the hash of the content/file you submit, you don’t have to worry about security or privacy issues. The file is needed to generate the fingerpring (SHA-256 hash) of the contents. We will never store the file. If you don’t take our word for it, there is always the possibility to determine the hash yourself and only submit that hash.
A hash is a mathematical one-way function, meaning it is impossible to retrieve the original content from the hash itself. This is easiest to understand by knowing that the SHA256 hash is 32 characters long, no matter of the file/content size.

2.2. Three modes of interacting with content

  • Register hash of a file by uploading a file both for registration and verification

    • we never store the file itself!

  • Provide your own content. We can create and register the hash for you, or you provide the hash yourself

  • Combine the registration and verification with objects from our Storage API. You only provide the location and we do the rest

2.3. Easy Blockchain API relationship

The Proof and Existence API is build on top of the Easy Blockchain API. Where the latter is an API specifically designed to store information in a blockchain agnostic way, the Proof API hides most of the blockchain implementation.
More information about the Easy Blockchain API: https://docs.sphereon.com/api/easy-blockchain/0.10/html

2.4. Storage API relationship

Like mentioned above there is a way registering and verifying files using our Storage API. When you store a file using our Storage API or retrieve information you will get back a StreamLocation JSON object that tells you where the file is stored. You can use this object to register of verify a file. This means you have direct integration of the Proof API with files stored in for instance Amazon S3 ® or Google Cloud Storage ®.
More information about the Storage API: https://docs.sphereon.com/api/storage/0.8/html

3. Storage of the hashes

We support 2 modes of storing hashes of files. This is the so called contentRegistrationMode in the configuration.

  • All hashes in a single chain

  • A unique chain per single hash

Of course it is possible to use both modes simultaneously. We then store the hash in a single chain as well as a new chain for every single hash.

3.1. Single chain for all hashes

The single chain for all file hashes is the most simple solution. It stores al hashes of the content you supply in a single and constant chain specifically created for your application. You can only register and verify hashes and it’s timestamps. Integration with other information means you have to point that information to the entry Ids in this chain. You could create chain links from other chains to entries in this single chain (see Easy Blockchain API https://docs.sphereon.com/api/easy-blockchain/0.10/html). However it is not possible to create links the other way around, thus from entries in this chain to other locations. If there is a need for 2 way links use a chain per hash.

3.2. Unique chain for a single hash

In this mode we create a new chain based on the hash value. The first entry of this chain will be the registration of the hash. The benefit of this solution is that it allows you to do more with information in this chain in a later stage.
This mode also means wo do not have to traverse the single proof chain to find your hash. We directly know whether the chain is there or not.

When you have to store a lot of hashes, we always recommend using this method.

Extra possibilities using this method are for instance:

The drawback of this method is that creating a chain is a relatively expensive operation, costing 11 times the price of a single hash registration in an existing chain. The registration is still really cheap though.

4. SDKs

Our API’s are based on the OpenAPI specification (formerly known as Swagger specification). This means you can pickup our REST API definition file and generate classes for your favorite programming language.

4.1. Provided SDKs and generated SDKs

4.1.1. Provided SDKs

For some popular programming languages we provide you with an SDK implementation
These SDKs are to be found on GitHub: https://github.com/Sphereon-SDK/blockchain-proof-sdk

4.1.2. Generate your own SDK

Please feel free to generate an SDK for your own programming language using our Swagger file. Please note that we do not officially support your SDK, but unofficially we are here to help of course.
You can use Swagger codegen for this (https://swagger.io/swagger-codegen). Swagger codegen support almost 100 programming languages.

Please use version 2.X of swagger codegen with our current API’s

4.2. Version compatibility between SDK and API

Al of our REST API’s follow the versioning scheme below

XX.YY

When the major number (XX) changes this means we completely redesign an API.
Minor number (YY) changes means smaller backwards comptible breaks within the API. An API can be changed forward compatible within the same minor number.

Our SDK follow the below versioning scheme

XX.YY.ZZ

The major (XX) and minor (YY) number always map directly to the accompanying REST API version.
The micro number (ZZ) is used if we add forward compatible changes to our REST API, or when bugs are encountered in a specific SDK.

5. Resources

5.1. Configuration

Configuration related API’s

5.1.1. Create a new configuration

POST /config
Description

Create a new configuration

Parameters
Type Name Description Schema

Body

request
required

Create a new Proof of Existence configuration using the provided settings. The context points to a context of the Easy Blockchain API. When you have no own context, simply use 'multichain' without the quotes as context. You will be using our multichain ledger then, which is recomended during development/testing

CreateConfigurationRequest

Responses
HTTP Code Description Schema

200

Configuration already exists

ConfigurationResponse

202

Configuration request received. Since we do register on the blockchain and this takes some time you will get back a 202 instead of a 201

ConfigurationResponse

400

Invalid configuration request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
var settings = new ChainSettings(Version: ChainSettings.VersionEnum.NUMBER_1, Secret: Encoding.UTF8.GetBytes("very secret"))
{
    HashAlgorithm = ChainSettings.HashAlgorithmEnum._256,
    ContentRegistrationChainTypes = new List<ChainSettings.ContentRegistrationChainTypesEnum>
    {
        ChainSettings.ContentRegistrationChainTypesEnum.PERHASHPROOFCHAIN,
        ChainSettings.ContentRegistrationChainTypesEnum.SINGLEPROOFCHAIN
    }
};

var createConfiguration = new CreateConfigurationRequest(Name: ExampleConfigName,
    InitialSettings: settings,
    Context: TestContextMultichain, AccessMode: CreateConfigurationRequest.AccessModeEnum.PRIVATE);

var configurationResponse = _configurationApi.CreateConfiguration(createConfiguration);
Example HTTP request
POST /blockchain/proof/0.10/config HTTP/1.1
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 569

{
  "accessMode" : "PRIVATE",
  "contentExtractionSettings" : {
    "binaryComparison" : true,
    "contentExtraction" : true,
    "minimumContentExtractionCharacters" : 40
  },
  "name" : "example",
  "context" : "multichain",
  "initialSettings" : {
    "version" : 1,
    "hashAlgorithm" : "SHA_256",
    "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
    "signatureSettings" : {
      "base64Secret" : "secret",
      "keyQualification" : "FULLY_QUALIFIED_KEY_ID",
      "signatureType" : "SECRET"
    }
  }
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1042

{
  "configuration" : {
    "id" : "8e4d98a5-5a0d-48b3-8ceb-18f1c0baf84b",
    "owner" : "LTEyMzQubm8gc3Vic2NyaWJlci5ibG9ja2NoYWluLXByb29mLW1zLlNBTkRCT1g=",
    "context" : "multichain",
    "name" : "example",
    "accessMode" : "PRIVATE",
    "chainSettings" : {
      "version" : 1,
      "hashAlgorithm" : "SHA_256",
      "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
      "singleProofChain" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
      "signatureSettings" : {
        "base64Secret" : "secret",
        "keyQualification" : "FULLY_QUALIFIED_KEY_ID",
        "signatureType" : "SECRET"
      }
    },
    "contentExtractionSettings" : {
      "binaryComparison" : true,
      "contentExtraction" : true,
      "minimumContentExtractionCharacters" : 40
    },
    "singleProofChain" : {
      "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
      "context" : "multichain"
    },
    "validFrom" : null
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/config' -i -X POST -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -H 'Content-Type: application/json' -d '{
  "accessMode" : "PRIVATE",
  "contentExtractionSettings" : {
    "binaryComparison" : true,
    "contentExtraction" : true,
    "minimumContentExtractionCharacters" : 40
  },
  "name" : "example",
  "context" : "multichain",
  "initialSettings" : {
    "version" : 1,
    "hashAlgorithm" : "SHA_256",
    "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
    "signatureSettings" : {
      "base64Secret" : "secret",
      "keyQualification" : "FULLY_QUALIFIED_KEY_ID",
      "signatureType" : "SECRET"
    }
  }
}'

5.1.2. Get configuration

GET /config/{configName}
Description

Get the configuration for registration/verification

Parameters
Type Name Description Schema

Path

configName
required

The configuration name for this operation

string

Responses
HTTP Code Description Schema

200

The configuration

ConfigurationResponse

400

Invalid request

ErrorResponse

404

Configuration not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
var configurationResponse = _configurationApi.GetConfiguration(ExampleConfigName);
Example HTTP request
GET /blockchain/proof/0.10/config/example HTTP/1.1
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1042

{
  "configuration" : {
    "id" : "8e4d98a5-5a0d-48b3-8ceb-18f1c0baf84b",
    "owner" : "LTEyMzQubm8gc3Vic2NyaWJlci5ibG9ja2NoYWluLXByb29mLW1zLlNBTkRCT1g=",
    "context" : "multichain",
    "name" : "example",
    "accessMode" : "PRIVATE",
    "chainSettings" : {
      "version" : 1,
      "hashAlgorithm" : "SHA_256",
      "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
      "singleProofChain" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
      "signatureSettings" : {
        "base64Secret" : "secret",
        "keyQualification" : "FULLY_QUALIFIED_KEY_ID",
        "signatureType" : "SECRET"
      }
    },
    "contentExtractionSettings" : {
      "binaryComparison" : true,
      "contentExtraction" : true,
      "minimumContentExtractionCharacters" : 40
    },
    "singleProofChain" : {
      "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
      "context" : "multichain"
    },
    "validFrom" : null
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/config/example' -i -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -H 'Content-Type: application/json'

5.2. Registration

Registration related API’s

5.2.1. Register content

PUT /existence/{configName}/content
Description

Register content. Please provide the content in the request. You also have to provide whether you have hashed the content yourself, or whether is should be done on the server side

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The configuration name this operation

string

Body

existence
required

Register content using the current settings

ContentRequest

Responses
HTTP Code Description Schema

200

Content already registered

RegisterContentResponse

202

Registration request received

RegisterContentResponse

400

Invalid registration request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
var requestId = Guid.NewGuid().ToString();
byte[] RegisteredContent = Encoding.Default.GetBytes("test-" + requestId);

var contentRequest = new ContentRequest(Content: RegisteredContent,
        HashProvider: ContentRequest.HashProviderEnum.SERVER,
        RequestId: requestId
);
var response = _registrationApi.RegisterUsingContent(ExampleConfigName, contentRequest);
Example HTTP request
PUT /blockchain/proof/0.10/existence/example/content HTTP/1.1
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
requestId: my-unique-request-id
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 437

{
  "content" : "MTU0MjA2NzE3OTk3NyANCkxvcmVtIGlwc3VtIGRvbG9yIHNpdCBhbWV0LCBjb25zZWN0ZXR1ciBhZGlwaXNjaW5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IGxhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLiBVdCBlbmltIGFkIG1pbmltIHZlbmlhbSwgcXVpcyBub3N0cnVkIGV4ZXJjaXRhdGlvbiB1bGxhbWNvIGxhYm9yaXMgbmlzaSB1dCBhbGlxdWlwIGV4IGVhIGNvbW1vZG8gY29uc2VxdWF0LiA=",
  "hashProvider" : "SERVER",
  "signatureSettings" : null,
  "fileName" : null
}
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 1110

{
  "contextName" : "multichain",
  "singleProofChain" : {
    "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
    "context" : "multichain",
    "entryId" : "32dcbe178885c9b2faaea15872ea641e4845d6ab693ee193ce0bb255d32046e4",
    "registrationState" : "PENDING",
    "signatureState" : null,
    "signatureStateMessage" : null
  },
  "perHashProofChain" : {
    "chainId" : "b6fb13c28f27b58176cd2ca921211483308c3d8a0fdfa8044498000979af2231",
    "context" : "multichain",
    "entryId" : "21d5a8b213a3d0d04b230e62e1407354c80021ab8bf7899ca9c82692de460c85",
    "registrationState" : "PENDING",
    "signatureState" : null,
    "signatureStateMessage" : null
  },
  "requestId" : "my-unique-request-id",
  "hash" : "b9143a66cf5aba3eb9d2834f4b34c3da47f4a8ce8647b73ac4ec26bedf4ecf2c",
  "hexSignature" : "6fdd78ddaeba71fe5a6dadde6fd776f37e1fe1bdf873775ae3b7f86bc71ef3ae3b6fbdda73879cdba6de75fe1e71fd9c",
  "base64Signature" : "zLjjHsGssZ578hreRWqiyy9A+ObUlMzibbXy8KKqNE0=",
  "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ]
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/existence/example/content' -i -X PUT -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -H 'requestId: my-unique-request-id' -H 'Content-Type: application/json' -d '{
  "content" : "MTU0MjA2NzE3OTk3NyANCkxvcmVtIGlwc3VtIGRvbG9yIHNpdCBhbWV0LCBjb25zZWN0ZXR1ciBhZGlwaXNjaW5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IGxhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLiBVdCBlbmltIGFkIG1pbmltIHZlbmlhbSwgcXVpcyBub3N0cnVkIGV4ZXJjaXRhdGlvbiB1bGxhbWNvIGxhYm9yaXMgbmlzaSB1dCBhbGlxdWlwIGV4IGVhIGNvbW1vZG8gY29uc2VxdWF0LiA=",
  "hashProvider" : "SERVER",
  "signatureSettings" : null,
  "fileName" : null
}'

5.2.2. Register hash using the Storage API

PUT /existence/{configName}/streams/location
Description

Register a hash of file/blob by supplying a Stream location of the Storage API. This Stream Location maps to a location of a file/blob on some remote cloud storage. Hashing will be done on the server side Please note that the binary data itself will not be stored, only the hash. Use the registerUsingContent endpoint if you’d like to store content

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The configuration name this operation

string

Body

streamLocation
required

The stream locations on storage

StreamLocation

Responses
HTTP Code Description Schema

200

Content already registered

RegisterContentResponse

202

Registration request received

RegisterContentResponse

400

Invalid registration request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

5.2.3. Register bytestream/file hash

PUT /existence/{configName}/streams/multipart
Description

Register a hash of content by supplying a file or some other binary data. Hashing will be done on the server side. Please note that the binary data itself will not be stored, only the hash. Use the registerUsingContent endpoint if you’d like to store content

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The configuration name this operation

string

Query

fileName
optional

Optional input file name. Needed when using bytestreams instead of filestreams

string

FormData

stream
required

The binary data (not hashed). Hashing will be done on the server side. The binary data will not be stored

file

Responses
HTTP Code Description Schema

200

Content already registered

RegisterContentResponse

202

Registration request received

RegisterContentResponse

400

Invalid registration request

ErrorResponse

Consumes
  • multipart/form-data

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
var requestId = Guid.NewGuid().ToString();
byte[] RegisteredContentForStream = Encoding.Default.GetBytes("test content -" + requestId);
Stream stream = new MemoryStream(RegisteredContentForStream);

var response = _registrationApi.RegisterUsingStream(ExampleConfigName, stream, "MemoryFileName.txt"); (1)
  1. You can optionally supply a filename when you use a memorystream. It is currently only used to generate a request id.

Example HTTP request
PUT /blockchain/proof/0.10/existence/example/streams/multipart HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
Host: gw.api.cloud.sphereon.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=stream
Content-Type: plain/text

Sample register content
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 1100

{
  "contextName" : "multichain",
  "singleProofChain" : {
    "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
    "context" : "multichain",
    "entryId" : "c6a52f615308104898f72c86486d448481ba48717066a2f5bd5abd5d3c110e41",
    "registrationState" : "PENDING",
    "signatureState" : null,
    "signatureStateMessage" : null
  },
  "perHashProofChain" : {
    "chainId" : "2522a3dc2467581ad8a8f526ca03542031414ea52b75d3e8261019bed086954a",
    "context" : "multichain",
    "entryId" : "b1ed92acef064baa338211938cb9e4a18ee71553b1110cd14b987aec5d18b2f2",
    "registrationState" : "PENDING",
    "signatureState" : null,
    "signatureStateMessage" : null
  },
  "requestId" : "sample.txt",
  "hash" : "06b54a9e7801dcc46780186790723573f8a484e476b5d812e6181db98cdec258",
  "hexSignature" : "d3a6f9e1af5eefcd3575c738ebbf34d7cebbf74ef6df9ef77fc6b8f387b8efa6f977cd767bad7cd5d6fdf1c75e736e7c",
  "base64Signature" : "clOhVyf/7VoXP/UpZCCy/cVG6bQ+AdhkjQrVclBBc8E=",
  "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ]
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/existence/example/streams/multipart' -i -X PUT -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -F 'stream=@sample.txt;type=plain/text'

5.3. Verification

Verification related API’s

5.3.1. Verify content

POST /existence/{configName}/content
Description

Verify content. Please provide the content in the request. You also have to provide whether you have hashed the content yourself, or whether is should be done on the server side

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The configName for this operation

string

Body

existence
required

Verify content using the current settings

ContentRequest

Responses
HTTP Code Description Schema

200

Content exists or not

VerifyContentResponse

400

Invalid verification request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
byte[] RegisteredContent = Encoding.Default.GetBytes("test-" + requestId);
var contentRequest = new ContentRequest(RequestId: "anything",
         HashProvider: ContentRequest.HashProviderEnum.SERVER,
         Content: RegisteredContent
);
var response = _verificationApi.VerifyUsingContent(ExampleConfigName, contentRequest);
Example HTTP request
POST /blockchain/proof/0.10/existence/example/content HTTP/1.1
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
requestId: a-new-request-id
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 165

{
  "content" : "dVJRNlpzOWF1ajY1MG9OUFN6VEQya2YwcU02R1I3YzZ4T3dtdnQ5T3p5dz0=",
  "hashProvider" : "CLIENT",
  "signatureSettings" : null,
  "fileName" : null
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1414

{
  "contextName" : "multichain",
  "singleProofChain" : {
    "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
    "context" : "multichain",
    "entryId" : "0ae8cc332c0dad774aacf8b0238ef40c9a44792069e0ee78f14359901ffd40d9",
    "registrationState" : "NOT_REGISTERED",
    "signatureState" : "NOT_FOUND",
    "signatureStateMessage" : "The signature could not be determined because no entry was found."
  },
  "perHashProofChain" : {
    "chainId" : "2cd91171182e527acc72dd253e562dcb3cb8e59dc78df624a07c70eb2ad7985b",
    "context" : "multichain",
    "entryId" : "fc357ce142f8028060aa8aada1bcf06c11091e03dac8a823a8b35cd67ccc7f74",
    "registrationState" : "NOT_REGISTERED",
    "signatureState" : "NOT_FOUND",
    "signatureStateMessage" : "The signature could not be determined because no entry was found."
  },
  "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
  "requestId" : "a-new-request-id",
  "registrationState" : "NOT_REGISTERED",
  "registrationTime" : null,
  "signatureState" : "NOT_FOUND",
  "signatureStateMessage" : "The signature could not be determined because no entry was found.",
  "hash" : "uRQ6Zs9auj650oNPSzTD2kf0qM6GR7c6xOwmvt9Ozyw=",
  "hexSignature" : "b9143a66cf5aba3eb9d2834f4b34c3da47f4a8ce8647b73ac4ec26bedf4ecf2c",
  "base64Signature" : "EpXweuYRs5A6Vk99eFvquw1BCxUFk33fVd+iM4Pyvcw="
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/existence/example/content' -i -X POST -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -H 'requestId: a-new-request-id' -H 'Content-Type: application/json' -d '{
  "content" : "dVJRNlpzOWF1ajY1MG9OUFN6VEQya2YwcU02R1I3YzZ4T3dtdnQ5T3p5dz0=",
  "hashProvider" : "CLIENT",
  "signatureSettings" : null,
  "fileName" : null
}'

5.3.2. Verify hash using the Storage API

POST /existence/{configName}/streams/location
Description

Verify a hash of file/blob by supplying a Stream location of the Storage API. This Stream Location maps to a location of a file/blob on some remote cloud storage. Hashing will be done on the server side Please note that the binary data itself will not be stored, only the hash. Use the registerUsingContent endpoint if you’d like to store content

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The context for this operation

string

Body

streamLocation
required

The stream location on storage

StreamLocation

Responses
HTTP Code Description Schema

200

Content exists or not

VerifyContentResponse

400

Invalid verification request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

5.3.3. Verify bytestream/file hash

POST /existence/{configName}/streams/multipart
Description

Verify a hash of content by supplying a file or some other binary data. Hashing will be done on the server side. Please note that the binary data itself will not be stored, only the hash. Use the registerUsingContent endpoint if you’d like to store content

Parameters
Type Name Description Schema

Header

base64Secret
optional

An alternate secret key in base64 format that overrides the value in your configuration.

string

Header

keyId
optional

An alternate crypto keys API id that will be used for signature generation.

string

Header

requestId
optional

Optional request id

string

Header

suppliedSignature
optional

An alternate supplied Signature in base64 format that overrides the signature generation.

string

Path

configName
required

The configuration name this operation

string

Query

fileName
optional

Optional input file name. Needed when using bytestreams instead of filestreams

string

FormData

stream
required

The binary data (not hashed). Hashing will be done on the server side. The binary data will not be stored

file

Responses
HTTP Code Description Schema

200

Content exists or not

VerifyContentResponse

400

Invalid verification request

ErrorResponse

Consumes
  • multipart/form-data

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example C# SDK
C#
byte[] RegisteredContent = Encoding.Default.GetBytes("test-" + requestId);
Stream stream = new MemoryStream(RegisteredContentForStream);

var response = _verificationApi.VerifyUsingStream(ExampleConfigName, stream, "MemoryFileName.txt"); (1)
  1. You can optionally supply a filename when you use a memorystream. It is currently only used to generate a request id.

Example HTTP request
POST /blockchain/proof/0.10/existence/example/streams/multipart HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954
Host: gw.api.cloud.sphereon.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=stream
Content-Type: plain/text

Sample verify content1542067211923
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1476

{
  "contextName" : "multichain",
  "singleProofChain" : {
    "chainId" : "ab9e21f1c9d759b248d3202030b4570b7435897ff17fb9203e8d24a0b560b9fd",
    "context" : "multichain",
    "entryId" : "e7e9f6fde2dc6b12ef0f6d067dc41417a3fb545ccf1628bcfa816694cbcd6ca8",
    "registrationState" : "NOT_REGISTERED",
    "signatureState" : "NOT_FOUND",
    "signatureStateMessage" : "The signature could not be determined because no entry was found."
  },
  "perHashProofChain" : {
    "chainId" : "f0badbbad15f18701df238cea2fe4e1a198e4907580665ecaa0545f08c487ca1",
    "context" : "multichain",
    "entryId" : "b63de40b3e85a9bb04fee58294daf48fbd4720e302ebb9fb6738bc5a521bd410",
    "registrationState" : "NOT_REGISTERED",
    "signatureState" : "NOT_FOUND",
    "signatureStateMessage" : "The signature could not be determined because no entry was found."
  },
  "contentRegistrationChainTypes" : [ "PER_HASH_PROOF_CHAIN", "SINGLE_PROOF_CHAIN" ],
  "requestId" : "not-registered-example.txt",
  "registrationState" : "NOT_REGISTERED",
  "registrationTime" : null,
  "signatureState" : "NOT_FOUND",
  "signatureStateMessage" : "The signature could not be determined because no entry was found.",
  "hash" : "eb7f69084b3930eba1f77011ae60b526def46b6d636287c5f274a42c27ff2fba",
  "hexSignature" : "79bedfebdd3ce1bdfddf479b6b57fbef4d7569eeb46f9dba75e7f8e9be9deb7eb6f3b7397f6ef86b8d9cdbb7dfd9f6da",
  "base64Signature" : "z9W72ZdZ8vj1LuntpC8egAWAzLI4muRDC5hWRVXC7Jw="
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/proof/0.10/existence/example/streams/multipart' -i -X POST -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer 4c795183-47ac-3a55-9352-a5b149109954' -F 'stream=@not-registered-example.txt;type=plain/text'

5.4. Existence-controller

Existence Controller

6. Security

6.1. oauth2schema

Type : oauth2
Flow : application
Token URL : https://gw.api.cloud.sphereon.com/token

Name Description

global

accessEverything

7. Definitions

7.1. ChainSettings

Existence ChainSettings. Normally you only supply them once during chain creation or during a settings update. You can also supply them during a content request, but then it is up to you to also supply the correct setting during verifyImpl

Name Description Schema

contentRegistrationChainTypes
required

A set of content registration chain types. This can be a single proof chain for all hashes, a more powerful chain per hash, or both

< enum (PER_HASH_PROOF_CHAIN, SINGLE_PROOF_CHAIN) > array

hashAlgorithm
optional

The hashing method used for the content. We always return and expect the hash in base64 form

enum (SHA_256, SHA_512)

signatureSettings
required

Settings that determine how the signature should be registered/verified

SignatureSettings

singleProofChain
optional

The proof chain Id linked to the current configuration. This is a shared proof chain for all registrations/hashes. Only when the single proof chain type has been configured.

string

version
required

The settings version (only 1 for now)

integer (int32)

7.2. CommittedChain

Committed Chain

Name Description Schema

chainId
optional
read-only

Chain Id

string

context
optional
read-only

The context

string

7.3. CommittedEntry

Commited Entry

Name Description Schema

chainId
optional
read-only

Chain Id

string

context
optional
read-only

The context

string

entryId
required
read-only

The entry Id for the registration

string

registrationState
required
read-only

The registration state of the entry

enum (NOT_REGISTERED, PENDING, REGISTERED)

registrationTime
optional
read-only

The registration time of the entry. Only when registration has occurred ofcourse

string (date-time)

signatureState
optional

This is the signature state.

enum (NOT_FOUND, UNSIGNED, INVALID, VERIFIED)

signatureStateMessage
optional

This is a message describing the signature state.

string

7.4. Configuration

The stored chainSettings from the chainSettings chain

Name Schema

accessMode
required
read-only

enum (PUBLIC, PRIVATE)

chainSettings
required

ChainSettings

contentExtractionSettings
optional

ContentExtractionSettings

context
required
read-only

string

id
required
read-only

string

name
required
read-only

string

singleProofChain
optional

CommittedChain

validFrom
required
read-only

string (date-time)

7.5. ConfigurationResponse

Committed context and settings response

Name Schema

configuration
required

Configuration

7.6. ContentExtractionSettings

Content extraction Settings. Normally proofs are done solely on the full binary content of the file itself. Sometimes you want to look at particular parts of the file. For instance the content of a PDF file. Adobe PDF changes the file on save as, whilst the contents stays the same

Name Description Schema

binaryComparison
required

Whether to do a binary comparison on the file
Example : false

boolean

contentExtraction
required

Whether to try a content extraction comparison on the file
Example : false

boolean

minimumContentExtractionCharacters
optional

When using content extraction. Only apply it to content that is larger than the amount of characters specified in here. Please note that you want enough entropy when using content extraction. We suggest to not go lower than this value

integer (int32)

7.7. ContentRequest

Content existence request

Name Description Schema

content
required

The content to register in base64.

string (byte)

fileName
optional

Optional fileName. Used when content extraction is enabled and SERVER hashing is being used. This allows better content extraction of binary file formats like Office files. Do not use when using CLIENT as hashProvider

string

hashProvider
required

When CLIENT is supplied the content should already have been hashed by you. When SERVER is supplied we will hash the content. Please note that we do not validate the hash when you supply it

enum (SERVER, CLIENT)

signatureSettings
optional

Optional signature settings like signature type

SignatureSettings

7.8. CreateConfigurationRequest

Create a context configuration

Name Description Schema

accessMode
required

The access mode for this configuration. Public means accessible to other tenants of the API as well. Currently public is only allowed for Sphereon itself

enum (PUBLIC, PRIVATE)

contentExtractionSettings
optional

ContentExtractionSettings

context
required

The Easy Blockchain API context. This has to be a context you created or a public context

string

initialSettings
required

The initial context settings.

ChainSettings

name
required

The configuration name.

string

7.9. Error

An error

Name Schema

cause
optional

Error

code
required

string

level
required

enum (INFO, WARNING, FATAL)

message
required

string

7.10. ErrorResponse

The error response

Name Schema

errors
optional

< Error > array

7.11. RegisterContentResponse

Committed Content response

Name Description Schema

base64Signature
required
read-only

The calculated signature in base64 form

string

contentRegistrationChainTypes
optional

A set of content registration targets

< enum (PER_HASH_PROOF_CHAIN, SINGLE_PROOF_CHAIN) > array

contextName
required

string

hash
required
read-only

The hash in base64 format that you supplied or that was calculated. This is the actual hash for the content

string

hexSignature
required
read-only

The calculated signature in hex form

string

perHashProofChain
optional

This is the proof chain specific for the current hash (if configured)

CommittedEntry

requestId
optional

string

signatureType
required
read-only

The signature type from the request or the default from the settings

enum (KEY_ID, SUPPLIED, SECRET, NONE)

singleProofChain
optional

This is the single proof chain where all hashes are stored (if configured)

CommittedEntry

7.12. SignatureSettings

How to calculate the signature

Name Description Schema

base64Secret
optional

An alternate Secret key that overrides the value in your configuration in base64. Used for generating a signature with a base64Secret

string

keyConfig
optional

Crypto keys config name when KEY_NAME_ONLY is supplied for key qualification

string

keyId
optional

Use a symmetric or asymmetric key from the crypto keys API to generate the signature.

string

keyQualification
optional

This determines whether yoy use fully qualified keyIds of the crypto-keys API in form (config/keys/keyname/version) or that you only use the keyname and provide the configuration here. The later means we will use the latest version by default

enum (KEY_NAME_ONLY, FULLY_QUALIFIED_KEY_ID)

signatureType
required

How to calculate the signature during registration and verification. Defaults to the configured value if omitted

enum (KEY_ID, SUPPLIED, SECRET, NONE)

suppliedSignature
optional

Only use this if you calculate your own signature. Otherwise always leave this blank! We will use the signature as is for registration/verification

string

7.13. StreamLocation

Location record of data stream

Name Description Schema

containerId
optional

The container Id

string

filename
optional

The current filename

string

folderPath
optional

The path of the folder in the container (if any). Please note that a folder can be virtual depending on the backend

string

id
optional
read-only

The auto generated ID for this location

string

originalFilename
optional

The original filename. Handy for later clientside naming

string

7.14. VerifyContentResponse

Verify Content response

Name Description Schema

base64Signature
required
read-only

The calculated signature in base64 form

string

contentRegistrationChainTypes
required

A set of content registration targets

< enum (PER_HASH_PROOF_CHAIN, SINGLE_PROOF_CHAIN) > array

contextName
required

string

hash
required
read-only

The hash in base64 format that you supplied or that was calculated. This is the actual hash for the content

string

hexSignature
required
read-only

The calculated signature in hex form

string

perHashProofChain
optional

This is the proof chain specific for the current hash, so a chain per hash (if configured)

CommittedEntry

registrationState
optional
read-only

This is the registration state from the singleProofChain or the perHashProofChain. If one of the chains has a registration this will return REGISTERED

enum (NOT_REGISTERED, PENDING, REGISTERED)

registrationTime
optional
read-only

This is the first registration time from the singleProofChain or the perHashProofChain

string (date-time)

requestId
optional

string

signatureState
optional

This is the signature state.

enum (NOT_FOUND, UNSIGNED, INVALID, VERIFIED)

signatureStateMessage
optional

This is a message describing the signature state.

string

signatureType
required
read-only

The signature type from the request or the default from the settings

enum (KEY_ID, SUPPLIED, SECRET, NONE)

singleProofChain
optional

This is the single proof chain where all hashes are stored in a single chain (if configured)

CommittedEntry