Using the service

This section details configuring and using the Point-to-Point encryption (P2PE) service.

Downloading the service software

Download the P2PE service software and a P2PE Luna Cloud HSM Service Client from your DPoD tenant P2PE service page. The P2PE service software includes a pre-configured Dockerfile and the P2PE CLI. You must download and use the P2PE Luna Cloud HSM Service Client from the P2PE service page.

1. Log in to your DPoD tenant as an Application Owner or Tenant Administrator user.

2. Navigate to the View Services tab (My Services tab for application owners). Click on the Point-to-Point Encryption service name.

3. Click Download P2PE Service Software.

   The browser begins a download of a P2PE Artifact .zip that contains:

   • P2PE CLI
   • P2PE Dockerfile
   • readme.txt
   • VERSION

4. Click New Service Client. The Create Service Client window displays.

5. In the Create Service Client window, enter a Service Client Name (Example: <p2pe_service_client>) and select Create Service Client.

   The browser begins a download of a P2PE service client.

   The P2PE service client is a zip file that contains system information required to connect your application to an HSM. For more information about the Luna Cloud HSM Service Client see Luna Cloud HSM Service Client.

Initializing the service

Initialize the P2PE service by using the P2PE service init command and providing the path to the P2PE Luna Cloud HSM Service Client folder. The password set during service initialization is required for the p2pe tls commands and the P2PE Docker image.

The P2PE service uses a Luna Cloud HSM Service as the HSM backend. Please refer to the Service Client Password Policy for best practices and recommendations on using a secure password.

On Windows operating systems execute the command from an Administrator Command Prompt. Right-click the Command Prompt and select Run as Administrator.

1. Create a workspace directory for the P2PE service.

   mkdir p2pe_service
   cd p2pe_service

   Copy

2. Move the <p2pe_service_software>.zip and the <p2pe_service_client>.zip into the /p2pe_service directory.

3. Extract the contents of the <p2pe_service_software>.zip and the <p2pe_service_client>.zip into the /p2pe_service directory.

   

   Note

   Do not delete the Luna Cloud HSM Service Client .zip after extracting. You need to provide the Luna Cloud HSM Service Client .zip when Building the Docker container.

4. Extract the cvclient-min.zip (Windows) or the cvclient-min.tar(Linux) in the p2pe_service directory. Do not extract to a new cvclient-min directory.

5. Initialize the P2PE service.

   

   Note

   P2PE CLI commands must be executed from the directory where the P2PE application is extracted. The P2PE CLI is available in the P2PE Artifacts package described in Downloading the service software.

   Linux

   ./p2pe service init --client ~/<path_to_p2pe_service> --password Welcome@123

   Copy

   Windows

   p2pe.exe service init --client C:/<path_to_p2pe_service> --password Welcome@123

   Copy
   

   Tip

   The service may take a few minutes to initialize.

Configuring TLS for Docker container

Configure TLS for the P2PE service Docker container and client applications using the tls init command. The tls init command generates a tls.json, tls.pem, and tls_req.pem for securing the TLS connection. The P2PE service only supports PEM and DER certificates. See the p2pe tls commands for more information about generating a DER certificate.

On Windows operating systems execute the command from an Administrator Command Prompt. Right-click the Command Prompt and select Run as Administrator.

Linux

./p2pe tls init --days 365 --keySize 2048 --subject /CN=localhost/C=IN/ --client ~/<path_to_p2pe_service> --password Welcome@123 --dns 0.0.0.0

Windows

p2pe.exe tls init --days 365 --keySize 2048 --subject /CN=localhost/C=IN/ --client C:/<path_to_p2pe_service> --password Welcome@123 --dns 0.0.0.0

You can configure TLS Using a self-signed TLS certificate or Using a CA signed TLS certificate.

You can use p2pe tls selfsigncertificate to generate a new self-signed TLS certificate, or use p2pe tls requestcertificate to generate a new certificate signing request. If you change the configuration you must restart the P2PE service. To use a different SAN refer to the command documentation.

