doc: amend README (#11)

Signed-off-by: Mart Somermaa <[email protected]>

Author: mrts

README.md

@@ -46,7 +46,7 @@ final class AuthTokenValidationConfiguration {
 
     private URI siteOrigin;
     private Cache<String, LocalDateTime> nonceCache;
-    private Collection<X509Certificate> trustedRootCACertificates = new HashSet<>();
+    private Collection<X509Certificate> trustedCACertificates = new HashSet<>();
     private boolean isUserCertificateRevocationCheckWithOcspEnabled = true;
     private Duration ocspRequestTimeout = Duration.ofSeconds(5);
     private Duration allowedClientClockSkew = Duration.ofMinutes(3);
@@ -63,7 +63,7 @@ final class AuthTokenValidationConfiguration {
     private AuthTokenValidationConfiguration(AuthTokenValidationConfiguration other) {
         this.siteOrigin = other.siteOrigin;
         this.nonceCache = other.nonceCache;
-        this.trustedRootCACertificates = new HashSet<>(other.trustedRootCACertificates);
+        this.trustedCACertificates = new HashSet<>(other.trustedCACertificates);
         this.isUserCertificateRevocationCheckWithOcspEnabled = other.isUserCertificateRevocationCheckWithOcspEnabled;
         this.ocspRequestTimeout = other.ocspRequestTimeout;
         this.allowedClientClockSkew = other.allowedClientClockSkew;
@@ -89,8 +89,8 @@ Cache<String, LocalDateTime> getNonceCache() {
         return nonceCache;
     }
 
-    Collection<X509Certificate> getTrustedRootCACertificates() {
-        return trustedRootCACertificates;
+    Collection<X509Certificate> getTrustedCACertificates() {
+        return trustedCACertificates;
     }
 
     boolean isUserCertificateRevocationCheckWithOcspEnabled() {
@@ -148,8 +148,8 @@ void validate() {
         Objects.requireNonNull(siteOrigin, "Origin URI must not be null");
         OriginValidator.validateIsOriginURL(siteOrigin);
         Objects.requireNonNull(nonceCache, "Nonce cache must not be null");
-        if (trustedRootCACertificates.isEmpty()) {
-            throw new IllegalArgumentException("At least one trusted root certificate authority must be provided");
+        if (trustedCACertificates.isEmpty()) {
+            throw new IllegalArgumentException("At least one trusted certificate authority must be provided");
         }
         requirePositiveDuration(ocspRequestTimeout, "OCSP request timeout");
         requirePositiveDuration(allowedClientClockSkew, "Allowed client clock skew");

src/main/java/org/webeid/security/validator/AuthTokenValidationConfiguration.java

@@ -73,23 +73,23 @@ public AuthTokenValidatorBuilder withNonceCache(Cache<String, LocalDateTime> cac
     }
 
     /**
-     * Sets the list of trusted user certificate root Certificate Authorities.
-     * In order for the user certificate to be considered valid, the root certificate of the issuer
-     * of the user certificate must be present in this list.
+     * Adds the given certificates to the list of trusted subject certificate intermediate Certificate Authorities.
+     * In order for the user certificate to be considered valid, the certificate of the issuer of the user certificate
+     * must be present in this list.
      * <p>
-     * At least one trusted root Certificate Authority must be provided as mandatory configuration parameter.
+     * At least one trusted intermediate Certificate Authority must be provided as a mandatory configuration parameter.
      *
-     * @param certificates trusted root Certificate Authority certificates
+     * @param certificates trusted intermediate Certificate Authority certificates
      * @return the builder instance for method chaining
      */
-    public AuthTokenValidatorBuilder withTrustedRootCertificateAuthorities(X509Certificate... certificates) {
-        Collections.addAll(configuration.getTrustedRootCACertificates(), certificates);
-        LOG.debug("Trusted root certificate authorities set to {}", configuration.getTrustedRootCACertificates());
+    public AuthTokenValidatorBuilder withTrustedCertificateAuthorities(X509Certificate... certificates) {
+        Collections.addAll(configuration.getTrustedCACertificates(), certificates);
+        LOG.debug("Trusted intermediate certificate authorities set to {}", configuration.getTrustedCACertificates());
         return this;
     }
 
     /**
-     * Sets the list of disallowed user certificate policies.
+     * Adds the given policies to the list of disallowed user certificate policies.
      * In order for the user certificate to be considered valid, it must not contain any policies
      * present in this list.
      *
@@ -130,7 +130,7 @@ public AuthTokenValidatorBuilder withOcspRequestTimeout(Duration ocspRequestTime
     }
 
     /**
-     * Sets the list of OCSP URLs for which the nonce protocol extension will be disabled.
+     * Adds the given URLs to the list of OCSP URLs for which the nonce protocol extension will be disabled.
      * The OCSP URL is extracted from the user certificate and some OCSP services don't support the nonce extension.
      *
      * @param urls OCSP URLs for which the nonce protocol extension will be disabled

src/main/java/org/webeid/security/validator/AuthTokenValidatorBuilder.java

@@ -58,8 +58,8 @@ final class AuthTokenValidatorImpl implements AuthTokenValidator {
     private final Supplier<OkHttpClient> httpClientSupplier;
     private final ValidatorBatch simpleSubjectCertificateValidators;
     private final ValidatorBatch tokenBodyValidators;
-    private final Set<TrustAnchor> trustedRootCACertificateAnchors;
-    private final CertStore trustedRootCACertificateCertStore;
+    private final Set<TrustAnchor> trustedCACertificateAnchors;
+    private final CertStore trustedCACertificateCertStore;
 
     /**
      * @param configuration configuration parameters for the token validator
@@ -89,17 +89,17 @@ final class AuthTokenValidatorImpl implements AuthTokenValidator {
             new SiteCertificateFingerprintValidator(configuration.getSiteCertificateSha256Fingerprint())::validateSiteCertificateFingerprint
         );
 
-        // Create and cache trusted root CA certificate JCA objects for SubjectCertificateTrustedValidator.
-        trustedRootCACertificateAnchors = configuration.getTrustedRootCACertificates()
+        // Create and cache trusted CA certificate JCA objects for SubjectCertificateTrustedValidator.
+        trustedCACertificateAnchors = configuration.getTrustedCACertificates()
             .stream()
             .map(cert -> new TrustAnchor(cert, null))
             .collect(Collectors.toSet());
         try {
             // We use the default JCE provider as there is no reason to use Bouncy Castle, moreover BC requires
             // the validated certificate to be in the certificate store which breaks the clean immutable usage of
-            // trustedRootCACertificateCertStore in SubjectCertificateTrustedValidator.
-            trustedRootCACertificateCertStore = CertStore.getInstance("Collection",
-                new CollectionCertStoreParameters(configuration.getTrustedRootCACertificates()));
+            // trustedCACertificateCertStore in SubjectCertificateTrustedValidator.
+            trustedCACertificateCertStore = CertStore.getInstance("Collection",
+                new CollectionCertStoreParameters(configuration.getTrustedCACertificates()));
         } catch (GeneralSecurityException e) {
             throw new JceException(e);
         }
@@ -149,7 +149,7 @@ public X509Certificate validate(String authToken) throws TokenValidationExceptio
      */
     private ValidatorBatch getCertTrustValidators() {
         final SubjectCertificateTrustedValidator certTrustedValidator =
-            new SubjectCertificateTrustedValidator(trustedRootCACertificateAnchors, trustedRootCACertificateCertStore);
+            new SubjectCertificateTrustedValidator(trustedCACertificateAnchors, trustedCACertificateCertStore);
         return ValidatorBatch.createFrom(
             certTrustedValidator::validateCertificateTrusted
         ).addOptional(configuration.isUserCertificateRevocationCheckWithOcspEnabled(),

src/main/java/org/webeid/security/validator/AuthTokenValidatorImpl.java

@@ -77,7 +77,7 @@ public void validateCertificateNotRevoked(AuthTokenValidatorData actualTokenData
             final OCSPReq request = new OcspRequestBuilder()
                 .certificate(certificate)
                 .enableOcspNonce(!ocspNonceDisabled)
-                .issuer(Objects.requireNonNull(trustValidator.getSubjectCertificateIssuerRootCertificate()))
+                .issuer(Objects.requireNonNull(trustValidator.getSubjectCertificateIssuerCertificate()))
                 .build();
 
             LOG.debug("Sending OCSP request");

src/main/java/org/webeid/security/validator/validators/SubjectCertificateNotRevokedValidator.java

@@ -33,23 +33,17 @@
 import java.security.cert.*;
 import java.util.Set;
 
-/**
- * Validator that validates that the user certificate from the authentication token is signed by a trusted certificate authority.
- * <p>
- * We use the default JCE provider as there is no reason to use Bouncy Castle, moreover BC requires the validated certificate
- * to be in the certificate store which breaks the clean immutable usage of {@code trustedRootCACertificateCertStore}.
- */
 public final class SubjectCertificateTrustedValidator {
 
     private static final Logger LOG = LoggerFactory.getLogger(SubjectCertificateTrustedValidator.class);
 
-    private final Set<TrustAnchor> trustedRootCACertificateAnchors;
-    private final CertStore trustedRootCACertificateCertStore;
-    private X509Certificate subjectCertificateIssuerRootCertificate;
+    private final Set<TrustAnchor> trustedCACertificateAnchors;
+    private final CertStore trustedCACertificateCertStore;
+    private X509Certificate subjectCertificateIssuerCertificate;
 
-    public SubjectCertificateTrustedValidator(Set<TrustAnchor> trustedRootCACertificateAnchors, CertStore trustedRootCACertificateCertStore) {
-        this.trustedRootCACertificateAnchors = trustedRootCACertificateAnchors;
-        this.trustedRootCACertificateCertStore = trustedRootCACertificateCertStore;
+    public SubjectCertificateTrustedValidator(Set<TrustAnchor> trustedCACertificateAnchors, CertStore trustedCACertificateCertStore) {
+        this.trustedCACertificateAnchors = trustedCACertificateAnchors;
+        this.trustedCACertificateCertStore = trustedCACertificateCertStore;
     }
 
     /**
@@ -66,15 +60,15 @@ public void validateCertificateTrusted(AuthTokenValidatorData actualTokenData) t
         selector.setCertificate(certificate);
 
         try {
-            final PKIXBuilderParameters pkixBuilderParameters = new PKIXBuilderParameters(trustedRootCACertificateAnchors, selector);
+            final PKIXBuilderParameters pkixBuilderParameters = new PKIXBuilderParameters(trustedCACertificateAnchors, selector);
             pkixBuilderParameters.setRevocationEnabled(false);
-            pkixBuilderParameters.addCertStore(trustedRootCACertificateCertStore);
+            pkixBuilderParameters.addCertStore(trustedCACertificateCertStore);
 
             // See the comment in AuthTokenValidatorImpl constructor why we use the default JCE provider.
             final CertPathBuilder certPathBuilder = CertPathBuilder.getInstance(CertPathBuilder.getDefaultType());
             final PKIXCertPathBuilderResult result = (PKIXCertPathBuilderResult) certPathBuilder.build(pkixBuilderParameters);
 
-            subjectCertificateIssuerRootCertificate = result.getTrustAnchor().getTrustedCert();
+            subjectCertificateIssuerCertificate = result.getTrustAnchor().getTrustedCert();
 
         } catch (InvalidAlgorithmParameterException | NoSuchAlgorithmException e) {
             throw new JceException(e);
@@ -84,7 +78,7 @@ public void validateCertificateTrusted(AuthTokenValidatorData actualTokenData) t
         }
     }
 
-    public X509Certificate getSubjectCertificateIssuerRootCertificate() {
-        return subjectCertificateIssuerRootCertificate;
+    public X509Certificate getSubjectCertificateIssuerCertificate() {
+        return subjectCertificateIssuerCertificate;
     }
 }

src/main/java/org/webeid/security/validator/validators/SubjectCertificateTrustedValidator.java

@@ -83,7 +83,7 @@ private static AuthTokenValidatorBuilder getAuthTokenValidatorBuilder(String uri
         return new AuthTokenValidatorBuilder()
             .withSiteOrigin(URI.create(uri))
             .withNonceCache(cache)
-            .withTrustedRootCertificateAuthorities(certificates);
+            .withTrustedCertificateAuthorities(certificates);
     }
 
     private static X509Certificate[] getCACertificates() throws CertificateException {

src/test/java/org/webeid/security/testutil/AuthTokenValidators.java

@@ -25,7 +25,7 @@ void testRootCertificateAuthorityMissing() {
             .withNonceCache(AbstractTestWithCache.createCache("AuthTokenValidatorBuilderTest"));
         assertThatThrownBy(builderWithMissingRootCa::build)
             .isInstanceOf(IllegalArgumentException.class)
-            .hasMessageStartingWith("At least one trusted root certificate authority must be provided");
+            .hasMessageStartingWith("At least one trusted certificate authority must be provided");
     }
 
 }