Using the Porticor Linux Agent
The Porticor Agent enables you to encrypt disks on your server, using Porticor's highly secure key management technology. The Agent connects to a key management appliance - a Porticor virtual machine deployed in your cloud account, which is responsible to safeguard your master key so that you do not have to trust anybody else with your keys, not even Porticor. You provision the Agent with a secure API key, which allows it to access its own managed crypto keys, but not the master key. All disk encryption takes place locally on the server that runs the Agent, and the disk-encryption keys are split between the key management appliance and the Porticor Virtual Key Management (PVKM) service.
- Download (login required) the agent from the Downloads
Note: Oracle Linux installation is somewhat different, see the bottom of this page for details.
- Install the package on your application server: On Ubuntu, run
dpkg -i package-name.deb. On Red Hat, CentOS and
Amazon Linux, run yum install package-name.rpm.
You may need to install dependencies, such as cryptsetup and pip on
Ubuntu (using apt-get install cryptsetup python-pip
- Configure the Porticor Virtual Appliance:
- Make sure you have at least one Porticor Virtual Appliance deployed in your cloud account (see this Getting Started article).
- You will need the address of your Porticor Virtual Appliance. Go to the PVKM's main management page, select an appropriate appliance, click "manage" and then note down its DNS address (typically ending with d.porticor.net). If no such appliance exists, you will have to start one.
- You will also need an API key, which you can obtain from the PVKM's API key management page. Notice that you have the option to generate Version 1 or Version 2 keys. For improved security, the agent supports Version 2 keys only.
- On AWS, we strongly recommend to enter your cloud credentials
into the Porticor appliance. Go to the Protected File Systems and
enter the AWS Key ID and Secret Key. Note: these credentials are
always kept within your account, and Porticor never sees them. Copy
your API key file (.pem) to your application server and run:
sudo porticor_agent initialize appliance-addr --api-key-file key-file
- The agent is ready to go.
The agent provides a single command porticor_agent, which in turn provides numerous subcommands. All subcommands must be run with root permissions. For example:
sudo porticor_agent status
All options in brackets [ are optional. All options in double-quotes " must be quoted if they consist of multiple words. Below is the list of subcommands:
- List the agent's commands.
- Display a status summary.
- initialize appliance-addr [--agent-name "name"] --api-key-file key-file [--persist-key] [--no-ip-validation]
- Initialize the agent. The agent will connect to the given appliance using the provided API key. Use the --api-key-file option to provide the location of your API Version 2 key. The agent's configuration is written to /etc/porticor-agent/agent-config.json. The appliance must be available for the initialization to complete successfully. During initialization, the current server's entropy pool (/dev/random) is refreshed. You can use --agent-name to name the agent. Use --persist-key (not recommended) if you want the agent's key to be saved on disk so that it can survive a reboot. On AWS, you may use --no-ip-validation if you prefer not to tie API keys to a particular server instance.
- reconfigure appliance-addr [--agent-name "name"] --api-key-file key-file [--persist-key] [--no-ip-validation]
- Similar to initialize, to be used when the agent has already been initialized. This is useful if you want to switch to a different appliance, or another API key.
- enter-key [--persist-key] [--no-ip-validation] --api-key-file key-file
- Enter an API key file if the secret key has been deleted, e.g. after a reboot.
- deconfigure [--force]
- Remove the agent's configuration without uninstalling it. The --force option skips the confirmation prompt. You may not deconfigure an agent while it still has disks configured on it.
- secure-disk device-name "comment"
- Set up a new disk for encryption. The device name is a block device, e.g. /dev/sdb. Important: make sure the device is empty before using it. You can add a comment between quotes, such as "My project's MySQL data disk".
- import-disk device-name "comment"
- Add an existing, previously encrypted disk to the agent's configuration database. Can be used for recovery of encrypted disks on a new instance. The device name is a block device, e.g. /dev/sdb. You can add a comment between quotes, such as "My project's MySQL data disk".
- resize-disk disk-name
- Adjust the disk size usable for encrypted data. Should be called after the underlying disk had been resized. Note that the disk size can never be reduced.
- rotate-disk-key disk-name
- Replace the disk secret key without re-encrypting the disk.
- Configure the agent to trust the appliance's CA certificate. This is only needed if you enable the Porticor CA (PCA) on the project after an agent has been configured.
- secure-mapped-disk file-name size ["comment"]
- Set up a new disk for encryption. This command uses a file-mapped disk (also known as "loop device") instead of a block device. A new file of the specified size (given in gigabytes) is created and mapped. You can add a comment between quotes, such as "My project's MySQL data disk". After you have set up the disk, you can use the mkfs /dev/mapper/hl-xxxx and mount /dev/mapper/hl-xxxx mount-point commands to respectively format and mount it. The mapper address is displayed by the list-disks command.
- lock-disk disk-name
- Lock a disk and forget its key. The key is removed from the agent and the appliance, but a key-share is retained on the Porticor Key Management service. The disk-name argument is a name of the form hl-1234abcd, as displayed by the list-disks command.
- unlock-disk disk-name
- Retrieve the disk's key from the Key Management service and ready it for use. The disk-name argument is a name of the form hl-1234abcd, as displayed by the list-disks command. You may need to remount the disk using the mount command.
- remove-disk [--force] disk-name
- Permanently remove the encrypted disk, and forget its encryption key. The disk-name argument is a name of the form hl-1234abcd, as displayed by the list-disks command. This operation cannot be undone! The --force argument overrides the confirmation prompt.
- edit-comment disk-name "new comment"
- Replaces the comment associated with the disk. The disk-name argument is a name of the form hl-1234abcd, as displayed by the list-disks command. The comment must be quoted.
- List all the disks managed by the agent.
- Unlock all disks that are marked as active. Useful in provisioning scripts, after enter-key has been used to refresh the key.
- Lock all active disks. Useful in provisioning scripts, during system shutdown.
Install the agent (on Ubuntu or Debian):
# dpkg -i porticor-agent_1.0-2_all.deb
Initial configuration (you will need an API key file):
# porticor_agent initialize
izjuuy0klp4-pztgzntfjmj.d.porticor.net --agent-name "DB Server
Agent" --api-key-file key_v2-cc5d1da5ec43f.pem
Check agent status:
# porticor_agent status
Agent Name: DB Server Agent Version: 2.20 UUID: 2bb0011b-4b79-e6f3-0cea-117d6a395d73 Project Serial: PROJMJNPQJDRJGZD2BLO001= Appliance: izjuuy0klp4-pztgzntfjmj.d.porticor.net API Key ID: 3t1aQrnPrdGvh6iK API Secret Key: Configured # of Protected Disks: 0
Encrypt an entire disk:
# porticor_agent secure-disk /dev/xvdg "An Encrypted Block
Alternatively, create a file of a certain size, and map it as
# porticor_agent secure-mapped-disk encrypted-data 10 "My
List all protected disks:
# porticor_agent list-disks
Name Device Size Status Mapping Comment hl-50168697a70a /dev/loop0 10 GB Active /dev/mapper/hl-50168697a70a My encrypted data
Prepare the disk for use: format and mount it:
# mkdir ./mydisk # mkfs -t ext4 /dev/mapper/hl-50168697a70a # mount /dev/mapper/hl-50168697a70a ./mydisk
The disk is now ready to use. Later, when the disk is no
needed, lock the disk:
# umount ./mydisk # porticor_agent lock-disk hl-50168697a70a
Remove the disk (this deletes the encryption keys and the data cannot be recovered)
# porticor_agent remove-disk hl-50168697a70a
This operation cannot be undone. Are you sure? [N]: y
When the agent is no longer in use, delete its configuration:
# porticor_agent deconfigure Really remove all
Agent configuration? [N]: y
In normal use, no long-term secrets are kept on the agent. Whenever the agent is configured using the API key, this key is replaced by a short-term, policy-constrained key, and only that second key is retained. The short-term key allows API calls to originate only from a single cloud instance, and allows for the instance to change its IP address. By default, the secret part of this key is not kept on disk, and so cannot be recovered by snapshot attacks. This means that your provisioning system should refresh the API key using the enter-key command whenever the server reboots. Note that the instance restriction policy is only available if the agent is installed on an AWS server, and requires that any agents should be collocated within the same region as their Porticor appliance.
The agent includes a startup script /etc/init.d/porticor-agent that re-establishes all active disks upon reboot. However this requires that:
- The API key is persisted to disk (with the
- Each disk mount is listed in /etc/fstab,
- There is a dependency in your existing startup scripts to
that /etc/fstab is read only after the Porticor script has been run.
Alternatively, if the API key is not persisted, you can use the enter-key subcommand to re-establish all disks. This can be done manually or from a script.
Oracle Linux AMIs are based on RHEL 5. To install the Agent on these images, a preparatory step is required. To install, fetch the RPM from this link, and the "prepare" script from this link. Then run prepare-porticor-agent.sh --install, followed by yum install --nogpgcheck package-name.rpm. To uninstall, reverse these steps: yum remove porticor-agent and then prepare-porticor-agent.sh --remove. All other steps are as described in the generic installation instructions.
The Agent can be scaled to a large number of disks. But on many
Linux distribution, the number of loop devices is very low (e.g.
10), limiting the maximum number of mapped disks to 10. To
work around this limitation, you can run the following script,
possibly in the
for i in $(seq 0 255); do mknod -m0660 /dev/loop$i b 7 $i chown root.disk /dev/loop$i done