The tls.json file is configured for Self-Signed mode with client-authentication disabled. See Using a CA signed TLS certificate or Using client authentication for more information about alternative TLS configurations. The name of the tls.json file must not be changed.

Note

P2PE service users must monitor for changes to the TLS certificate and TLS trust store.

The tls.json file appears as follows:

{
    "mode": "Self-Signed",
    "trust-store": "/dpod/p2pe/etc/tls/ca",
    "certificate": "/dpod/p2pe/etc/tls/server/tls.pem",
    "client-auth": false
}

The tls.json file defines:

Using a self-signed TLS certificate

1. Execute the tls init command.

   

   Tip

   The p2pe tls init command generates the tls.json, tls.pem, and tls_req.pem files.

2. Mount the tls.json file to /dpod/p2pe/etc/tls/config/tls.json.

3. Mount the tls.pem to the certificate directory defined in the tls.json file.

Using a CA signed TLS certificate

1. Execute the tls init command.

2. Submit the Certificate Signing Request tls_req.pem to a Certificate Authority for signing.

3. Open the tls.json file and modify the "mode:" entry to appear as "mode:" "CA-Signed".

4. Mount the tls.json file to /dpod/p2pe/etc/tls/config/tls.json.

5. Mount the signed certificate to the certificate directory defined in the tls.json file.

Using client authentication

Enabling client authentication requires inclusion of --clientCert and --clientPvtKey commands during all p2pe key commands using the P2PE CLI. See p2pe key for more information about using the --clientCert and --clientPvtKey flags for client authentication.

On Windows operating systems execute the command from an Administrator Command Prompt. Right-click the Command Prompt and select Run as Administrator.

1. Open the tls.json file and modify the "client-auth:" entry to read "client-auth": true.

2. Mount the client's CA certificate to the trust-store directory defined in the tls.json file.

Building the service container

The P2PE service container is available on the Docker Public Registry. Pull the container and build the P2PE service using the P2PE service client, P2PE service Dockerfile, and the docker build command. Do not modify the Dockerfile.

Tip

See Download the service software for more information about acquiring the P2PE Dockerfile and the P2PE service client.

1. Execute docker build.

   docker build --tag <tag_for_p2pe_docker_container> --target configured_p2pe_service --build-arg clientSetup=<p2pe_service_client>.zip <absolute_path_of_dir_containing_dockerfile>

   Copy
   

   Note

   The --target configured_p2pe_service is defined in the Dockerfile, and you must build the container using this target. The --build-arg clientSetup= variable requires the <p2pe_service_client>.zip. The P2PE service client .zip must be available in the directory containing the P2PE Dockerfile. The container may take a few minutes to build.

2. List docker images to verify the container built successfully.

   docker images

   Copy

   Returns

   REPOSITORY                           TAG                 IMAGE ID            CREATED             SIZE
   <tag_for_p2pe_docker_container>      latest              <Image ID>          9 seconds ago       260mb

   Copy

Running the service container

Start the P2PE service Docker container using the docker run command.

Mount the tls.json file to /dpod/p2pe/etc/tls/config/tls.json by including the flag --volume "/tls.json:/dpod/p2pe/etc/tls/config/tls.json. Mount the tls certificate trust store directory when executing docker run by including the flag --volume "/tls:<tls_trust_store>".

If running the Docker Container on Docker Host pass the P2PE service password to the Docker container using the --password flag. If using Kubernetes or Docker Swarm, the password is expected by the service container as an environment variable, set the P2PE_SERVICE_PASSWORD environment variable and exclude the --password flag from the docker run command.

To run the service container

