Sending a file

This page shows you how to get a file — a passport scan, a signed form — from your machine to a colleague's, through your vault. You store the file in a record's file field, which seals it on your machine. You send your colleague one line. They run that line on their machine, which opens the file and writes it to disk.

Before you start

• You and your colleague are each signed in to the vault on your own machines, each as your own principal. See signing in and principals.
• Both machines are enrolled devices in the same vault. The file is sealed on the sending machine and opened on the receiving one, and each needs a device to unwrap the vault's master key. See enrolling and managing devices.
• The schema has a type: file field. Give it a filename_field too, so your colleague gets the file under its real name rather than under its token. See file fields.
• The record exists. Create it with custodian records create, and keep its identifier.
• The sender can write the field, and the recipient can read it. The sender's principal needs a --write grant on the collection, and a --plaintext grant on the file field and its filename field: storing a file reads the record first, and a write grant does not permit reading. The recipient's principal needs the same --plaintext grant on the file field, and on its filename field if you set one. See custodian grant.

1. Store the file's name

custodian file put stores the file's bytes, not its name. The name goes in the filename field, an ordinary field of the record that you set yourself. Read the value from standard input, so that it does not appear on the command line:

printf 'passport.pdf' | custodian records update 018f4e2a-7c1b-7a3e-b9d4-2f6c8a1e5b70 --collection policyholders --set passport_scan_name=@-

You can also set it when you create the record, with the same --set. If you skip this step, your colleague gets the file under its token, with a note saying the record holds no name for it.

2. Store the file

On your machine, store the file in the record's file field:

custodian file put 018f4e2a-7c1b-7a3e-b9d4-2f6c8a1e5b70 --collection policyholders --field passport_scan --input passport.pdf

Stored in field "passport_scan" on record 018f4e2a-7c1b-7a3e-b9d4-2f6c8a1e5b70.
  tok_AOWVT36VNVCIESCL

Retrieve it on an enrolled device with:
  custodian file get tok_AOWVT36VNVCIESCL

If the file is the output of a program — a form a program fills in, for example — you can store that output directly, without it reaching your terminal, with custodian exec --capture-output. It prints the token on standard error; the retrieval line is custodian file get followed by that token.

3. Send the retrieval line

Copy the last line, custodian file get tok_AOWVT36VNVCIESCL, and send it to your colleague — in an email, a message, or a ticket.

The line holds the file's token, not the file. A token is the identifier Custodian gives the stored file, tok_ followed by sixteen characters. It is not a sign-in token, and on its own it does not open the file. Running the line needs a signed-in credential with a grant to read the field and an enrolled device in the vault. For anyone without that grant, the command refuses as it would for a token that does not exist:

error: Token tok_AOWVT36VNVCIESCL resolves to no file you can read: it does not exist, it belongs to another vault, or you hold no read_plaintext grant on its field. Nothing was written.

4. Retrieve the file

Your colleague runs the line on their enrolled machine. If they are signed in to more than one vault, the line does not say which one the file is in, and the command refuses rather than guess. They add --vault <slug> (and --url <api> if they use more than one deployment) — or you can add it to the line before you send it. See selecting a deployment and vault.

custodian file get tok_AOWVT36VNVCIESCL

Wrote passport.pdf (412 KB) to /home/alex/Custodian/acme/passport.pdf

The file lands in ~/Custodian/<vault>/ with permissions 0600, so only their user account can open it. To put it somewhere else, they add --output <path>. Where the file goes, what permissions it gets, and what happens when a file of that name already exists are all described under custodian file get.

If something goes wrong

The retrieval line has stopped working. Two things make a retrieval line stop working:

• You replaced the file. Storing a new file in the same field — with custodian file put or a capture — gives it a new token.

• The vault's master key was rotated. custodian key rotate recomputes every file's token. Its warning says so before it starts:

  ! Every file in this vault is among those tokens: any retrieval line already sent for a
    file — printed or emailed — stops working and must be re-issued once this completes.

Either way, the old line can never work again, so send a new one built from the file's new token:

• After a replacement, the command that stored the new file printed the new retrieval line.

• After a rotation, read the record. The file field's line shows its new token:

  custodian records get 018f4e2a-7c1b-7a3e-b9d4-2f6c8a1e5b70 --collection policyholders

  passport_scan       tok_K3QZ7W2M5VJXRT4N  tokenised
  passport_scan_name  tok_P6HCY2DQ5LMNWB3F  tokenised

  Send custodian file get tok_K3QZ7W2M5VJXRT4N. You do not need the original file.

The presence prompt was declined. On a Mac, opening the file asks for Touch ID or a passcode. If your colleague declines it, nothing is written:

error: Cannot open the file: the presence prompt was declined, so this device did not unwrap the master key. Re-run and approve the prompt (Touch ID, a passcode, or your device PIN) to open it.

They run the same line again and approve the prompt.

The file was written under its token, not its name. The schema has no filename_field for the file field, the record holds no name (see step 1), or your colleague has no grant on the filename field. The note under the result says which. See how the file is named.