Reference: TLS Protect Datacenter configuration¶

For more information about its use, see Push a Firefly configuration to TLS Protect Datacenter.

The Firefly security configuration enables security teams to define policies that align with corporate security requirements. These policies govern the SubCA certificate used to sign certificates requested by clients, the policies applied to the requested leaf certificates, as well as the authentication and authorization configuration for the client.

The Firefly security configuration is structured in YAML format. A typical workflow begins with a sample configuration generated by the Venafi CLI, which serves as a template. Security teams can then modify this template to align with corporate security requirements. The configuration can be validated for syntax errors and common misconfigurations before being imported into the TLS Protect Datacenter. Once imported, Firefly instances can retrieve the configuration during startup to become operational.

Learn more about YAML

A YAML format primarily uses three node types:

Mappings (aka Maps or Dictionaries) The content of a mapping node is an unordered set of key/value node pairs, with the restriction that each of the keys is unique. YAML places no further restrictions on the nodes.
Sequences (aka Arrays or Lists) The content of a sequence node is an ordered series of zero or more nodes. In particular, a sequence may contain the same node more than once. It could even contain itself.
Literals (Strings, numbers, boolean, etc.) The content of a scalar node is an opaque datum that can be presented as a series of zero or more Unicode characters.

Sample configuration file:

firefly.yaml

subCaProvider:
  validityPeriod: P60D
  commonName: subca.example.com
  keyAlgorithm: RSA_4096
  tppPolicyFolderDN: "firefly\\SubCA"
clientAuthentication:
  urls:
  - https://example.com/.well-known/jwks.json
  type: JWT_JWKS
clientAuthorization:
  customClaimsAliases:
    configuration: venafi-firefly.configuration
    allowAllPolicies: venafi-firefly.allowAllPolicies
    allowedPolicies: venafi-firefly.allowedPolicies
policies:
- name: Policy
  validityPeriod: P7D
  subject:
    commonName:
      type: REQUIRED
      allowedValues:
      - example.com
      minOccurrences: 1
      maxOccurrences: 1
    organization:
      type: OPTIONAL
      allowedValues:
      - ^(example|acme)$
      defaultValues:
      - example
      maxOccurrences: 1
  sans:
    dnsNames:
      type: REQUIRED
      allowedValues:
      - "^[A-Za-z0-9][A-Za-z0-9-]*\\.example\\.com$"
      minOccurrences: 1
      maxOccurrences: 10
  keyUsages:
  - digitalSignature
  - keyEncipherment
  - keyAgreement
  extendedKeyUsages:
  - CLIENT_AUTH
  - SERVER_AUTH
  keyAlgorithm:
    allowedValues:
    - RSA_2048
    - RSA_3072
    - RSA_4096
    - EC_P256
    - EC_P384
    - EC_P521
    - EC_ED25519
    defaultValue: EC_P256
minTlsVersion: TLS13

Security configuration nodes¶

Field	Type	Description	Required
`subCaProvider`		Configuration options for the subordinate certificate that Firefly will use to sign leaf certificates. This includes details about the policy folder in the TLS Protect Datacenter for enrollment, subordinate certificate request information, and specifications for the HSM used to generate and store the private key material, if required.	Yes
`clientAuthentication`		Configuration options for authenticating clients requesting certificates over TCP-based protocols. This includes details about the OIDC Discovery URL and the JWKS URI.	No
`clientAuthorization`		Configuration options for authorizing clients requesting certificates over TCP-based protocols. This including details about the names of custom claims validated during client authorization.	No
`policies`		Configuration options for certificate issuance policies enforced by Firefly when clients request certificates.	Yes
`minTlsVersion`	string	The minimum TLS protocol version that Firefly will use when serving clients over HTTP-based protocols. Possible values: `TLS13` and `TLS12`.	No

`subCaProvider` node¶

Field	Type	Description	Valid options	Required Field
`validityPeriod`	string	The validity period for the requested subordinate certificate should be in ISO8601 period format. For example, for a 6-day validity period, you can use P6D, and for a 90-day period, you can use P90D.		Yes
`commonName`	string	The common name (CN) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	Yes
`organization`	string	The organization (O) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	No
`organizationalUnit`	string	The organization unit (OU) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	No
`locality`	string	The locality or city (L) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	No
`stateOrProvince`	string	The state or province (ST) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	No
`country`	string	The country (C) for the requested subordinate certificate will be used by Firefly for signing.	max 64 chars	No
`keyAlgorithm`	string	The key algorithm and size used to generate the private key for the requested subordinate certificate will be used by Firefly for signing.	RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521 and EC_ED25519	Yes
`pkcs11`	PKCS11Configuration	Configuration options for using the PKCS11 interface, which is used to interact with HSM devices for generating and storing the private key material for the subordinate certificate.		No
`tppPolicyFolderDN`	string	The Distinguished Name (DN) of the policy folder in the TLS Protect Datacenter, which will be used when requesting a subordinate certificate. For example, `firefly\\SubCA` or `\\VED\\Policy\\firefly\\SubCA` Note that the `\\VED\\Policy\\` prefix can be omitted.	max 128 chars	Yes

