Skip to main content
Everything the tool stores lives in one keystore directory on your machine. Private keys stay there, and the bank API key is never written to disk.

The keystore

The keystore is one directory, ./.trusset-kyc by default. --home or TRUSSET_KYC_HOME moves it.
The keystore directory has mode 0700 and every file in it has mode 0600. The tool refuses to use a keystore that other users can read, and tells you the chmod that fixes it. File modes are not enforced on Windows.

How private keys are protected

Set TRUSSET_KYC_PASSPHRASE before keygen and source-keygen. The private key is then stored encrypted with a key derived by scrypt (N=32768, r=8, p=1) and AES-256-GCM, and the passphrase is required every time the key is used. The passphrase is never stored.
Without TRUSSET_KYC_PASSPHRASE the private key is stored unencrypted, protected by the file mode only. The tool prints a warning when it does this.
Two secrets are never written by the tool:
  • The bank’s API key. It is read from TRUSSET_API_KEY only and is never printed.
  • The passphrase.
The verifier’s inbox token exists only inside the stored invite file and is never printed. invite list leaves it out.

A filed record

trusset-kyc open writes each record to <out>/<walletAddress>/<envelopeId>/, with the wallet address in lowercase: The directory is created with mode 0700 and its files with mode 0600. The files are written first and moved into place together, so a directory that exists is complete. These files are enough to verify the record again without Trusset: see Verify a filed record offline.
This directory holds the KYC files in clear. It is the only copy on your side, and Trusset deleted the ciphertext when the record was opened. Protect it and back it up as you would any other store of personal data. How long you keep it is your decision under your own retention rules.

Envelope files

trusset-kyc seal writes <envelopeId>.envelope.json with mode 0600. It holds the delivery body and nothing secret: the header in clear, which names the wallet, and the ciphertext. Delete it once the delivery is confirmed.

What to back up

Never commit the keystore, the output directory or envelope files to version control. The tool’s own .gitignore excludes .trusset-kyc/, records/ and *.envelope.json.

When a key is lost or exposed

The bank’s record key is lost. Records already opened are unaffected, because they are filed in clear. Records still waiting cannot be opened. Create a new key with keygen, register it with Set Record Key, issue a new invite for every source, and ask the sources to seal and send the waiting records again. The bank’s record key is exposed. Open the records that are waiting first, so that Trusset deletes their ciphertext, then replace the key the same way. A record sealed to the exposed key can be read by anyone who holds that key and obtains its envelope. The verifier’s signing key is lost or exposed. Create a new signing key and send the public key to every bank you deliver to. Each bank confirms the new fingerprint with you, registers the key with Update KYC Source and replaces its local pin with source add --replace --former-key revoke. Until then the bank’s tool keeps accepting records signed with the old key. Once revoked, the old key opens no record, records filed under it no longer verify, and it can never be pinned again in that keystore, not even after source remove. The invite is exposed. Ask the bank for a new one. Reissue Source Invite ends the old token at once. With the token alone someone can read your inbox description, and the status of a delivery whose envelope ID they know. They cannot deliver or revoke a record, because both must be signed with your signing key.