Initial configuration
If you are interested in using Antimatter's disaster recovery mechanism (or would like to use our split-key mechanism to encrypt files completely aside from the main Antimatter product), please contact us, and we can ship you the requisite key cards and reader.
This tutorial will give instructions on how to configure and use Antimatter key cards in offline mode where the tools do not contact Antimatter servers. The upside of this flow is that it will always work, regardless of the state of Antimatter's infrastructure, but the downside is that you need to have all the quorum members in one place so that they can take turns inserting their key cards into the same computer to run commands.
In the next few weeks we will be launching support for online mode that allows for different computers to work together to run these commands, but offline mode will always be supported.
When you first receive your key cards, they will need "personalization". This is the initial configuration step where you configure who the key card belongs to. You need to specify both an email, and a comment. We recommend using the comment to distinguish between cards used for testing and for production.
All interaction with Antimatter Keychain cards is done using the CLI. To begin, simply insert a keychain card into the reader and run the below command.
am dr personalize --email michael@antimatter.io --comment "Michael Development Card"
If you encounter an error, ensure that the card is inserted properly into the reader, and that you inserted it swiftly (if you insert it very slowly, sometimes it can cause problems. An alternative is to plug the card into the reader first, then plug the reader into your computer).
Once a card has been personalized, you can verify that personalization with the info command. This is also useful for working out what card you have plugged into your machine:
am dr info
┌─► Keychain #0012001096
│ State: Personalized
│ Keychain fingerprint: 859a563b55cc592017c519a383e4f318
│ Personalization info v1:
│ Email: michael@antimatter.io
│ Comment: Michael Development Card
│ Issuance certificate: VALID
│ Personalization certificate: VALID
└
If you ever need to re-use a card for a different person, or a different purpose, you can re-personalize the card with a new email and comment. It will increment the personalization version number:
am dr personalize --email michael@antimatter.io --comment "Michael Production Card"
am dr info
┌─► Keychain #0012001096
│ State: Personalized
│ Keychain fingerprint: 859a563b55cc592017c519a383e4f318
│ Personalization info v2:
│ Email: michael@antimatter.io
│ Comment: Michael Production Card
│ Issuance certificate: VALID
│ Personalization certificate: VALID
└
I'm going to do this for two other cards, which I will call Alice and Bob:
# with card 2 inserted:
am dr personalize --email alice@example.com --comment "Alice"
# with card 3 inserted:
am dr personalize --email bob@example.com --comment "Bob"
Now, we need to create a delegation. A delegation is a key, split among a group of people. The maximum number of people in a delegation is 16, and you can pick any quorum number from 1 (any one person can use the key, which is not recommended) to 16 (everyone in the delegation must approve in order to use the key). Typical choices are 2 out of 3 or 3 out of 5.
A key card can support up to 20 distinct delegations on it, and you can delete delegations to make room for new ones. Delegations used for production can also be locked to make it harder to accidentally delete.
When you run create-delegation it will ask you for a name for name, comment, size and quorum. After that you can pick your additional members. If you have just personalized your other members on the same computer, they will show up, otherwise you need to have first inserted each key card into the machine and rum am dr info to load the personalization certificate from the key card onto the machine to populate this menu.
am dr create-delegation
> Delegation name: Production
> Delegation comment: Customer X
> Delegation size (between 2 and 16): 3
> Delegation quorum (between 2 and delegation size): 2
? Select the members for your delegation:
> [ ] bob@example.com
[ ] alice@example.com
[↑↓ to move, space to select one, → to all, ← to none, type to filter]
After creating a delegation, you can see the state of the new delegation with the dinfo command:
am dr dinfo
┌─► Delegation name: "Production"
│ Comment: "Customer X"
│ Delegation fingerprint: da1f46a2483f7e87c5a5fa5aeb868453
│ State: AWAITING_MEMBER_CONFIRMATION
│ Number of delegates: 3
│ Approval quorum size: 2
│ DR public key: BOFs9DFfYM8F/gVWiJnKJf372RgAdJ3pio+qsdYSySqSyhmY8lhJ+aRreoZbhb4QHApoXWvShiDpk9RAyVXg7y0=
│ DR Event state: NONE
│ DR Usage counter: N/A
│ Members:
├00┬─► Keychain "#0012001096"
│ │ Fingerprint: 859a563b55cc592017c519a383e4f318 (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: michael@antimatter.io
│ │ Comment: Michael Production Card
│ └
├01┬─► Keychain "#0012001097"
│ │ Fingerprint: 2fcbbd4fc58b48ff2f78eaffd5578a4c (checked)
│ │ State: INFO-KNOWN + UNCONFIRMED
│ │ Custodian info v2:
│ │ Email: bob@example.com
│ │ Comment: Bob
│ └
├02┬─► Keychain "#0012001098"
│ │ Fingerprint: 011261c5fd12ca73ab8f77d14b70f4fa (checked)
│ │ State: INFO-KNOWN + UNCONFIRMED
│ │ Custodian info v2:
│ │ Email: alice@example.com
│ │ Comment: Alice
│ └
└
A newly created delegation is in the state AWAITING_MEMBER_CONFIRMATION as the creating key card does not yet know that other cards invited to the delegation have successfully saved their key shards. To process those invitations, insert each other card in turn and run the auto command:
# With card 2 inserted
am dr auto
There is a pending delegation invitation for this card (#1002001098)
┌─► Delegation invite for #1002001098
│ Encrypted payload size: 260
│ CMAC: c955c8d5c4916e5c42b00be848275d7c
└
> Accept the Invitation? Yes
ⓘ invitation accepted
# With card 3 inserted
am dr auto
There is a pending delegation invitation for this card (#1002001097)
┌─► Delegation invite for #1002001097
│ Encrypted payload size: 260
│ CMAC: 17938a18414889d75d49d32511d6dcf9
└
> Accept the Invitation? Yes
ⓘ invitation accepted
Then you can insert the coordinator card and run auto:
am dr auto
Processing membership affirmations for "Production"
approvals found: 2
ⓘ 2 new approvals found for delegation "Production"
At this point, the delegation is marked as "VALID + UNPROTECTED" meaning that it can be used for disaster recovery, but it can also be deleted if required.
am dr dinfo
┌─► Delegation name: "Production"
│ Comment: "Customer X"
│ Delegation fingerprint: da1f46a2483f7e87c5a5fa5aeb868453
│ State: VALID + UNPROTECTED
│ Number of delegates: 3
│ Approval quorum size: 2
│ DR public key: BOFs9DFfYM8F/gVWiJnKJf372RgAdJ3pio+qsdYSySqSyhmY8lhJ+aRreoZbhb4QHApoXWvShiDpk9RAyVXg7y0=
│ DR Event state: NONE
│ DR Usage counter: N/A
│ Members:
├00┬─► Keychain "#0012001096"
│ │ Fingerprint: 859a563b55cc592017c519a383e4f318 (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: michael@antimatter.io
│ │ Comment: Michael Production Card
│ └
├01┬─► Keychain "#0012001097"
│ │ Fingerprint: 2fcbbd4fc58b48ff2f78eaffd5578a4c (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: bob@example.com
│ │ Comment: Bob
│ └
├02┬─► Keychain "#0012001098"
│ │ Fingerprint: 011261c5fd12ca73ab8f77d14b70f4fa (checked)
│ │ State: CONFIRMED
│ │ Custodian info v2:
│ │ Email: alice@example.com
│ │ Comment: Alice
│ └
└
At this point in time, we can configure the disaster recovery key in an Antimatter domain with the settings enable command:
am dr settings enable
> Would you like to add/replace the disaster recovery key with a delegation's DR public key? Yes
> Select a delegation: Production: da1f46a2483f7e87c5a5fa5aeb868453
┌─► Disaster Recovery Settings
│ Domain: dm-KJ1pANudFzr
│ Status: enabled
│ DR Public Key: BOFs9DFfYM8F/gVWiJnKJf372RgAdJ3pio+qsdYSySqSyhmY8lhJ+aRreoZbhb4QHApoXWvShiDpk9RAyVXg7y0=
│ Keycard: Identiv SCR3500 C Contact Reader
│ Attached card contains matching delegation
│ Name: Production
│ Fingerprint: da1f46a2483f7e87c5a5fa5aeb868453
└
You can confirm that DR is properly configured in your domain with the settings query command:
am dr settings query
┌─► Disaster Recovery Settings
│ Domain: dm-KJ1pANudFzr
│ Status: enabled
│ DR Public Key: BOFs9DFfYM8F/gVWiJnKJf372RgAdJ3pio+qsdYSySqSyhmY8lhJ+aRreoZbhb4QHApoXWvShiDpk9RAyVXg7y0=
│ Keycard: Identiv SCR3500 C Contact Reader
│ Attached card contains matching delegation
│ Name: Production
│ Fingerprint: da1f46a2483f7e87c5a5fa5aeb868453
└
You can use also use the delegation DR public key directly to encrypt a file. This file will not be decryptable by any means other than a DR event:
echo "super secret file" > testfile
am dr encrypt --in testfile --out testfile.enc
> Select a delegation: Production: da1f46a2483f7e87c5a5fa5aeb868453
This is not creating an Antimatter capsule, so it is not tied into the Antimatter infrastructure. This can be useful if you just want to use Antimatter's key sharding for things like root certificates.
Extra precautions for use in production
When you have configured a delegation for use in production, you may want to lock the delegation so that it is harder to accidentally delete from the card. This can be done with:
$ am dr lock
When viewing the delegation you can see that it is now listed as write protected:
$ am dr dinfo
┌─► Delegation name: "Production"
│ Delegation fingerprint: d588e62cb2059e15e9021d212a320553
│ Comment: "Customer X"
│ State: VALID + WRITE-PROTECTED
│ Number of delegates: 3
│ Approval quorum size: 2
│ DR public key: BM5PQApkALcWbWlEwhONzQJ70Wq4GYyMQ/LzMqqKdRYudBNgmgFQL5CYU8e3h9CGFyh+g/WXVoTwE9oAUgKIhXI=
│ DR Event state: NONE
│ DR Usage counter: N/A
│ 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 v3:
│ │ Email: alice@company.com
│ │ Comment: Alice
│ └
├02┬─► Keychain "#1002001098"
│ │ Fingerprint: 80141dd0b07d50b36c7fbd9683020244 (checked)
│ │ State: INFO-KNOWN + UNCONFIRMED
│ │ Custodian info v3:
│ │ Email: bob@company.com
│ │ Comment: Bob Production Card
│ └
└
An attempt to delete that delegation will result in an error:
$ am dr delete-delegation --fingerprint d588e62cb2059e15e9021d212a320553
fail status: 0x6e12 (ERR_RESOURCE_LOCKED)