API-Changes.txt

NEXT MAJOR VERSION - LITE PKI VALIDATION

This release is deliberately source- and binary-incompatible with 2.x. The
behavioral contract and migration rules are in
docs/changes/0003-lite-pki-contract.md.

Planned removals include all proxy-certificate APIs, namespace-policy APIs,
legacy OpenSSL subject hashes, and the detailed copied-reviewer validation
error catalogue. Validator constructors and parameter objects will no longer
accept proxy or namespace settings.

Certificate-array validation treats the first certificate as the target and
the rest as path-building candidates. Successful results contain the resolved
chain and selected trust anchor. Invalid results report one primary native-PKIX
failure with its cause, stage, and certificate position. Error listeners can
observe failures but can no longer suppress them.

OCSP remains supported. Core native OCSP and CRL modes are migrated first;
responder configuration, ordering, nonce, and cache behavior follow in
separately reviewed changes. No OCSP capability is removed silently.

The exact removed and replacement Java symbols will be appended by the PR that
changes each part of the API.


MAVEN COORDINATES AND JAVA BASELINE

The published Maven coordinates changed from eu.eu-emi.security:canl to
io.imunity.tanl:tanl. Java package names remain under eu.emi.security; this is
an artifact-coordinate change, not a package relocation.

The library now targets Java 17. Building it requires JDK 17 or newer and
Maven 3.9.2 or newer.

The initial TANL development version is 0.0.1-SNAPSHOT.


DEPRECATED CANL COMPATIBILITY APIS REMOVED

TANL does not carry forward project-owned APIs that CANL had already
deprecated. The following types were removed:

- eu.emi.security.authn.x509.impl.SocketFactoryCreator
- eu.emi.security.authn.x509.impl.AbstractHostnameToCertificateChecker
- eu.emi.security.authn.x509.impl.HostnameMismatchCallback

Use SocketFactoryCreator2 and HostnameMismatchCallback2 for JSSE integration
and hostname mismatch handling. The following members and constructor
signatures were also removed:

- CrlCheckingMode.IF_VALID (use IF_PRESENT)
- RevocationParameters(CrlCheckingMode) (pass OCSPParametes explicitly)
- RevocationParametersExt(CrlCheckingMode, CRLParameters) (pass
  OCSPParametes explicitly)
- KeyStoreHelper.getInstance(String) (use getInstanceForTrust(String) or
  getInstanceForCredential(String), according to the keystore role)


PROXY CERTIFICATE SUPPORT REMOVED

Proxy-aware validation and proxy generation/inspection are no longer part of
the library. Normal PKIX processing rejects both legacy proxy certificates and
RFC 3820 proxy certificates; there is no compatibility flag that enables them.

The following public types were removed:

- eu.emi.security.authn.x509.ProxySupport
- eu.emi.security.authn.x509.proxy.BaseProxyCertificateOptions
- eu.emi.security.authn.x509.proxy.CertificateExtension
- eu.emi.security.authn.x509.proxy.OidAndValue
- eu.emi.security.authn.x509.proxy.ProxyCSR
- eu.emi.security.authn.x509.proxy.ProxyCSRGenerator
- eu.emi.security.authn.x509.proxy.ProxyCSRInfo
- eu.emi.security.authn.x509.proxy.ProxyCertificate
- eu.emi.security.authn.x509.proxy.ProxyCertificateOptions
- eu.emi.security.authn.x509.proxy.ProxyChainInfo
- eu.emi.security.authn.x509.proxy.ProxyChainType
- eu.emi.security.authn.x509.proxy.ProxyGenerator
- eu.emi.security.authn.x509.proxy.ProxyPolicy
- eu.emi.security.authn.x509.proxy.ProxyRequestOptions
- eu.emi.security.authn.x509.proxy.ProxyType
- eu.emi.security.authn.x509.proxy.ProxyUtils

The following members and constructor signatures were removed:

- X509CertChainValidatorExt.getProxySupport()
- ValidatorParams.DEFAULT_PROXY_SUPPORT
- ValidatorParams(RevocationParameters, ProxySupport)
- ValidatorParams(RevocationParameters, ProxySupport,
  Collection<? extends StoreUpdateListener>)
- ValidatorParams.isAllowProxy()
- ValidatorParams.setAllowProxy(ProxySupport)
- ValidatorParamsExt(RevocationParametersExt, ProxySupport)
- ValidatorParamsExt(RevocationParametersExt, ProxySupport,
  Collection<? extends StoreUpdateListener>)

Use ValidatorParams and ValidatorParamsExt constructors with only revocation
settings and, where needed, initial store-update listeners.

The proxyEECInChain, proxyLength, proxyNoIssuer, proxyCASet,
proxyIssuerAltNameSet, proxySubjectAltNameSet, proxyIssuedByCa,
proxyNoIssuerSubject, proxySubjectInconsistent, proxyIssuerNoDsig,
proxySubjectOneRDN, proxySubjectMultiLastRDN, proxySubjectLastRDNNotCN,
proxySubjectBaseWrong, proxyTypeInconsistent, and proxyInconsistentlyLimited
ValidationErrorCode values were removed. The INCONSISTENT_PROXY_CHAIN and
INVALID_PROXY_CERT ValidationErrorCategory values were removed with them.


