Notarizing a file by its hash with metadata

Start the Python shell and configure its session.

The following variables should be available now:

>>> base_url  # the base URL of the API
'https://eu2-cloud.acronis.com/api/notary/v2'
>>> auth  # the 'Authorization' header value with the access token
{'Authorization': 'Bearer 8770b34b74f9e4d9424eff50c38182bb4ae7f5596582ae61900b1b6a23e3ec58'}

Define a variable named file_path, and then assign the path to your file to this variable:
```
>>> file_path = '<path to file>'
```
Important

If the path contains backslashes, remember to escape them with an additional backslash.
Open the file for reading in binary mode:
```
>>> file = open(file_path, 'rb')
```

Calculate the hash value of the file contents by using the SHA-256 algorithm:

>>> sha256 = hashlib.sha256()
>>> chunk = file.read(128 * sha256.block_size)
>>> while chunk:
...     sha256.update(chunk)
...     chunk = file.read(128 * sha256.block_size)
>>> file_hash = sha256.hexdigest()
>>> file_hash
'2c7c3d5f244f1a40069a32224215e0cf9b42485c99d80f357d76f006359c7a18'

Close the file:
```
>>> file.close()
```

Fetch the file name from the file path:

>>> file_name = os.path.basename(file_path)

Define a variable named metadata, and then assign an object with the following JSON parameters to this variable:
```
>>> metadata = {
...     'GUID': file_name,
...     'eTag': file_hash
... }
```
You may specify other information about the file in additional keys. Refer to the API reference for more information.
Warning
- Do not specify sensitive information in this object because the entire object contents will be available in the notarization certificate that will be created for the object when you send it to the notary service.
- Key names are case-sensitive. For example, if you do not write eTag as shown in the snippet above, the notary service will calculate the SHA-256 hash value of the entire object contents and write this value to the blockchain. Thus, an attempt to later verify the file’s authenticity will fail.

Convert the metadata object to a JSON text:

>>> metadata = json.dumps(metadata, indent=4)

Send a POST request with the JSON text to the /meta endpoint:

>>> response = requests.post(
...     f'{base_url}/meta',
...     headers={'Content-Type': 'application/json', **auth},
...     data=metadata,
... )

Check the status code of the response:
```
>>> response.status_code
200
```
Status code 200 means that the notary service has received the object and started notarizing it.

A different status code means that an error has occurred. For the details, refer to “Status and error codes”.
Convert the JSON text that the response body contains to an object, and then fetch the ID of the created notarization certificate:
```
>>> certificate_id = response.json()['certificate_id']
>>> certificate_id
'7605f73deaee7b071a570b3ac20cc9fe7a3abf337be7c86c55c28af9d3d8435c'
```
Important

The certificate_id will be required in the requests to the verification endpoints.
Check the notarization status by sending a GET request to the /certificates/{certificate_id} endpoint. We recommend waiting about an hour before checking because the notarization process may take a long time:
```
>>> response = requests.get(f'{base_url}/certificates/{certificate_id}', headers=auth)
```

Check the status code of the response:

>>> response.status_code
200

Status code 200 means that the request was successful.

A different status code means that an error has occurred. For the details, refer to “Status and error codes”.

Also, the response body contains the notarization certificate object formatted as a JSON text. When converted to an object, it will look as follows:

>>> pprint.pprint(response.json())
{'contract': '0xd10e3Be2bc8f959Bc8C41CF65F60dE721cF89ADF',
 'eventtime': '2019-11-11T13:07:07.004366Z',
 'id': '7605f73deaee7b071a570b3ac20cc9fe7a3abf337be7c86c55c28af9d3d8435c',
 'merkle_proof': '[{"left":"88c20ca21dd6fa9e0a64c7e981a012812bbca152010195cd4296d959cfa35f1e"}]',
 'merkle_root': '6d05fb9f0c2cff4942987661a44e71f0f554d435ce494dd3e7a21df6c6ba963c',
 'notarized_location': 'beta-baas',
 'object': {'eTag': '2c7c3d5f244f1a40069a32224215e0cf9b42485c99d80f357d76f006359c7a18',
            'key': '<file name>',
            'metadata': {
                'GUID': '<file name>',
                'eTag': '2c7c3d5f244f1a40069a32224215e0cf9b42485c99d80f357d76f006359c7a18'
            },
            'sequencer': 'DEF04BD0C5114542F8',
            'size': 89},
 'blockchain': 'eth',
 'qr_code': 'data:image/png;base64,iVBORw0KGgoAAAANSUh...',
 'sender': '0x201354729f8d0f8b64e9a0c353c672c6a66b3857',
 'signee_details': {'tenant_name': 'John Doe'},
 'timestamp': 1573572432,
 'txid': '0x6494a098f6487ebbcfa85b7cbe64c1f9f077f03866477b67be64320ea109fa73',
 'version': '3'}

