Skip to main content
Run the tool on a machine you control and that is allowed to hold KYC files. The examples assume a POSIX shell.
1

Create the record key

The private key is written to the keystore, ./.trusset-kyc by default, encrypted with the passphrase. Back up the key file and the passphrase now. See Keys and files.
2

Register the public key

Register the public key as the record key of your instance, in the Issuer Portal or with Set Record Key. Only the public key is sent. On a production instance this step is refused until Trusset has enabled sealed KYC records for your organisation.
3

Add the verifier as a source

The verifier sends you its signing public key, which trusset-kyc source-keygen printed on its side. Add the source in the Issuer Portal or with Add KYC Source: its name, that key, the verification profile it verifies for, and the whitelists its records admit to.You get back an invite string. Hand it to the verifier over a confidential channel, because it holds the verifier’s token.
4

Compare fingerprints, then pin the source

Call the verifier, over a channel that does not run through Trusset. Read them the fingerprint of your record key as trusset-kyc key show prints it on this machine, never from the Issuer Portal: the portal and the invite both come from Trusset. The verifier’s tool stores the invite only when your fingerprint matches the key in it. Have them read you the fingerprint of their signing key. Only when it matches, pin the signing key:
--id is the source ID from the Issuer Portal or the API. From now on the tool accepts a record from this source only when both of its signatures verify against this key. trusset-kyc source list shows the pins.When the verifier later changes its signing key, first run trusset-kyc open --all, so every record still waiting under the former key is opened while that key is pinned. Then compare the new fingerprint with the verifier over a separate channel and run the same command with the new key, --replace and a decision about the former key:
--former-key retire is a planned rotation: the records you filed under the former key still verify. --former-key revoke is for a key that was lost or exposed: the records filed under it no longer verify, because anyone holding it could have signed them. Either way the former key opens no new record, whatever date the envelope claims. A record that arrives later under it is held, not rejected; ask the verifier to seal it again with its current key. A retired key that turns out to be exposed is revoked with trusset-kyc source revoke-key --id <sourceId> --key <former key>. A revoked key can never be pinned again, for any source, and source remove keeps it revoked.
5

See what is waiting

pull lists and decrypts nothing. A customer.kyc_record_received webhook event tells you when to look. --status, --source and --wallet filter the list.
6

Open the records

open <recordId> --out ./records opens one record. For each record the tool works in this order and stops at the first step that fails:
  1. It downloads the envelope and checks that its header matches the record Trusset listed.
  2. It verifies the signature on the envelope against the pinned key.
  3. It decrypts with the record key the header names.
  4. It verifies the signature inside the record against the pinned key.
  5. It checks the record against the header: the record digest, the open commitment, the wallet, source, profile and dates, and the hash of every attachment.
  6. It writes the files to --out.
  7. Only then does it tell Trusset the record is open, which makes Trusset delete the ciphertext.
The files land in <out>/<walletAddress>/<envelopeId>/. Keys and files lists them.
7

Review and approve

Review the filed record under your own procedures. Then approve or reject it in the Issuer Portal, or with Approve KYC Record and Reject KYC Record. Approving returns the transaction that lists the wallet on each whitelist bound to the source. Your wallet signs it. The tool takes no part in this step.

What open reports

Each record ends in one of these outcomes: With --all the tool continues with the remaining records after a failure. The exit code of the run is 2 when any record ended with 2, otherwise 3 when any ended with 3, otherwise 1 when any ended with 1, otherwise 0.
Trusset deletes the ciphertext as soon as the opening is acknowledged. The files under --out are then your copy of the record. Put that directory on storage you back up and protect it like any other store of personal data.

Verify a filed record offline

verify needs no network and no private key, so an auditor can run it on a copy. It checks the signature in record.sig over record.json with the key in source.json, and checks that this key is one you trust: your pin, one of its retired keys for a record sealed before that key was retired, or, on a machine without the pin, the verifier’s fingerprint given with --fingerprint. A revoked key anchors nothing. Without that anchor the record does not verify. It also checks the record digest and the other bindings against header.json, checks every attachment hash, and checks the envelope signature using the digest in receipt.json. It prints one line per check and exits 0 when the record verifies and 2 when it does not.

When a record is revoked or expires

Nothing on your disk changes. The record’s status on Trusset becomes REVOKED or EXPIRED, a webhook event reports it, and when the wallet is still listed the record shows action: REMOVE. Build the removal with Build Record Removal or in the Issuer Portal, and sign it with your wallet.

Replacing the record key

trusset-kyc keygen can be run again. It adds a key and keeps the earlier ones, so envelopes sealed to an older key still open. trusset-kyc key show lists them. After you register the new public key, every source needs a new invite. See Set Record Key.