Sample subCaProvidernode:

subCaProvider:
  validityPeriod: P60D
  commonName: My Common Name
  organization: My Organization
  organizationalUnit: My Organizational Unit
  locality: My Locality
  stateOrProvince: My State
  country: US
  keyAlgorithm: EC_P521
  tppPolicyFolderDN: "firefly\\SubCA"

`pkcs11` node¶

Field	Type	Description	Valid options	Required Field
`signingEnabled`	bool	Specify whether the use of an HSM is required for generating and storing the private key material for the subordinate certificate.	true or false	No
`partitionLabel`	String	Partition label on the HSM which will be used for generating and storing the private key material for the subordinate certificate.	max 32 chars	Yes, if signingEnabled is true
`partitionSerialNumber`	String	Partition Serial Number if the HSM has more than one partition with the same label.	String matching ^[A-Fa-fx0-9]{0,18}$	No
`pin`	String	PIN for the partition on the HSM.		Yes, if signingEnabled is true
`allowedClientLibraries`	String Sequence	SHA256 checksums of the client libraries that Firefly is permitted to use when interacting with HSM devices via the PKCS11 interface. If not specified, any client library can be used.	String matching ^[a-fA-F0-9]{64}$	No

Sample pkcs11 node:

pkcs11:
  signingEnabled: true
  partitionLabel: partition1
  partitionSerialNumber: "1234567890234"
  pin: hsm-pin
  allowedClientLibraries:
  - 10a1eac382af5e320d24da6ac76996316df8d3a25b1bc92574cb71b20706efdf

`clientAuthentication` node¶

Firefly will authenticate and authorize its clients when requesting certificates. Authentication methods include JWKS, OIDC, or None. If you wish to prevent clients from requesting certificates via TCP-based protocols, simply omit this section. Note that clients will still be able to request certificates over non-TCP-based protocols, such as when Firefly acts as a cert-manager issuer or through a Unix Domain Socket (UDS).

For JWKS authentication, set the fields below.

Field	Type	Description	Valid options	Required Field	Introduced in version
`urls`	String Sequence	JWKS URIs that will be used by Firefly to retrieve the JWKS containing the public keys used to validate the JWTs used by clients.	At least one URI, with a maximum length of 256 characters	Yes
`type`	String	The authentication type.	Must be JWT_JWKS	Yes

Sample clientAuthentication with JWKS:

clientAuthentication:
  urls:
  - https://idp.example.com/.well-known/jwks.json
  type: JWT_JWKS

For OIDC authentication, set the fields below:

Field	Type	Description	Valid options	Required Field
`baseUrl`	String	The base URL of the OIDC endpoint, for example, `https://idp.example.com`. This base URL is used to retrieve additional information required during client authentication. Note that the suffix `/.well-known/openid-configuration` should be omitted.	Valid URL; max 256 chars	Yes
`audience`	String	The value of the audience field that will be used when validating the JWTs used by clients.	max 256 chars	Yes
`type`	String	The authentication type.	Must be JWT_OIDC	Yes

Sample clientAuthentication with OIDC:

clientAuthentication:
  baseUrl: https://example.com/.well-known/openid-configuration
  audience: firefly
  type: JWT_OIDC

clientAuthorization node¶

Field	Type	Description	Valid options	Required Field	Introduced in version
`customClaimsAliases`	customClaimsAliasesSpec	You may want to configure your IdP to include custom claims in the JWTs issued for clients. In that case, you don't need to specify custom names for the claims. If you can't use the default claim names, you may be able to use claims that are already defined by your IdP. Specify the names of those claims, which Firefly will use for authorizing clients via JWKS or OIDC Discovery.		No

customClaimsAliasesSpec node¶

Field	Type	Description	Valid options	Required Field
`configuration`	String	The name of the claim to be used instead of the default name, `venafi-firefly.configuration`, when validating the JWTs used by clients.	max 128 chars	No
`allowAllPolicies`	String	The name of the claim to be used instead of the default name, `venafi-firefly.allowAllPolicies`, when validating the JWTs used by clients.	max 128 chars	No
`allowedPolicies`	String	The name of the claim to be used instead of the default name, `venafi-firefly.allowedPolicies`, when validating the JWTs used by clients.	max 128 chars	No