OPENSSL TRUSTSTORE SIMPLIFIED

OpenSSL-style truststores now contain hashed CA certificates and CRLs only.
The library uses the modern OpenSSL subject hash unconditionally. Certificate
collision suffixes remain HASH.0, HASH.1, and so on; CRL suffixes remain
HASH.r0, HASH.r1, and so on. Pre-OpenSSL-1.0 MD5 subject hashes are no longer
recognized. Globus .signing_policy and EUGridPMA .namespaces files are neither
loaded nor enforced.

The following public types were removed:

- eu.emi.security.authn.x509.NamespaceCheckingMode
- eu.emi.security.authn.x509.helpers.ns.AbstractEuGridPmaNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.AbstractGlobusNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.AbstractNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.EuGridPmaNamespacesParser
- eu.emi.security.authn.x509.helpers.ns.EuGridPmaNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.GlobusNamespacesParser
- eu.emi.security.authn.x509.helpers.ns.GlobusNamespacesParser.InvalidPolicyFilenameException
- eu.emi.security.authn.x509.helpers.ns.GlobusNamespacesParser.PolicySyntaxException
- eu.emi.security.authn.x509.helpers.ns.GlobusNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.LazyEuGridPmaNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.LazyGlobusNamespacesStore
- eu.emi.security.authn.x509.helpers.ns.NamespaceChecker
- eu.emi.security.authn.x509.helpers.ns.NamespacePolicy
- eu.emi.security.authn.x509.helpers.ns.NamespacesParser
- eu.emi.security.authn.x509.helpers.ns.NamespacesStore
- eu.emi.security.authn.x509.helpers.ns.OpensslNamespacePolicyImpl
- eu.emi.security.authn.x509.helpers.ns.ParserUtils
- eu.emi.security.authn.x509.helpers.trust.OpensslTrustAnchorStore

The following OpensslCertChainValidator members and constructor signatures
were removed:

- OpensslCertChainValidator(String, NamespaceCheckingMode, long,
  ValidatorParams)
- OpensslCertChainValidator(String, boolean, NamespaceCheckingMode, long,
  ValidatorParams)
- OpensslCertChainValidator(String, boolean, NamespaceCheckingMode, long,
  ValidatorParams, boolean)
- OpensslCertChainValidator(String, NamespaceCheckingMode, long)
- OpensslCertChainValidator.getNamespaceCheckingMode()

Use these modern-hash replacements:

- OpensslCertChainValidator(String, long, ValidatorParams)
- OpensslCertChainValidator(String, long, ValidatorParams, boolean)
- OpensslCertChainValidator(String, long)
- OpensslCertChainValidator(String)

The final boolean in the full replacement constructor still selects lazy or
eager loading. There is no namespace or hash-format compatibility flag.

The following namespace-specific members were removed:

- StoreUpdateListener.EACL_NAMESPACE
- StoreUpdateListener.EUGRIDPMA_NAMESPACE
- ValidationErrorCode.nsUndefinedAndRequired
- ValidationErrorCode.nsDeny
- ValidationErrorCode.nsNotAccepted
- ValidationErrorCategory.NAMESPACE

The following helper signatures were removed or replaced:

- OpensslTruststoreHelper.getNsFile(String, String)
- OpensslTruststoreHelper.getOpenSSLCAHash(X500Principal, boolean), replaced
  by getOpenSSLCAHash(X500Principal)
- OpensslTrustAnchorStoreImpl(String, Timer, long, boolean, boolean,
  ObserversHandler, boolean), replaced by the same constructor without the
  three boolean namespace/hash arguments
- LazyOpensslTrustAnchorStoreImpl(String, long, ObserversHandler, boolean),
  replaced by the same constructor without the boolean hash argument
- OpensslCRLStoreSpi(String, long, Timer, ObserversHandler, boolean), replaced
  by the same constructor without the boolean hash argument
- LazyOpensslCRLStoreSpi(String, long, ObserversHandler, boolean), replaced by
  the same constructor without the boolean hash argument


NATIVE PKIX BASE VALIDATION

When both CRL and OCSP checking are disabled, certificate paths are now built
and validated by the native Bouncy Castle PKIX CertPathBuilder and
CertPathValidator selected explicitly from the BC provider.

For X509Certificate array input, element zero is the target and the remaining
elements are unordered path-building candidates. CertPath input is validated
directly without rebuilding or reordering. An included trust-anchor
certificate is removed before validation, while successful ValidationResult
chains include the selected anchor. An exact configured, self-signed trust
anchor is accepted as a one-certificate input.

Strict CRL-only validation is migrated to native BC in the subsequent native
CRL change. Other revocation configurations remain available on the existing
compatibility path until their dedicated migration changes.


PRIMARY VALIDATION ERROR CONTRACT