If the notarization is complete:

The txid key contains the hash of the blockchain transaction that can be viewed on https://etherscan.io/tx/{txid}.
The contract, sender, merkle_root, and merkle_proof keys contain the blockchain transaction details.
The timestamp key contains the Unix time when the hash value of the file contents was written to the blockchain (notarization completion time).
The eTag key of the object object contains the actual hash value that was written to the blockchain.
The web version of the notarization certificate is available at https://eu2-cloud.acronis.com/notary/certificate/{certificate_id}.

Empty txid, contract, merkle_proof, merkle_root, and sender keys mean that the notarization is still in progress and the web version of the certificate is not created yet.

Full code example

#!/usr/bin/env python3

import requests  # Will be used for sending requests to the API.
import hashlib   # Will be used for calculating hash values.
import os.path   # Will be used for path-related operations.
import pprint    # Will be used for formatting the output of JSON objects received in API responses.
import json      # Will be used for converting dictionaries into JSON text

# Define variables named "LOGIN" and "PASSWORD" and then assign them with your account credentials
LOGIN = '<your login>'        # Change login here
PASSWORD = '<your password>'  # Change password here

# Define a variable named "cloud_url" and then assign it with the URL of the cloud platform
cloud_url = 'https://cloud.acronis.com'

# Fetch the URL of the data center where your account is located by sending a GET request to the "/api/1/accounts" endpoint
response = requests.get(
    f'{cloud_url}/api/1/accounts',
    params={'login': LOGIN}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and store the data center URL
# in a variable that will be used in further requests
server_url = response.json()['server_url']

# Define a variable named "account_creds", and then assign the username and password to this variable
account_creds = {
    'username': LOGIN,
    'password': PASSWORD
}

# Generate a token by sending a POST request to the "/api/2/idp/token" with your account credentials to the cloud platform
response = requests.post(
    f'{server_url}/api/2/idp/token',
    headers={'Content-Type': 'application/x-www-form-urlencoded'},
    data={'grant_type': 'password', **account_creds}
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and then assign it to a variable named "token_info"
token_info = response.json()

# Define a variable named "auth" and then assign it with a dictionary with "Authorization" key containing
# token string formatted as "Bearer <access_token>"
auth = {
    'Authorization': 'Bearer ' + token_info['access_token']
}

# Define a variable named "base_url", and then assign the API base URL using the data center URL
# to this variable
base_url = f'{server_url}/api/notary/v2'

# Define a variable named "file_path" and then assign it with the path to your file
file_path = '<path to file>'  # Change path to file here

# Open the file for reading in binary mode
file = open(file_path, 'rb')

# Calculate the SHA-256 hash of the file
sha256 = hashlib.sha256()
chunk = file.read(128 * sha256.block_size)
while chunk:
    sha256.update(chunk)
    chunk = file.read(128 * sha256.block_size)
file_hash = sha256.hexdigest()

# Close the file
file.close()

# Fetch the name of the file and then assign its value to the "file_name" variable
file_name = os.path.basename(file_path)

# Define a variable named "metadata" and then assign it with a dictionary with a "GUID" key containing the
# name of the file, and "eTag" key containing the hash of the file
metadata = {
    'GUID': file_name,
    'eTag': file_hash
}

# Convert the "metadata" dictionary to a JSON text
metadata = json.dumps(metadata, indent=4)

# Send the file hash for notarization by sending a POST request to the "/meta" endpoint
response = requests.post(
    f'{base_url}/meta',
    headers={'Content-Type': 'application/json', **auth},
    data=metadata,
)
response.raise_for_status()

# Convert the JSON text that the response body contains to a dictionary and fetch the certificate ID
certificate_id = response.json()['certificate_id']

# Fetch the notarization certificate by sending a GET request to the "/certificates/{certificate_id}" endpoint
response = requests.get(f'{base_url}/certificates/{certificate_id}', headers=auth)
response.raise_for_status()