Recovery
To recover a capsule or a file encrypted with am dr encrypt, you first need to propose a Disaster Recovery Event and get a quorum of members to approve that event. There are two main types of event. A "Usage" event allows for the key to be used on the key card for a fixed number of decryptions, but never allows the key to leave the card. An "Export" event is used for large-scale recovery where you need to export the key off the key card so that you can decrypt large numbers of files without needing the keycard. There is also a Migrate event for moving a key to a new delegation, but we will cover that in future documentation.
We recommend using Usage events wherever possible, as they maintain the security of the DR private key. You will be prompted for the delegation and number of uses to permit. You can also enter a comment that will be displayed to the other quorum members when asking for their approval:
am dr propose
> Please select an event type: usage
> Number of uses: 3
> Select a delegation: Production: d588e62cb2059e15e9021d212a320553
> Please enter a comment (less than 40 characters): Propose for testing
ⓘ 2 proposal requests saved
After this, you insert in the remaining cards until you reach a quorum (e.g. one additional card in my example) and run the auto command:
am dr auto
There is a pending DR event request for this card (#1002001097)
┌─► DR Event Request for #1002001097
│ Delegation name: Production
│ Delegation fingerprint: d588e62cb2059e15e9021d212a320553
│ Proposing keychain: 1002001096
│ Proposing fingerprint: c2159e9761af9299742530e20401fafe
│ Signature: VALID
│ Event type: Usage (3 uses)
│ Event ID: 1
│ Comment: Propose for testing
└
? Approve the Request? (Y/n) y
ⓘ approval record saved
After collecting enough approvals, re-insert the initial card that proposed the event and run auto:
am dr auto
ⓘ event opened for delegation "Production"
At this point, you have an open event. We created an event permitting on-card usage of the DR key to decrypt 3 files, but your event can also be an Export event permitting the key to be saved from the card, or a Migrate event permitting the key to be moved to a new delegation.
You can see information about the open event with the dinfo command:
am dr dinfo
┌─► Delegation name: "Production"
│ Comment: "Customer X"
│ State: VALID + UNPROTECTED
│ Number of delegates: 3
│ Approval quorum size: 2
│ DR public key: BM5PQApkALcWbWlEwhONzQJ70Wq4GYyMQ/LzMqqKdRYudBNgmgFQL5CYU8e3h9CGFyh+g/WXVoTwE9oAUgKIhXI=
│ Coordination key fingerprint: d588e62cb2059e15e9021d212a320553
│ DR Event state: OPEN (ON-CARD USAGE)
│ DR Usage counter: 3
│ Members:
├00┬─► Keychain "#1002001096"
│ │ Fingerprint: c2159e9761af9299742530e20401fafe (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: michael@antimatter.io
│ │ Comment: Michael Production Card
│ └
├01┬─► Keychain "#1002001097"
│ │ Fingerprint: 08cb335c0bdab4d9bae9254d29420c3c (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: alice@example.com
│ │ Comment: Alice
│ └
├02┬─► Keychain "#1002001098"
│ │ Fingerprint: 80141dd0b07d50b36c7fbd9683020244 (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: bob@example.com
│ │ Comment: Bob
│ └
└
Let's walk through what it would look like to decrypt an antimatter capsule using the DR key. First we make a capsule
using the encapsulate command:
echo "sensitive capsule file" | am encapsulate --write-context default > mycapsule
This can normally be read with:
am open --read-context default --in mycapsule
sensitive capsule file
The AWS key used for this Antimatter domain will now being disabled. After 10 minutes, when attempting to open the capsule, the following error will occur:
am open --read-context default --in mycapsule
error: Error: opening capsule: APIError: open request failed (403 Forbidden): {"traceID":"ccf43de8-e631-4ad9-aaeb-198025c8c9ba","message":"arn:aws:kms:us-east-1:810429701647:key/8521461c-57a3-40e4-9460-5e441d99b55f is disabled."}
Even though the REK is no longer available, it's still possible to use the open DR event to decrypt this file:
am dr recover --in mycapsule
> Select a delegation: Production: d588e62cb2059e15e9021d212a320553
sensitive capsule file
To decrypt a file encrypted with am dr encrypt:
echo "super secret file" > testfile
am dr encrypt --in testfile --out testfile.enc
> Select a delegation: Production: d588e62cb2059e15e9021d212a320553
am dr recover --in testfile.enc
> Select a delegation: Production: d588e62cb2059e15e9021d212a320553
super secret file
You can see that the number of uses in our event has decreased. It will automatically close when it reaches zero:
am dr dinfo
┌─► Delegation name: "Production"
│ Comment: "Customer X"
│ State: VALID + UNPROTECTED
│ Number of delegates: 3
│ Approval quorum size: 2
│ DR public key: BM5PQApkALcWbWlEwhONzQJ70Wq4GYyMQ/LzMqqKdRYudBNgmgFQL5CYU8e3h9CGFyh+g/WXVoTwE9oAUgKIhXI=
│ Coordination key fingerprint: d588e62cb2059e15e9021d212a320553
│ DR Event state: OPEN (ON-CARD USAGE)
│ DR Usage counter: 1
│ Members:
...
You can close an event early with the close command. This removes the reconstructed disaster recovery private key from the key card, and you will need to propose a new event if you need to do more decryption:
am dr close
> Select a delegation: Production: d588e62cb2059e15e9021d212a320553