ValidationResult is now immutable and contains either no errors for a valid
result or one primary error for an invalid result. getErrors() remains as an
immutable empty or single-element compatibility view. The following public
members were removed:

- ValidationResult(boolean)
- ValidationResult(boolean, List<ValidationError>)
- ValidationResult(boolean, List<ValidationError>, Set<String>,
  List<X509Certificate>)
- ValidationResult.addErrors(List<ValidationError>)
- ValidationResult.setErrors(List<ValidationError>)

Use ValidationResult.valid(List<X509Certificate>),
ValidationResult.invalid(ValidationError), or
ValidationResult.invalid(ValidationError, Set<String>) when constructing a
result. ValidationResult.getPrimaryError() returns the one error directly.

ValidationErrorListener.onValidationError(ValidationError) now returns void.
Listeners receive notification of the immutable primary error but can no
longer suppress it or change the validation verdict.

ValidationStage was added with INPUT, PATH_BUILDING, PATH_VALIDATION, and
REVOCATION values. Native errors expose their stage, original provider message,
original cause, position, and certificate through ValidationError. Stable
native codes and categories use the uppercase names documented in the lite
PKI contract. Provider failures with an unspecified standard reason use
PKIX_FAILURE; provider messages are diagnostic and are not parsed.

CommonX509TrustManager, SSLTrustManager, and
SSLTrustManagerWithHostnameChecking now preserve the primary validation
exception as the cause of their TLS-facing CertificateException.

Revocation configurations not yet migrated continue to use the existing
revocation engine. Their verdicts and OCSP behavior remain available, while
their old detailed error catalogue is temporarily retained until native
revocation replaces that path.


NATIVE STRICT CRL VALIDATION

Validation configured with CrlCheckingMode.REQUIRE and
OCSPCheckingMode.IGNORE now uses the native BC CertPathValidator for strict CRL
checking. The selected path is first validated with revocation disabled and is
then validated against the configured CRL store, so a CRL failure is reported
at the REVOCATION stage rather than as a path-building failure.

The native validator retains all supplied certificate candidates for CRL
issuer discovery and enables native delta-CRL processing. Missing, expired,
malformed, badly signed, and revoking CRLs all fail strict validation. Separate
and indirect CRL signer certificates and delta CRLs remain supported where BC
can resolve them from the supplied certificate and CRL stores.

BC 1.85 reports its CRL failures with an unspecified standard reason, including
definitive revocation. Such failures therefore use PKIX_FAILURE, as required by
the primary-error contract, while preserving REVOCATION stage, certificate
position, provider message, and cause. Provider text is not parsed to infer a
more specific code.

CrlCheckingMode.IF_VALID, every OCSP-enabled configuration, mechanism ordering,
and useAllEnabled continue through the compatibility implementation in this
stacked change. OCSP support is unchanged. The IF_VALID/IF_PRESENT decision and
native OCSP migration remain separate changes.


NATIVE REQUIRED OCSP VALIDATION

Validation configured with CrlCheckingMode.IGNORE and
OCSPCheckingMode.REQUIRE now uses a native BC PKIXRevocationChecker for a
narrow core configuration: exactly one explicit OCSPResponder, no Authority
Information Access extension on any supplied certificate, default responder
settings, and no nonce or persistent cache. Both certificate-array and
asserted-CertPath inputs are supported.

Base path validation and strict OCSP checking are separate passes. The OCSP
pass explicitly adds BC's PKIXRevocationChecker with NO_FALLBACK while leaving
ordinary PKIX revocation disabled, preventing an unintended CRL fallback.
Good responses validate; revoked, unknown, expired, malformed, and badly
signed responses fail.

BC 1.85 exposes no standard reason for the observed OCSP failures, including
definitive revocation, so they use PKIX_FAILURE at the REVOCATION stage while
retaining the provider cause, message, and position where available. Provider
text is not parsed. Malformed response bytes can fail before a certificate
index is assigned and therefore retain position -1.

Configurations using AIA discovery, multiple responders, non-default timeout
or cache controls, nonce, OCSPCheckingMode.IF_AVAILABLE, CRL/OCSP combinations,
mechanism ordering, or useAllEnabled remain on the compatibility path. The
migrated core currently uses BC's native 15-second transport timeout and weak
in-memory response cache; transport controls, caching, and responder discovery
remain separate migration layers.


NATIVE OCSP RESPONDER DISCOVERY

Strict OCSP-only validation now discovers a responder from certificate
Authority Information Access when no explicit OCSPResponder is configured and
every supplied non-anchor certificate contains exactly one HTTP(S) OCSP URI.
Default responder settings are required. Certificate arrays and asserted
CertPath inputs are supported, and configured trust anchors are not themselves
revocation-checked.

The selected path is first validated normally. Each certificate/issuer edge is
then checked in a separate native BC OCSP pass using that certificate's own
discovered responder URI and its already validated issuer. This supports
chains whose CAs advertise different responders without changing the
JVM-global ocsp.enable setting. Failures are remapped to their position in the
complete selected path.

