The former Porticor support site is now frozen. Please refer to our Intuit page.

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.

Installing the Agent

  1. Download (login required) the agent from the Downloads page.
    Note: Oracle Linux installation is somewhat different, see the bottom of this page for details.
  2. 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 python-m2crypto).
  3. 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
  4. The agent is ready to go.

Agent Commands

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

Command Syntax

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:

help
List the agent's commands.
status
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.
set-ca-certificate
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-disks
List all the disks managed by the agent.
start
Unlock all disks that are marked as active. Useful in provisioning scripts, after enter-key has been used to refresh the key.
terminate
Lock all active disks. Useful in provisioning scripts, during system shutdown.

Example Session

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 Device"

Alternatively, create a file of a certain size, and map it as an
encrypted disk:

# porticor_agent secure-mapped-disk encrypted-data 10 "My encrypted data"

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 longer
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

Agent Security

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.

Host Startup

The agent includes a startup script /etc/init.d/porticor-agent that re-establishes all active disks upon reboot. However this requires that:

  1. The API key is persisted to disk (with the --persist-key flag)
  2. Each disk mount is listed in /etc/fstab, and
  3. There is a dependency in your existing startup scripts to ensure
    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.

Installation on Oracle Linux

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.

Scalability

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 /etc/rc.local script:

for i in $(seq 0 255); do
  mknod -m0660 /dev/loop$i b 7 $i
  chown root.disk /dev/loop$i
done