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.
From the docker directory in this repo, run ./manage start.
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
To upload a tails file, 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.
A simple GET request will download a tails file. The path is /{revoc_reg_id} where revoc_reg_id is a valid id. If it 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.
Due to how revocation works in 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.