Missing, multiple, malformed, relative, or non-HTTP(S) discovered responder
locations, mixed configured/discovered responders, nonce, non-default cache
controls outside the separately documented memory-cache layer,
OCSPCheckingMode.IF_AVAILABLE, and all CRL/OCSP combinations remain on the
compatibility path. Multiple responders are not retried natively because BC
1.85 does not structurally distinguish responder failures from definitive
revocation; provider messages are not parsed.


NATIVE OCSP CONNECTION TIMEOUT

Strict OCSP-only validation now honors OCSPParametes.getConntectTimeout()
through the native validation path when OCSP response caching is explicitly
disabled with a negative cache TTL. This applies to both the single configured
responder and single-per-certificate AIA configurations migrated previously.
HTTP(S) requests are built and fetched by the retained OCSP transport with the
configured connect/read timeout. The encoded response is then supplied to
PKIXRevocationChecker.setOcspResponses(), and native BC remains responsible
for response signature, signer, certificate status, and freshness validation.

This initial timeout layer applied when caching was disabled. The subsequent
native response-cache layer extends the same per-request transport to default
and custom in-memory cache TTLs. Disk cache, nonce, multiple responders,
responder ordering, OCSPCheckingMode.IF_AVAILABLE, and CRL/OCSP combinations
remain on the compatibility path. Transport and response failures remain
strict invalid results reported as PKIX_FAILURE at the REVOCATION stage;
provider messages are not parsed to infer whether a later responder should be
attempted.


NATIVE OCSP IN-MEMORY RESPONSE CACHE

The previously migrated strict OCSP configurations now use a bounded,
thread-safe, per-validator cache of encoded OCSP responses for every
non-negative OCSPParametes cache TTL. A negative TTL continues to disable
caching, and zero leaves expiry to response metadata. The cache contains at
most 100 certificate/responder entries and expires each response at the
earliest of the configured TTL, HTTP Cache-Control max-age, and OCSP
nextUpdate. Cached byte arrays are copied at both cache boundaries.

Only responses accepted by native BC are added. Every cache hit is supplied
again to PKIXRevocationChecker.setOcspResponses(), so native BC revalidates the
response against the current certificate, issuer, trust, status, and time.
Rejected, forged, malformed, unknown, or revoked responses are not cached.
The cache key includes the responder URI, checked certificate, issuer, and any
explicit trusted responder certificate.

OCSPParametes documents cache TTL in seconds, and the native cache now honors
that unit; the legacy cache accidentally treated the same value as
milliseconds. The default 3600 therefore means one hour, still capped by HTTP
and OCSP response expiry. Persistent disk caching remains on the compatibility
path for its dedicated migration layer. Nonce, multiple/responder ordering,
OCSPCheckingMode.IF_AVAILABLE, and CRL/OCSP combinations remain unchanged on
compatibility code. Persistent caching is added by the following migration
layer.


NATIVE OCSP PERSISTENT RESPONSE CACHE

A configured OCSPParametes disk cache path now extends the native encoded-
response cache across validator instances and process restarts. The native
cache directory is created when necessary. Stable SHA-256 filenames bind each
entry to its responder URI, certificate, issuer, and explicit responder
certificate. Existing serialized ocspresp_ files are ignored; native entries
use a versioned ocspresp-v1-*.cache format with no Java deserialization.

Persistent entries retain their original fetch time and response-expiry limit,
so configured TTL, HTTP max-age, and OCSP nextUpdate are enforced after a
restart. Files have strict headers, lengths, and a 64 KiB bound. Writes use a
same-directory temporary file and atomic replacement when supported.
Malformed, truncated, oversized, future-dated, expired, unreadable, or
otherwise corrupt entries are removed and treated as cache misses. A cache
read or write failure never creates a valid result by itself.

Every loaded response is passed to a fresh PKIXRevocationChecker before use.
If native validation rejects it, the memory and disk entries are deleted and
one response is fetched and checked normally. Only newly fetched responses
accepted by native BC are persisted. A negative cache TTL still disables both
memory and disk caching even when a disk path is configured. Nonce, multiple
responders and ordering, OCSPCheckingMode.IF_AVAILABLE, CRL/OCSP combinations,
and OCSP update notifications remain separate migration layers. Nonce support
is added by the following migration layer.


NATIVE OCSP NONCE VALIDATION

Strict native OCSP validation now honors OCSPParametes.isUseNonce() for both
one configured responder and one discovered responder per certificate. Each
request receives a fresh 16-byte nonce generated by SecureRandom. A response
must contain a BasicOCSPResp nonce extension whose value exactly matches the
request. A missing, malformed, or mismatched nonce fails validation as
PKIX_FAILURE at the REVOCATION stage.

Nonce comparison is a narrow structural check performed before the encoded
response is supplied to PKIXRevocationChecker. Native BC remains responsible
for the response signature, signer authorization, certificate identity and
status, and freshness. Provider messages are not parsed and the compatibility
response verifier is not used as a second validation authority.

