Luna Security Provider Framework

January 2, 2026 · View on GitHub

The Luna Security Provider Framework causes an application to be automatically configured to work with a bound Luna Security Service.

Detection Criterion	Existence of a single bound Luna Security Provider service. The existence of an Luna Security service defined by the `VCAP_SERVICES` payload containing a service name, label or tag with `luna` as a substring.
Tags	`luna-security-provider=<version>`

Tags are printed to standard output by the buildpack detect script

User-Provided Service

When binding to the Luna Security Provider using a user-provided service, it must have name or tag with luna in it. The credential payload can contain the following entries:

Name	Description
`client`	A hash containing client configuration
`servers`	An array of hashes containing server configuration
`groups`	An array of hashes containing group configuration

Client Configuration

Name	Description
`certificate`	A PEM encoded client certificate
`private-key`	A PEM encoded client private key

Server Configuration

Name	Description
`certificate`	A PEM encoded server certificate
`name`	A host name or address

Group Configuration

Name	Description
`label`	The label for the group
`members`	An array of group member serial numbers

Example Credentials Payload

{
  "client": {
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "private-key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  },
  "servers": [
    {
      "name": "test-host-1",
      "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    },
    {
      "name": "test-host-2",
      "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
    }
  ],
  "groups": [
    {
      "label": "test-group-1",
      "members": [
        "test-serial-number-1",
        "test-serial-number-2"
      ]
    },
    {
      "label": "test-group-2",
      "members": [
        "test-serial-number-3",
        "test-serial-number-4"
      ]
    }
  ]
}

Creating Credential Payload

In order to create the credentials payload, you should collapse the JSON payload to a single line and set it like the following

$ cf create-user-provided-service luna -p '{"client":{"certificate":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----","private-key":"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"},"servers":[{"name":"test-host-1","certificate":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"},{"name":"test-host-2","certificate":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}],"groups":[{"label":"test-group-1","members":["test-serial-number-1","test-serial-number-2"]},{"label":"test-group-2","members":["test-serial-number-3","test-serial-number-4"]}]}'

Configuration

For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to Configuration and Extension.

The framework can be configured by modifying the config/luna_security_provider.yml file in the buildpack. The framework uses the Repository utility support and so it supports the version syntax defined there.

Name	Description
`ha_logging_enabled`	Whether to enable HA logging for the Luna Security Provider. Defaults to `true`.
`logging_enabled`	Whether to enable the logging wrapper for the Luna Security Provider. Defaults to `false`.
`tcp_keep_alive_enabled`	Whether to enable the client TCP keep alive setting for the Luna Security Provider. Defaults to `false`.
`repository_root`	The URL of the Luna Security Provider repository index (details).
`version`	Version of the Luna Security Provider to use.

The Luna Security Provider is automatically configured when a service is bound with both servers and groups keys in the VCAP_SERVICES credentials. The buildpack generates a complete Chrystoki.conf configuration file from the service binding information.

Default Configuration

The buildpack includes a default Chrystoki.conf template that is embedded at compile time. This provides sensible defaults for Cloud Foundry deployments.

The default configuration file is located in src/java/resources/files/luna_security_provider/Chrystoki.conf.

Customizing Default Configuration via Fork

To customize the default Luna Security Provider configuration across all applications using your buildpack:

Fork the java-buildpack repository
Modify the configuration file in src/java/resources/files/luna_security_provider/
Build and package your custom buildpack
Upload the custom buildpack to your Cloud Foundry foundation

This approach is useful for operators who want to enforce organization-wide Luna Security Provider settings.