CycloneDX / CycloneDX/specification
[2.0]: Define the certificate bytes covered by certificateProperties.fingerprint
- Dominant language
- XSLT
- Stars
- 547
- Forks
- 93
- Avg merge
- 7h 11m
- Merged PRs (30d)
- 37
Description
## Context
This follows the discussion in #1031. A maintainer noted that changing the CycloneDX 1.x semantics could be considered breaking and asked that any corresponding CycloneDX 2.0 issue be tracked separately.
I reviewed the current `2.0-dev` branch at commit `a1c8aeb2e4e6a72851fd937f210e9b5add1cf514`.
In `schema/2.0/model/cyclonedx-cryptography-2.0.schema.json`, `certificateProperties.fingerprint` is still described as:
> The fingerprint is a cryptographic hash of the certificate excluding it's signature.
PR #903 added support for standard and custom fingerprint algorithms, but does not appear to define the exact certificate bytes covered by this field.
## Interoperability question
For an X.509 certificate, at least three different inputs could be interpreted:
1. The complete DER-encoded `Certificate`, including `signatureAlgorithm` and `signatureValue`.
2. The DER-encoded `tbsCertificate`, excluding the outer signature.
3. The DER-encoded SubjectPublicKeyInfo, which identifies the public key rather than the certificate.
These produce different values. OpenSSL certificate fingerprints, Java `X509Certificate.getEncoded()` and Go `x509.Certificate.Raw` normally operate on the complete DER-encoded certificate.
Without an explicit definition, two producers can generate different values for the same certificate while both documents remain schema-valid.
## Requested clarification
Could CycloneDX 2.0 explicitly define the intended input bytes for `certificateProperties.fingerprint`?
If the conventional certificate fingerprint is intended, possible wording would be:
> A cryptographic hash of the complete DER-encoded certificate, including its signature algorithm and signature value. Certificates represented in another encoding, such as PEM, are decoded to DER before hashing.
If `tbsCertificate` is intended instead, it would be helpful to name that structure explicitly and distinguish it from the conventional certificate fingerprint.
## Testing contribution
For a neutral CBOM interoperability test-suite prototype, our current test policy uses SHA-256 over the complete DER certificate for certificate identity and SHA-256 over SPKI for public-key identity. These remain explicit test-policy choices rather than assumed CycloneDX semantics.
If useful, we would be happy to provide fully synthetic fixtures containing complete-DER, `tbsCertificate` and SPKI fingerprints, together with expected values and cross-implementation checks.
Contributor guide
Research direction
Start with schema/2.0/model/cyclonedx-cryptography-2.0.schema.json, then read discussion #1031 and PR #903 to understand the existing fingerprint wording and algorithms. Compare complete DER, tbsCertificate, and SubjectPublicKeyInfo interpretations. Done means the CycloneDX 2.0 semantics explicitly identify the bytes to hash and the interoperability expectations are unambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json
- Domain
- cryptography, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100