Nonce-enabled validation always performs a new request and bypasses both the
memory and persistent response caches, regardless of configured cache TTL or
disk path. A cached response is bound to its original request nonce and can
not establish freshness for a later validation. Nonce-free caching behavior
is unchanged. Multiple responders and ordering, OCSPCheckingMode.IF_AVAILABLE,
CRL/OCSP combinations, and OCSP update notifications remain separate layers.
Deterministic responder selection is added by the following migration layer.


NATIVE OCSP RESPONDER ORDERING

Strict native OCSP validation now accepts multiple configured responders,
multiple certificate AIA responders, and configurations containing both. The
configured responder array and AIA access descriptions each retain their
original order. OCSPParametes.isPreferLocalResponders() selects which group is
placed first; an empty preferred group naturally selects the other group.
The first resulting responder is used independently for each certificate in
the validated path.

Configured responders retain their explicitly trusted responder certificate.
Discovered responders use the already validated issuer context. Timeout,
nonce, and cache behavior from the preceding native layers apply to the
selected responder. A non-empty preferred configured group can be selected
without parsing unused AIA metadata; AIA remains strict whenever the
discovered group is needed.

This layer deliberately selects but does not retry. A native OCSP rejection is
returned immediately and is not converted into success by a later responder.
BC 1.85 does not structurally distinguish revoked, unknown, stale, forged, or
otherwise invalid responses in the observed CertPathValidatorException
reasons, and provider messages are not parsed to guess retryability. Safe
transport-failure fallback is added by the following layer.


NATIVE OCSP TRANSPORT FALLBACK

Strict native OCSP validation now tries the next ordered responder when an
HTTP(S) connection, request, or response-read operation fails. Fallback
crosses configured and AIA responder groups in the order established by
OCSPParametes.isPreferLocalResponders(). A successful response still passes
through nonce enforcement and a fresh PKIXRevocationChecker before it can
produce a valid result. If every attempted responder has a transport failure,
the final transport failure is returned at the original certificate position.

Response-data failures are explicitly separated from transport failures.
Oversized or ASN.1-malformed OCSP bytes raise a bounded response-decoding
failure and stop validation. Missing or mismatched nonces and every native BC
response rejection also stop immediately. This prevents revoked, unknown,
stale, forged, or otherwise invalid response data from being converted into
success by a later responder. Retry decisions use exception types and control
flow only; provider messages are not parsed.

Response caches remain keyed by responder, certificate, issuer, and explicit
responder certificate, so fallback can reuse only a response belonging to the
candidate being attempted. Nonce-enabled attempts continue to bypass caches.
OCSPCheckingMode.IF_AVAILABLE, CRL/OCSP combinations, responder-failure
caching, and update notifications remain separate layers.


NATIVE OCSP RESPONDER FAILURE CACHE

Responder-wide transport failures from the native OCSP fetch path are now
cached by responder URI. This includes connection, request-write, timeout,
response-read, and explicit HTTP 502/503/504 failures. Other HTTP errors remain
retryable for ordered fallback but are not cached because they can be specific
to one certificate request. A live failure entry skips that responder without
opening a connection and remains a retryable outcome, so ordered validation
can proceed to the next configured or AIA responder. A successfully cached
OCSP response is still tried before the responder-failure cache, and any newly
received non-cacheable HTTP response clears the responder's failure entry.

Failure caching uses the existing OCSPParametes cache controls. A negative TTL
disables both response and failure caching. Positive values expire failure
entries in the documented unit of seconds. Since a failure has no response
validity metadata, zero uses OCSPParametes.DEFAULT_CACHE as a bounded one-hour
failure lifetime instead of suppressing a responder forever.

Each validator's in-memory failure cache is access-ordered and limited to 100
responder URIs. When a disk-cache directory is configured, failure metadata is
stored separately as ocspfail-v1-<sha256>.cache. The digest covers the
responder URI, and the versioned fixed-size record contains only the failure
timestamp. Java exceptions and provider messages are never serialized or used
as cache keys. Corrupt, truncated, future-dated, and expired records are
deleted as cache misses; persistence errors do not alter validation.

Only the IOException transport boundary classified by the transport-fallback
layer creates an entry. Oversized or malformed response bytes, nonce failures,
and all native BC response-validation failures remain terminal and are never
negative-cached. Nonce-enabled requests bypass response caching but retain
responder-failure caching because availability is independent of response
replay.

OCSPCheckingMode.IF_AVAILABLE, CRL/OCSP combinations, and update notifications
remain separate layers.


NATIVE OCSP UPDATE NOTIFICATIONS

Native OCSP request and response-processing failures are now reported through
the validator's existing StoreUpdateListener collection. Each notification
uses the responder URI as its location, StoreUpdateListener.OCSP as its type,
Severity.WARNING, and the original structured exception as its cause. The
native validator retains the shared ObserversHandler, so both initial listeners
and listeners registered after validator construction observe these events.

Notifications are emitted for request-construction failures, HTTP transport
failures, cached responder failures, bounded response-decoding failures, nonce
failures, and encoded-response processing failures. They are emitted at each
responder attempt, including a failed attempt hidden by successful fallback.
Response cache hits and successful fetches do not emit update notifications,
matching the compatibility path.

