This topic provides the prerequisites and instructions for running Enterprise Spring Boot Governance Starter library with your app for the first time.

Prerequisites

• Before adding the Spring Boot Governance Starter to your application, you must have access to it in your project’s build. The recommended approach is to sync the Spring Enterprise Subscription artifact repository to your internal artifact repository. See Spring Enterprise Subscription for Artifact Repository Administrators for details.

• Your Maven or Gradle build environment must have access to an artifact repository where the Spring Boot Governance Starter library is available, at group path com.vmware.tanzu.spring.governance.

Configure the Dependency

The instructions in the following sections describe how to add the Spring Boot Governance Starter dependency to your project’s Gradle or Maven build file.

Gradle

In your build.gradle file, add the governance-starter dependency:

dependencies {
    ...
    implementation "com.vmware.tanzu.spring.governance:governance-starter:1.0.0"
}

Maven

In your pom.xml file, add the governance-starter dependency:

...
<dependency>
    <groupId>com.vmware.tanzu.spring.governance</groupId>
    <artifactId>governance-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Run the Application

If the app does not have the necessary TLS setting in place, the app will fail to start with the following error (or similar):

***************************
APPLICATION FAILED TO START
***************************

Description:

FIPS validation test case(s) encountered 1 failure(s):
- Failed test for TNZSPEC-0001: Application must use TLS
  - Expected TLS to be enabled for connector at port 8080


Action:

Resolve all test failures

By default, the app exits on a FIPS validation error, following FIPS rules. However, you can turn that off by setting a property to allow continuous improvement in test environment:

tanzu.governance:
  fips:
    exit-on-failure: false

By default, all specs will be checked. However, you can skip specific specs by providing them as a comma-separated list to the skip property:

tanzu.governance:
  specs:
    skip: TNZSPEC-0001,TNZSPEC-0020

The governance-starter brings in a couple of FIPS-related Bouncy Castle libraries as transitive dependencies. By default, BouncyCastle is configured in FIPS mode and is set as the primary security provider in the application context. You can override this behavior by setting the enforce property:

tanzu.governance:
  fips:
    config:
      bouncy-castle:
        enforce: false

Enable TLS with a PKCS12 keystore (non-compliant)

1. Generate a certificate with keytool:

   keytool -genkeypair -alias "demo" -keyalg RSA -keysize 4096 -validity 3650 \
   -dname "CN=localhost" -keypass changeit \
   -keystore src/main/resources/keystore.p12 \
   -ext "SAN=dns:localhost,dns:hello-fips,dns:hello-fips.sample" \
   -storeType PKCS12 -storepass changeit
   

2. Add properties to application.yml to configure TLS:

   server:
       port: 8443
       ssl:
           enabled: true
           key-alias: demo
           key-store: classpath:keystore.p12
           key-store-password: changeit
           key-store-type: PKCS12
   

3. In this case, the app would fail to start because this key store type is not available in an approved mode of operation due to the algorithms required for PBE key generation in the PKCS12 standard. See section 7 in the Bouncy Castle documentation.

   Caused by: java.security.NoSuchAlgorithmException: Cannot find any provider supporting PBES2
       at java.base/javax.crypto.Cipher.getInstance(Cipher.java:574) ~[na:na]
       at java.base/sun.security.pkcs12.PKCS12KeyStore.lambda$engineGetKey$0(PKCS12KeyStore.java:363) ~[na:na]
       at java.base/sun.security.pkcs12.PKCS12KeyStore$RetryWithZero.run(PKCS12KeyStore.java:257) ~[na:na]
       at java.base/sun.security.pkcs12.PKCS12KeyStore.engineGetKey(PKCS12KeyStore.java:361) ~[na:na]
       ... 30 common frames omitted
   

Enable TLS with a BCFKS certificate (compliant)

1. Generate a certificate with keytool:

   export JAR_FILE="bc-fips-1.0.2.4.jar"
   export PROVIDER="org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider"
   
   # Download the bouncy castle jar to create the cert with approved encryption method
   curl -s -o "$JAR_FILE" https://downloads.bouncycastle.org/fips-java/bc-fips-1.0.2.4.jar
   
   cd
   keytool -genkeypair -alias demo -keyalg RSA -keysize 4096 -validity 3650 \
   -dname "CN=localhost" -keypass changeit \
   -keystore src/main/resources/keystore.bks \
   -ext "SAN=dns:localhost,dns:hello-fips,dns:hello-fips.samples" \
   -storeType BCFKS -storepass changeit \
   -providerPath "$JAR_FILE" \
   -provider "$PROVIDER" \
   -providerClass "$PROVIDER"
   

2. Add the properties to application.yaml to configure TLS:

   server:
       port: 8443
       ssl:
           enabled: true
           key-alias: demo
           key-store: classpath:keystore.bks
           key-store-password: changeit
           key-password: changeit
           key-store-type: "BCFKS"
   

The app now starts up correctly.

The Governance Actuator Endpoint

The Governance Starter library adds an actuator endpoint containing a summary of the test results, the collected details, and the individual test runs. The tests are re-run on every call to the endpoint.

The endpoint can be accessed at the governance actuator endpoint, which returns the tests and specs for all tags. See this example: https://localhost:8443/actuator/governance.

The Governance Starter library brings in spring-boot-actuator as a transitive dependency, which causes the default actuator endpoints to be made available. For more details about the Spring Boot Actuator, including what endpoints are enabled by default and how to turn them off, see the Spring documentation.

Filter by tag

Specs have tags associated with them to allow for filtering the spec. To filter the results by a specific tag, add it as a query parameter as shown in this example: https://localhost:8443/actuator/governance?tag=FIPS-140-3

The following tags are available in the predefined specifications:

If there is a space in the tag name replace it with a %20 when using it as a query parameter;
for example: https://localhost:8443/actuator/governance?tag=IRS%20p1075r11-2021.

Exposing the Endpoint

Add application properties to expose the Governance Actuator Endpoint:

management:
  endpoints:
    web:
      exposure:
        include: "governance"

Viewing the Governance Actuator Endpoint

Start the application again and access https://localhost:8443/actuator/governance?tag=FIPS-140-3. You should see the comprehensive report containing the FIPS stance, relevant configuration details, all the test rule runs, and an overall test summary at the bottom:

{
 "details": ...,
 "tests": ...,
  "timestamp": "2024-03-26T14:19:43Z",
  "results": {
    "totalTestCasesRan": 16,
    "totalTestCasesPassed": 16,
    "totalTestCasesFailed": 0,
    "totalTestCasesUnknown": 0,
    "totalTestCasesSkipped": 0,
    "allTestCasesPassed": true
  }
}

The field totalTestCasesRan is the sum of the tests that passed, failed, and resulted in an unknown state. The unknown state can occur when the library encountered a problem running a test, or collecting the data for the test.

For example, the library uses reflection while collecting the configuration of the application. In the case where reflection fails, the test result is unknown. If you encounter this result when running the pre-defined tests, contact Broadcom Support with your use case.

If there are failing or unknown tests, the library forces the application to shut down. However, you can bypass the shutdown by deactivating the specific test or by deactivating the exit-on-failure flag.

See Library Configuration Options for further instructions.