An Indy Tails Server is file server that is designed to receive, store and serve Hyperledger Indy Tails files. An Indy Tails Server is commonly used by issuers of Indy AnonCred verifiable credentials, particularly those that issued using Aries Cloud Agent Python.
An Indy Tails Server is file server that is designed to receive, store and serve Hyperledger Indy Tails files. Indy tails files are generated by an issuer of Indy AnonCred verifiable credentials when a Revocation Registry is created and must be published to a location accessible by all holders that receive a credential referenced in that Revocation Registry. The generated file is static, it does not change, and the credential holders use the tails file to produce a zero-knowledge proof of non-revocation about their credential and include it when responding to a proof request with a proof that includes claims from a revocable credential. If you are new to Indy AnonCreds Revocation, please review this document to understand how Indy revocation works, and where tails files fit in.
An Indy Tails Server is a customized file server that makes it easy for AnonCred
Issuers to publish tails files and for holders to access those tails files. A tails
file does not have to be published to an Indy Tails Server, they can be published
anywhere as long as there exists a URL accessible to all holders to access the tails
file. If holders are mobile iOS or Android apps, the URL must use SSL (e.g. must be
https:) due to the restrictions in those OS's. Support for publishing tails files
to an Indy Tails Server is built into
Aries Cloud Agent Python.
The following are some metrics about the size of Indy tails files. When an issuer creates a Revocation Registry, they give it a size corresponding to the number of Indy AnonCred credentials that can be issued from the Registry. The size of tails file grows linearly with the number of credentials in the Registry, and that size is a limiting factor on how big a Registry can be. If too large, the holders will have challenges in downloading and processing the tails file.
| Revocation Registry Size | Tail File Size | Proof Generation Time |
|---|---|---|
| 3000 | 768KB | ~4sec |
| 10000 | 2.6MB | ~5sec |
| 32768 | 8.4MB | ~7sec |
- Tests of Proof Generation used the Lissi-Wallet on a iPhone 12Pro
- 32768 is the Revocation Registry max-size-value set in Aries Cloud Agent Python.
Recent performance improvements in Tails File handling both in I/O and cryptographic processing may have resulted in decreases in proof generation times.
From the docker directory in this repo, run ./manage start.
The docker environment requires Ngrok to run locally. After registering an Ngrok token you can create a .env file in the docker directory and supply your token with
NGROK_AUTHTOKEN=<your token here>
Install the python package tails-server from this directory. This may be available on PyPI some day.
pip3 install -e .Run the software:
tails-server --host 0.0.0.0 --port 6543 --storage-path $STORAGE_PATHWhere $STORAGE_PATH is where you would like the tails files stored.
This server has two functions:
- Uploading a tails file
- Downloading a tails file
For each of those operations, there are two endpoints, one based on the Revocation Registry ID, and the other based on the hash of the tails file to be load/retrieved.
To upload a tails file using the Revocation Registry ID, make a PUT request to
/{revoc_reg_id} as a multipart file upload with 2 fields. The first field
must be named genesis and the second field must be named tails.
genesis should be the genesis transactions file and tails should be the
tails file. The server supports chunked encoding for streaming very large tails
files. The server will lookup the relevant revocation registry definition and
check the integrity of the file against fileHash on the ledger. If it's good,
it will store the file. Otherwise it will respond with response code 400. If
revoc_reg_id does not exist on the ledger, the server will respond with
response code 404. If the file already exists on the server, it will respond
with response code 409.
To upload a tails file using the hash endpoint, use the PUT /hash/{tails-hash}
endpoint to upload the file, validate the hash against the uploaded file, and
ensure the tails file "looks" like a tails file by carrying out several checks
of the contents.
For downloading a file using the Revocation Registry ID, execute a GET request
with the path /{revoc_reg_id} where revoc_reg_id is a valid id. If it
doesn't exist, the server will respond with response code 404.
For downloading a file using the tails file hash, execute a GET /hash/{tails-hash}. If a file with that hash doesn't exist, the server will
respond with response code 404.
This software is designed to support scaling to as many machines or processes as necessary. As long as the filesystem (perhaps a network mount) being written to support POSIX file locks, you should be good.
There is a suite of integration tests that test some assumptions about the environment like the type of mounted file system and the ledger that is being connected to. For running these tests a local von-network needs to be running, you can spin one up by
git clone https://github.com/bcgov/von-network
cd von-network
./manage build
./manage start
After the von-network is up, goto the tails-server docker directory, run the manage script as follows.
cd indy-tails-server/docker
./manage test
This will perform a series of tests creating revocation registries with a local tails-server. Some notes:
- The tests can only be run once per run of VON Network (error
UnauthorizedClientRequest). To rerun, bring down von-network (./manage down; ./manage startin the von-network repository clone) and rerun the tests. - Wait a bit after starting von-network (15-20 seconds) before running the indy-tails-server tests, as you will get an error (
Server disconnected...) if you start too quickly. If you get that error, try again and it should work.
If you want to run a local copy for testing with other deployments, here are some things you can try:
- After starting your docker Tails File instance, run the ACA-Py Alice-Faber Demo with Revocation.
- After starting your docker Tails File instance, run the Aries Agent Test
Harness (AATH). For
example, after cloning the AATH repo, run the command
./manage runset acapy -bto build and run the standard set of tests with ACA-Py. AATH detects that a tails file is already running locally, and so will use that instance.
Due to how revocation works in Hyperledger Indy, there is the expectation/requirement that the tails server public URL will be stable over time. Failing to satisfy this requirement will cause failures when issuing and/or verifying credentials for which the credential definition was created/registered on an "old" tails server url.