Native BC response-validation failures are deliberately excluded. BC 1.85
does not structurally distinguish a revoked or unknown certificate status from
an invalid signature, unauthorized signer, stale response, or similar
provider failure. Treating every such result as a responder loading warning
would incorrectly report definitive certificate status as an infrastructure
problem, while parsing provider messages would be unstable. All such results
remain terminal validation failures exactly as before.

OCSPCheckingMode.IF_AVAILABLE and CRL/OCSP combinations remain separate
layers.


NATIVE OCSP IF_AVAILABLE MODE

OCSP-only validation using OCSPCheckingMode.IF_AVAILABLE now runs through the
native ordered OCSP path for both certificate-array and asserted-CertPath
entry points. Configuration, discovery, preference, timeout, cache, nonce,
fallback, failure-cache, and update-notification behavior is shared with the
required mode.

The optional boundary is defined without provider-message parsing. A missing
configured/AIA responder, or exhaustion of all ordered responders through
structured HTTP transport failures, is accepted for that already base-
validated certificate/issuer edge. Transport failures still produce OCSP
update warnings and failure-cache entries before validation continues.

Once response bytes are received, validation is strict. Malformed or oversized
data, missing or mismatched nonces, revoked or unknown status, bad signatures,
unauthorized responders, stale responses, and every other native rejection
remain terminal failures. Accepted responses must pass the same fresh native
PKIXRevocationChecker used by REQUIRE.

This intentionally narrows the historical IF_AVAILABLE behavior, which also
ignored unknown and general response errors. BC 1.85 exposes neither a working
soft-failure list for its OCSP checker nor stable standard reasons that
distinguish a signed unknown status from forged, stale, unauthorized, or other
invalid responses. Softening an unsigned status parsed before native
validation would allow a forged unknown response to bypass revocation checks.
The public OCSPCheckingMode documentation now states the safe availability-
only contract.

CRL/OCSP combinations, mechanism ordering, and useAllEnabled remain separate
layers.


NATIVE COMBINED REVOCATION POLICY

Configurations combining CrlCheckingMode.REQUIRE with either
OCSPCheckingMode.REQUIRE or OCSPCheckingMode.IF_AVAILABLE now use native
Bouncy Castle validation for both certificate-array and asserted-CertPath
entry points. Base path validation is completed first, then the configured
RevocationCheckingOrder and useAllEnabled policy is applied independently to
each non-anchor certificate.

Native OCSP now retains an internal distinction between a verified response
and unavailability. With useAllEnabled false, only a verified first mechanism
short-circuits the second. Optional OCSP absence or exhaustion through HTTP
transport failures advances to CRL when CRL is next. A received invalid OCSP
response and every strict CRL or required OCSP failure remain terminal and do
not trigger mechanism fallback. With useAllEnabled true both mechanisms are
evaluated, subject to their individual required or optional mode.

The combined path reuses all native OCSP responder discovery, ordering,
transport, cache, nonce, failure-cache, and notification behavior. CRLs are
checked natively for each certificate/issuer edge using the configured CRL
and certificate stores. No provider messages are parsed and no unsigned OCSP
status is trusted.

RevocationParameters.clone() now preserves RevocationCheckingOrder and
useAllEnabled instead of silently resetting both to their defaults.

CrlCheckingMode.IF_VALID, including its combined configurations, remains on
the compatibility implementation pending the separate IF_PRESENT decision.


NATIVE CRL IF_PRESENT MODE

CrlCheckingMode.IF_PRESENT was added for optional, present-but-enforced CRL
validation and is now the default. The deprecated CrlCheckingMode.IF_VALID
compatibility alias was subsequently removed from TANL.

The selected path is base-validated first. For each non-anchor certificate,
the configured store is queried for parsed X509CRLs issued by the certificate
issuer or by an explicit directory-name cRLIssuer in its CRL Distribution
Points extension. If none exists, that edge is unavailable and is accepted by
CRL-only validation or passed to the next combined-policy mechanism. If any
candidate exists, the edge is validated using strict native BC CRL checking.

Candidate discovery does not pre-validate dates, signatures, distribution-
point scope, reason coverage, delta relationships, or revocation status.
Consequently expired, badly signed, inapplicable, incomplete, revoking, and
otherwise rejected candidate sets remain terminal. Malformed source bytes
which the configured store can not decode are not parsed X509CRL candidates;
existing CRL loading-error notifications still report them.

The native mode supports certificate arrays, asserted CertPaths, partially
populated chains, indirect CRL issuers, distribution-point CRLs, delta CRLs,
and combined CRL/OCSP order and useAllEnabled policy. Store-query and CRL
Distribution Points parsing failures are terminal. Unrelated issuers do not
activate strict checking. Provider messages are not parsed and native BC
remains the sole authority for every present candidate.


LEGACY VALIDATION ENGINE REMOVED