1. Run the service container.

   docker run --security-opt=no-new-privileges --volume "/tls.json:/dpod/p2pe/etc/tls/config/tls.json" --volume "/tls:<tls_trust_store>" --volume "/tls.pem:/dpod/p2pe/etc/tls/server/tls.pem" -it --publish 8080:8080 <tag_for_p2pe_docker_container> --password Welcome@123

   Copy
   

   Note

   You must use the certificate or CSR generated using a p2pe tls command. Failure to use a certificate or CSR generated using the p2pe cli will result in a crypto/rsa: verification error.

   

   Tip

   The --security-opt=no-new-privileges flag is not mandatory, but is a best practice recommended by CIS Guidelines for Docker.

   Returns

   TLS Successfully Configured
   Private Key matches public key from provided certificate. Starting Server....

   Copy

(Optional) Running the service container with logging

By default, the P2PE service logs are set to the info severity level and print to STDOUT.

You can set the log level or set the log file output location by including the --env environment variables when executing docker run as described in Running the service container.

Note

Be aware that some configuration files and parameters can change without being logged because they are passed in to the P2PE service and are not modified through it. These changes can include Identity and Access Management activities such as password changes.

Set the log level

Set the <loglevel> value using --env P2PE_SERVICE_LOG_LEVEL=<loglevel>. Setting the log level will log any events of that severity or higher. The seven log levels are listed here in order of decreasing severity:

1. panic
2. fatal
3. error
4. warn
5. info (default)
6. debug
7. trace

To set the log level

docker run --security-opt=no-new-privileges --volume "/tls.json:/dpod/p2pe/etc/tls/config/tls.json" --volume "/tls:<tls_trust_store>" --volume "/tls.pem:/dpod/p2pe/etc/tls/server/tls.pem" -it --publish 8080:8080 --env P2PE_SERVICE_LOG_LEVEL=<loglevel> --env P2PE_SERVICE_LOG_FILE=<logfile>.txt <tag_for_p2pe_docker_container> --password Welcome@123

Set the log file output location

By defaults, logs are returned at STDOUT. Redirect logs to a log output file using --env P2PE_SERVICE_LOG_FILE=<service_log>.txt. You must mount a volume to the P2PE container at /dpod/p2pe/etc/logs with write permissions. If you do not mount a volume or it does not have write permissions, logs will be redirected to STDOUT.

To set the log file output location

docker run --security-opt=no-new-privileges --volume "/tls.json:/dpod/p2pe/etc/tls/config/tls.json" --volume "/tls:<tls_trust_store>" --volume "/tls.pem:/dpod/p2pe/etc/tls/server/tls.pem" --env P2PE_SERVICE_LOG_FILE=<service_log_file_name>.txt --volume "/tmp/logs:/dpod/p2pe/etc/logs" -it --publish 8080:8080 <tag_for_p2pe_docker_container> --password Welcome@123

Generating and listing keys

Send a request to the service to generate a key using p2pe key generate, and list available keys using p2pe key list.

On Windows operating systems execute the command from an Administrator Command Prompt. Right-click the Command Prompt and select Run as Administrator.

To generate a key and list keys

1. Generate a Base Derivation Key (BDK).

   Linux

   ./p2pe key generate --keyUsage BDK --keyAlgo 3DES --caCert tls.pem

   Copy

   Windows

   p2pe.exe key generate --keyUsage BDK --keyAlgo 3DES --caCert tls.pem

   Copy

2. Generate a Key Encryption Key (KEK).

   Linux

   ./p2pe key generate --keyUsage KEK --keyAlgo AES-128 --caCert tls.pem

   Copy

   Windows

   p2pe.exe key generate --keyUsage KEK --keyAlgo Aes-128 --caCert tls.pem

   Copy

3. List keys.

   Linux

   ./p2pe key list --caCert tls.pem

   Copy

   Windows

   p2pe.exe key list --caCert tls.pem

   Copy

   Returns a list including the BDK and KEK.

   Key id            Algorithm   KeyType   KCV
   <key_id_string>   AES-128     kek       <kcv>
   <key_id_string>   3DES        bdk       <kcv>

   Copy