Note: This example uses the manage-certificates tool that comes with PingDataGovernance. The tool provides many of the same features as the Java keytool utility but can be easier to use. If you prefer to use keytool, use manage-certificates --display-keytool-command to show a command you can use to obtain a similar result with keytool.

  1. Generate a signing key pair for the Policy Administration GUI.

    Create a key pair consisting of a private key and the corresponding public key. Put the key pair in a key store so that the Policy Administration GUI can use it. The following command accomplishes both of these goals 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 filename healthcare-pap-signing.jks. The Policy Administration GUI uses this to sign deployment packages.
    • The key store contains the Policy Administration GUI's private signing key and the corresponding public key.
    • The key store itself has the password <keystore-password>.
    • The private key itself also has a password, <private-key-password>.
    • The signing key pair has the nickname/alias healthcare-pap.
    • The subject DN is arbitrary.
    • The keys are valid for 90 days.
    • This key store is a sensitive asset that you should carefully protect.
  2. Export a public certificate from the Policy Administration GUI's key store.
    $ 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 filename healthcare-pap.pem.
    • The public certificate file is an input during the next step. It is not used directly by either the Policy Administration GUI or PingDataGovernance Server.
    • This public certificate represents the public key created in the previous step. Note that the alias is used to specify the key.
    • This public certificate is not a sensitive asset.
  3. Create a trust store for PingDataGovernance Server for the public certificate from the previous step.
    $ 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 filename healthcare-pap-verification.jks. PingDataGovernance Server uses this to verify that deployment packages created by the Policy Administration GUI were actually created by that GUI.
    • The trust store contains the Policy Administration GUI's public certificate.
    • The trust store itself has the password <truststore-password>.
    • This trust store is not a sensitive asset.

  4. Configure the Policy Administration GUI to use the key store to sign the deployment packages it creates.

    1. Make a copy of the default options file.
      $ cp config/options.yml my-options.yml
    2. Edit the new options file to include a configuration block like the following one, substituting your passwords and other values. Place this new block at the top level, parallel to the core block, either before or after it.
      deploymentPackageData:
  keystore:
    resource: /path/to/healthcare-pap-signing.jks
    password: keystore-password
  securityLevel: signed
  signingKey:
    alias: healthcare-pap
    password: private-key-password
    3. Stop the Policy Administration GUI.
      $ bin/stop-server
    4. Run setup using the --optionsFile my-options.yml argument. Customize all other options as appropriate for your needs.
    5. Start the Policy Administration GUI.
      $ bin/start-server

  5. Configure the PingDataGovernance Server to use the trust store for verification so that it accepts only deployment packages created by this Policy Administration GUI.

    1. Create a trust manager provider, which is how the PingDataGovernance Server configuration refers to a trust store file. Include the path to the trust store file and the trust store's password.
      $ 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>"

    2. Configure the policy decision service.

      $ dsconfig set-policy-decision-service-prop \
  --set pdp-mode:embedded \
  --set "deployment-package</path/to/deployment-package.SDP" \
  --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

      deployment-package-security-level

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

      Valid values are:

      • unsigned (the default)

        PingDataGovernance Server does not check a deployment package for a trusted signature.

      • signed

        PingDataGovernance 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, PingDataGovernance 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 Administration GUI's public certificate.

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

      deployment-package-verification-key-nickname

      Specifies the nickname or alias of the Policy Administration GUI's public certificate.

      This property is required if 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.