Native Bouncy Castle PKIX validation is now the only certificate-path and
revocation-validation implementation. All retained CRL, OCSP, and combined
configurations route to it for both certificate arrays and CertPath inputs.
There is no compatibility fallback. Unsupported or null configuration is
reported as INVALID_INPUT.

The custom OCSP request and bounded HTTP transport needed by native validation
is package-private and never authenticates or interprets response status.
Native PKIXRevocationChecker remains the sole response-validation authority.
The removed internal-package standalone OCSP client also exposed signed
requests through an X509Credential argument. Validator configuration never
supported a request signer, so retained validator requests remain unsigned.
Direct users should use Bouncy Castle's OCSP request API.

The following public types were removed:

- eu.emi.security.authn.x509.helpers.pkipath.BCCertPathValidator
- eu.emi.security.authn.x509.helpers.pkipath.BCErrorMapper
- eu.emi.security.authn.x509.helpers.pkipath.ExtPKIXParameters2
- eu.emi.security.authn.x509.helpers.pkipath.ExtPKIXParameters2.Builder
- eu.emi.security.authn.x509.helpers.pkipath.NonValidatingCertPathBuilder
- eu.emi.security.authn.x509.helpers.pkipath.SimpleValidationErrorException
- eu.emi.security.authn.x509.helpers.pkipath.ValidationErrorException
- eu.emi.security.authn.x509.helpers.pkipath.bc.CertPathValidatorUtilitiesCanl
- eu.emi.security.authn.x509.helpers.pkipath.bc.FixedBCPKIXCertPathReviewer
- eu.emi.security.authn.x509.helpers.pkipath.bc.PKIXPolicyNode
- eu.emi.security.authn.x509.helpers.pkipath.bc.RFC3280CertPathUtilitiesCanl
- eu.emi.security.authn.x509.helpers.revocation.CRLRevocationChecker
- eu.emi.security.authn.x509.helpers.revocation.RevocationChecker
- eu.emi.security.authn.x509.helpers.revocation.RevocationStatus
- eu.emi.security.authn.x509.helpers.ocsp.BoundedSizeLruMap
- eu.emi.security.authn.x509.helpers.ocsp.OCSPCacheBase
- eu.emi.security.authn.x509.helpers.ocsp.OCSPCachingClient
- eu.emi.security.authn.x509.helpers.ocsp.OCSPClientImpl
- eu.emi.security.authn.x509.helpers.ocsp.OCSPClientImpl.OCSPResponseDecodingException
- eu.emi.security.authn.x509.helpers.ocsp.OCSPRespondersCache
- eu.emi.security.authn.x509.helpers.ocsp.OCSPResponseStructure
- eu.emi.security.authn.x509.helpers.ocsp.OCSPResponsesCache
- eu.emi.security.authn.x509.helpers.ocsp.OCSPResult
- eu.emi.security.authn.x509.helpers.ocsp.OCSPResult.Status
- eu.emi.security.authn.x509.helpers.ocsp.OCSPRevocationChecker
- eu.emi.security.authn.x509.helpers.ocsp.OCSPVerifier

The following ValidationError members were removed with the compatibility
error formatter:

- ValidationError(X509Certificate[], int, ValidationErrorCode, Object...)
- ValidationError.getParameters()
- ValidationError.makeReason(Throwable)
- ValidationError.makeReasonFromStack(Throwable)

The protected AbstractValidator.validator compatibility-reviewer field was
removed. Subclasses continue to initialize through AbstractValidator.init()
and validation is always delegated to the private native implementation.

The GENERAL_INPUT, X509_BASIC, X509_CHAIN, CRL, and OCSP
ValidationErrorCategory values were removed. INPUT, PATH, CERTIFICATE,
NAME_CONSTRAINT, POLICY, REVOCATION, and OTHER are the complete retained set.

The following legacy ValidationErrorCode values were removed:

- unknown, unknownMsg, inputError, emptyCertPath, invalidCertificatePath
- noIssuerPublicKey, noBasicConstraints, pathLenghtExtended,
  conflictingTrustAnchors, noTrustAnchorFound, trustButInvalidCert,
  signatureNotVerified, certificateNotYetValid, certificateExpired, noCACert,
  noCertSign, unknownCriticalExt, certWrongIssuer, errorProcesingBC,
  QcStatementExtError, certPathCheckerError, criticalExtensionError,
  unknownCriticalExts, pubKeyError, processLengthConstError,
  rootKeyIsValidButNotATrustAnchor, trustAnchorIssuerError, trustDNInvalid,
  trustKeyUsage, trustPubKeyError
- explicitPolicy, invalidPolicyMapping, invalidPolicy, noValidPolicyTree,
  policyConstExtError, policyExtError, policyInhibitExtError,
  policyMapExtError, policyQualifierError
- excludedDN, excludedEmail, excludedIP, ncExtError, ncSubjectNameError,
  notPermittedDN, notPermittedEmail, notPermittedIP, subjAltNameExtError