Sample clientAuthorization node:

clientAuthorization:
  customClaimsAliases:
    configuration: claim.configuration
    allowAllPolicies: claim.allowAllPolicies
    allowedPolicies: claim.allowedPolicies

`policies` node¶

Field	Type	Description	Valid options	Required Field
`name`		The policy name a client can specify when requesting a certificate. The policy name must also be in the venafi-firefly.allowedPolicies custom claim of JWTs clients present to Firefly when requesting a certificate unless the venafi-firefly.allowAllPolicies claim is true.	max 64 chars	Yes
`validityPeriod`		The maximum validity period for the certificate requested by clients, as well as the default validity period if they do not specify one in their request. It is specified in ISO8601 period format. For example, for a 6-day validity period, use P6D, and for a 90-day period, use P90D.		Yes
`subject`				Yes
`sans`				Yes
`keyUsages`	String Sequence	The Key Usages that will be included in any certificate issued under this policy.	At least one of digitalSignature, contentCommitment, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly or decipherOnly	Yes
`extendedKeyUsages`	String Sequence	The Extended Key Usages that will be included in any certificate issued under this policy.	At least one of ANY, SERVER_AUTH, CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, IPSEC_ENDSYSTEM, IPSEC_TUNNEL, IPSEC_USER, TIME_STAMPING or OCSP_SIGNING	Yes
`keyAlgorithm`	keyAlgorithmSpec	The allowed and default key algorithms that will be used for certificates issued under this policy.		Yes

`subject` node¶

Field	Type	Required Field
`commonName`	attributeSpec
`organization`	attributeSpec
`organizationalUnit`	attributeSpec
`locality`	attributeSpec	Yes
`stateOrProvince`	attributeSpec
`country`	attributeSpec

`sans` node¶

Field	Type	Required Field
`dnsNames`	attributeSpec	Yes
`ipAddresses`	attributeSpec
`rfc822Names`	attributeSpec
`uniformResourceIdentifiers`	attributeSpec

`attributeSpec` node¶

Field	Type	Required Field
`type`	String	One of the IGNORED, FORBIDDEN, OPTIONAL, REQUIRED or LOCKED
`allowedValues`	String Sequence
`defaultValues`	String Sequence	Yes
`minOccurrences`	int
`maxOccurrences`	int

`keyAlgorithm` node¶

Field	Type	Description	Valid options	Required Field	Introduced in version
`allowedValues`	String Sequence	The key algorithm and size that are allowed when clients specify them in their request or when a CSR is submitted.	At least one of RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521, and EC_ED25519	Yes
`defaultValue`	String	The key algorithm and size that will be used when a client does not specify them in their request.	One of RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P384, EC_P521, and EC_ED25519.	Yes

Sample policies node:

policies:
- name: Policy
  validityPeriod: P7D
  subject:
    commonName:
      type: REQUIRED
      allowedValues:
      - example.com
      minOccurrences: 1
      maxOccurrences: 1
    organization:
      type: OPTIONAL
      allowedValues:
      - ^(example|acme)$
      defaultValues:
      - example
      maxOccurrences: 1
  sans:
    dnsNames:
      type: REQUIRED
      allowedValues:
      - "^[A-Za-z0-9][A-Za-z0-9-]*\\.example\\.com$"
      minOccurrences: 1
      maxOccurrences: 10
  keyUsages:
  - digitalSignature
  - keyEncipherment
  - keyAgreement
  extendedKeyUsages:
  - CLIENT_AUTH
  - SERVER_AUTH
  keyAlgorithm:
    allowedValues:
    - RSA_2048
    - RSA_3072
    - RSA_4096
    - EC_P256
    - EC_P384
    - EC_P521
    - EC_ED25519
    defaultValue: EC_P256

minTLSversion node¶

Parameter	Type	Description	Required?	Introduced in version
`minTLSversion`	string	The minimum TLS protocol version that Firefly will use when serving clients over HTTP-based protocols. Possible values: `TLS13` and `TLS12`.	No

Reference: TLS Protect Datacenter configuration¶

Security configuration nodes¶

subCaProvider node¶

pkcs11 node¶

clientAuthentication node¶

clientAuthorization node¶

customClaimsAliasesSpec node¶

policies node¶

subject node¶

sans node¶

attributeSpec node¶

keyAlgorithm node¶