Policy application management with signed deployment packages

Signed deployment packages ensure a PingAuthorize Server uses only deployment packages from a certain PingAuthorize Policy Editor, allowing you to avoid the use of packages intended for a different context or to use packages from only a designated source.

Use case: Distinct PingAuthorize deployments

Consider an organization with two distinct PingAuthorize deployments: healthcare and banking. Each deployment has a unique set of policies. Using the healthcare policies for the banking deployment, or vice versa, would make the deployment ineffective. Signed deployment packages avoid this issue. To set up signed deployment packages for these two deployments:

Set up the healthcare configuration.
1. Create a signing key pair with a private key and a public key for healthcare.
2. Set up a Policy Editor to create all healthcare policies. Configure that GUI to sign its deployment packages with the healthcare private key.
3. Configure the healthcare PingAuthorize Server to use the healthcare public key to verify deployment packages. Now the healthcare deployment only accepts healthcare policies and does not accept banking policies.
Set up the banking configuration.
1. Create a signing key pair with a private key and a public key for banking.
2. Set up a Policy Editor to create all banking policies. Configure that GUI to sign its deployment packages with the banking private key.
3. Configure the banking PingAuthorize Server to use the banking public key to verify deployment packages. Now the banking deployment only accepts banking policies and does not accept healthcare policies.

Use case: Designated source for deployment packages

An organization has several people who write policies. Each policy writer has their own Policy Editor to develop and test policies. However, to ensure the organization fully verifies each deployment package before it goes into preproduction or production, only one Policy Editor can actually sign deployment packages with the key accepted by the PingAuthorize Server.

Example: Configure signed deployment packages for healthcare

In this example, you configure a PingAuthorize Policy Editor to sign its deployment packages for a PingAuthorize Server dedicated to healthcare policies.

About this task

This example uses the manage-certificates tool that comes with PingAuthorize. The tool provides many of the same features as the Java keytool utility. If you prefer to use keytool, running manage-certificates --display-keytool-command shows a command that you can use to obtain a similar result.

Steps

Generate a signing key pair for the Policy Editor:
1. Create a key pair consisting of a private key and the corresponding public key and put the key pair in a key store so that the Policy Editor can use it.
  
  Example:
  
  The following command performs both of these actions by generating a key store with a self-signed certificate:
  $ manage-certificates generate-self-signed-certificate \ --keystore "healthcare-pap-signing.jks" \ --keystore-type jks \ --keystore-password "<keystore-password>" \ --private-key-password "<private-key-password>" \ --alias "healthcare-pap" \ --subject-dn "cn=Healthcare PAP,dc=example,dc=com" \ --days-valid 90
  - This command creates a key store with the name healthcare-pap-signing.jks, containing the Policy Editor’s private signing key and the corresponding public key.
  - The Policy Editor uses this key store to sign deployment packages.
  - The key store itself and the private key each have passwords.
  - The signing key pair has the alias healthcare-pap.
  - The subject DN is arbitrary.
  - The keys are valid for 90 days.
Export a public certificate from the Policy Editor’s key store.

Example:
```
$ manage-certificates export-certificate \
  --keystore "healthcare-pap-signing.jks" \
  --keystore-password "<keystore-password>" \
  --alias "healthcare-pap" \
  --export-certificate-chain \
  --output-format pem \
  --output-file "healthcare-pap.pem"
```
This command creates a public certificate file with the name healthcare-pap.pem. This file becomes an input during the next step, and it is not used directly by either the Policy Editor or PingAuthorize. The public certificate specified by the --alias argument represents the public key created in the previous step.
Create a trust store for PingAuthorize Server for the public certificate from the previous step.

Example:
```
$ manage-certificates import-certificate \
  --keystore "healthcare-pap-verification.jks" \
  --keystore-password "<keystore-password>" \
  --keystore-type jks \
  --alias "healthcare-pap" \
  --certificate-file "healthcare-pap.pem" \
  --no-prompt
```
This command creates a trust store with the name healthcare-pap-verification.jks, containing the Policy Editor’s public certificate. PingAuthorize Server uses this trust store to verify that deployment packages created by the Policy Editor were actually created by that GUI.

Configure the Policy Editor to use the key store to sign the deployment packages it creates:

Make a copy of the default options file.
```
$ cp config/options.yml my-options.yml
```

Edit the new options file for your policy deployment method, uncommenting the appropriate block and substituting your passwords and other values.

Using deploymentPackageData to define the signing key configuration only affects exported deployment packages. Deployment packages published to a store only use their store-specfic configurations defined in the deploymentPackageStores block to apply a signing key.

Use the deploymentPackageData block to configure signing for exported deployment packages.

deploymentPackageData:
  #  contentType: json
  #  keystore:
  #    resource: /path/to/healthcare-pap-signing.jks
  #    password: keystore-password
  #  securityLevel: signed
  #  signingKey:
  #    alias: healthcare-pap
  #    password: private-key-password

Under the deploymentPackageStores block, use the appropriate store type to configure signing for deployment packages published to a deployment package store.

deploymentPackageStores:
  # Define deployment package store publishing targets here.
  #
  # - name: Signed filesystem store
  #   description: Signed file system directory store
  #   type: filesystem
  #   path: /path/to/signed-deployment-package-store/
  #   securityLevel: signed
  #   keystore:
  #     resource: /path/to/healthcare-pap-signing.jks
  #     password: keystore-password
  #   signingKey:
  #     alias: healthcare-pap
  #     password: private-key-password
  #  Other deployment package store types omitted for brevity...

Stop the Policy Editor.
```
$ bin/stop-server
```
Run setup using the --optionsFile my-options.yml argument.

Customize all other options as appropriate for your needs.
Start the Policy Editor.
```
$ bin/start-server
```

Configure the PingAuthorize Server to use the trust store for verification so that it accepts only deployment packages created by this Policy Editor:

Create a trust manager provider and include the path to the trust store file and the trust store’s password.

The trust manager provider is how the PingAuthorize Server configuration refers to a trust store file.

$ dsconfig create-trust-manager-provider \
  --provider-name "Healthcare PAP Verification Store" \
  --type file-based \
  --set enabled:true \
  --set "trust-store-file:/path/to/healthcare-pap-verification.jks" \
  --set trust-store-type:JKS \
  --set "trust-store-pin:<truststore-password>"

Configure the policy decision service.

$ dsconfig set-policy-decision-service-prop \
  --set pdp-mode:embedded \
  --set "deployment-package</path/to/deployment-package.deploymentpackage" \
  --set deployment-package-security-level:signed \
  --set "deployment-package-trust-store:Healthcare PAP Verification Store" \
  --set "deployment-package-verification-key-nickname:healthcare-pap"

Deployment packages are only for the embedded PDP mode, so this command sets the pdp-mode property accordingly. The other properties are described in the following table.

Property Description

Property	Description
`deployment-package-security-level`	Determines whether PingAuthorize Server require a deployment package to be signed. Valid values are: `unsigned` PingAuthorize Server does not check a deployment package for a trusted signature. This value is set by default. `signed` PingAuthorize Server checks a deployment package for a trusted signature and rejects a deployment package that fails that check. Whenever a deployment package fails a check, PingAuthorize Server continues to use the last accepted deployment package.
`deployment-package-trust-store`	Specifies a trust manager provider, which specifies in turn a trust store containing a Policy Editor’s public certificate. This property is required if the value of `deployment-package-security-level` is `signed`.
`deployment-package-verification-key-nickname`	Specifies the alias of the Policy Editor’s public certificate. This property is required if the value of `deployment-package-security-level` is `signed`.

deployment-package-security-level

Determines whether PingAuthorize Server require a deployment package to be signed.

Valid values are:

unsigned: PingAuthorize Server does not check a deployment package for a trusted signature. This value is set by default.
signed: PingAuthorize Server checks a deployment package for a trusted signature and rejects a deployment package that fails that check. Whenever a deployment package fails a check, PingAuthorize Server continues to use the last accepted deployment package.

deployment-package-trust-store

Specifies a trust manager provider, which specifies in turn a trust store containing a Policy Editor’s public certificate.

This property is required if the value of deployment-package-security-level is signed.

deployment-package-verification-key-nickname

Specifies the alias of the Policy Editor’s public certificate.

This property is required if the value of deployment-package-security-level is signed.

For more information about the properties, see the Configuration Reference located in the server’s docs/config-guide directory.