- certRevoked, noBaseCRL, noValidCrlFound, noCrlForExpiredCert,
  crlVerifyFailed, distrPtExtError, crlAuthInfoAccError, crlBCExtError,
  crlDistPtExtError, crlExtractionError, crlIssuerException,
  crlNoIssuerPublicKey, crlOnlyAttrCert, crlOnlyCaCert, crlOnlyUserCert,
  crlReasonExtError, onlineCRLWrongCA, onlineInvalidCRL, noCrlInCertstore,
  noCrlSigningPermited, loadCrlDistPointError, localInvalidCRL,
  crlUnknownCritExt, crlNoIssuerForDP, crlNoIssuerAndDP,
  crlIDPAndDPMismatch, crlDeltaProblem, crlAKIExtError
- ocspCertRevoked, ocspNoResponder, ocspResponderQueryError,
  ocspResponseInvalid, ocspOtherError

The valiadationErrors.properties compatibility message bundle was removed.
Messages and category mappings for the 17 retained stable codes are now part
of the native error model itself.


RESIDUAL GRID/EMI MATERIAL REMOVED

The public eu.emi.security.authn.x509.impl.OpensslNameUtils class was removed.
It converted RFC 2253 distinguished names to an ambiguous slash-delimited
display syntax and had no remaining production caller. Use X500NameUtils and
X500Principal for standards-based DN parsing, comparison, and display. There
is no replacement for conversion to the historical slash syntax.

The historical gLite validator compatibility matrix, its broad fixture corpus,
and proxy-generation test configuration were removed. Focused tests continue
to cover native PKIX and revocation, modern OpenSSL hashes, absent CRLs,
certificate expiry and revocation, unusual DNs, concurrent validation,
hostname checks, and rejection of proxy certificates.

Obsolete EMI project links and mailing lists, SVN-fetched documentation and
packaging tools, `tools.jar`-dependent site reports, and RPM/Deb packaging
templates were removed. The Maven group/artifact coordinates and Java package
names are intentionally unchanged pending a separately approved publication
identity.


FINAL VERIFICATION AND MIGRATION GUIDE

The retained TLS adapter behavior is covered with real valid, untrusted,
expired, revoked, and unsupported-critical-extension chains. Invalid TLS
chains retain the native primary validation exception as the
CertificateException cause.

docs/migration-guide.md provides current examples for lazy and eager
OpensslCertChainValidator construction, CRL and OCSP policy selection,
responder ordering and useAllEnabled, immutable primary-error handling, and
the modern OpenSSL certificate and CRL hash layout. The compatibility breaks
listed above are the complete intentional removals for this modernization;
OCSP support remains part of the public validator configuration and runtime.


2.x HISTORICAL CHANGES

1) changed semantics of the DN compare methods operating on the string representation.
2) changed ParseException to (runtime) IllegalArgumentException in X500NameUtils. 
3) changed slightly X500NameUtils.getAttributeValues description 
(string form is returned whenever it is possible). also do not return null.
4) removed 3 duplicated methods from CertificateUtils (are in ProxyUtils).
5) CertificateUtils.savePEMKeystore accepts also a separate KS's key's password.
6) CertificateUtils.savePrivateKey allows to write also encrypted DER keys.
7) CertificateUtils.loadPEMKeystore accepts also a separate KS's key's password.
8) Added to more constants to FormatMode for one line printing. 
9) For completeness getKeyAlias method was added to the X509Credential interface.
10) Removed possibility to get not handled non-critical extensions. 
11) Methods setCrl in validators now accepts Set<String> not Set<URL> 
as wildcards may be used.
12) Constructors of validators use a single CRLParams argument as CRL configuration
became more complex
13) added dispose method to validators
14) added new listener to validators: get notification when update error occur
15) added new validator type: FlexibleCertChainValidator
16) optional possibility to add updateError observers in constructor of validators 
17) minor change in ret value of the ProxyChainInfo getXXYYRestriction: empty arrays 
are returned instead of null if no empty restriction is produced.
18) Changed byte[][] into String[] in case of proxy restrictions (consistently)
19) Added  X500Principal getX500Principal(String rfcDn) to X500NameUtils
20) Added proxy generation method with one org (no signing key).
21) Wrapped CRL modes and parameters into Revocation modes and parameters to allow for 
smooth addition of OCSP settings in future.

DEV NOTES:

(questions for java-util):
- Why OpensslCertPAthValidator requires that each proxy (not PC issuer cert) 
has a digital signature bit set?
- Why two Validators? Proxy and Openssl? What about respective tests?
- concatArrayArrays in IPAddressComparator is broken.


- !! HostnameChecker implements the RFC in a strict way. If there is a dNSAltName then CN is not used 
as RFC states. CN matching is used only if dNS altName is not present. 

- X.509 v1 certificates support: intermediary CA certificates are not supported. Roll-over (i.e. 
two trusted v1 certificates with the same subject but different keys) is not supported.

- Trusted certificates from the truststore are trusted and are not checked if are valid.

- Known issue: due to bug in BC (http://www.bouncycastle.org/jira/browse/BJA-370) only masks
8, 16, 24 and 32 are working correctly in Proxy certificate target/source restrictions.