A REST API and web interface that integrates multiple linters to perform pre- and post-issuance linting of PKI artifacts (Certificates, Precertificates, CRLs, and OCSP Responses).
At a glance:
- Features
- Why lint?
- Why use multiple linters?
- Why use pkimetal?
- Supported linters
- Docker containers
- Public instances
- Known users/integrations
- About this project
Details:
- Access multiple linters via a single, simple REST API call.
- Accepts Certificates, Precertificates, CRLs, and OCSP responses as inputs.
- Enables pre-issuance and post-issuance linting.
- Optionally auto-detects the intended profile of the input.
- Runs only the appropriate linters/lints for the selected profile.
- Unifies the linters' findings into a common response format.
- Optimized for performance and scalability.
- Dockerized.
CABForum Ballot SC-75, adopted June 27th 2024, explains that...
Due to the complexity involved in implementing Certificate Profiles that conform to these Requirements, it is considered best practice for the CA to implement a Linting process to test the technical conformity of each to-be-signed artifact prior to signing it.
Linters are not in competition with each other. Different linters have different capabilities, and no linter today claims 100% coverage of all the rules coming from the various root program policies, CABForum requirements, RFCs, etc. Running multiple linters will probably increase your total coverage. If a linter catches even a single issue that no other linter catches, then that linter has proven its worth. Linters, like all software, sometimes have bugs; but it's relatively unlikely that the same bug affects all the linters.
In addition to general-purpose linters for PKI artifacts, there are also special-purpose linters available that can extend your overall linting coverage with a detailed focus on a particular requirement or subset of requirements.
- Software integration: Linters have been developed in several different programming languages: Ruby (Certlint), C (x509lint), Go (ZLint), Python (pkilint). It's not always easy to integrate third-party code written in a different language into your own application. pkimetal does this integration so that you don't have to.
- To-be-signed input: Linters tend to only accept signed PKI artifacts as input, whereas pre-issuance linting is performed on a to-be-signed artifact prior to signing. Figuring out how to convert to-be-signed input into something that the linters can process is sufficiently non-obvious that CABForum Ballot SC-75 includes two suggested methods. pkimetal accepts to-be-signed input and handles this conversion for you.
- Lint selection: Getting the correct linting result for any given input type requires calling the right subset of linters with the right options. pkimetal takes care of this for you.
- Performance: Most of the available linters are designed to be run from the command line, linting one input file each time. With some linters, repeating this process for multiple files can incur some pretty severe performance penalties: the overhead of starting up the programming language interpreter each time, and the overhead of initiating the linter functionality each time. These overheads mean that, for example, it can take half a second to lint just one certificate, which would be a bottleneck for many CAs' certificate issuance rates. pkimetal incurs these performance penalties only once, making the linting of multiple PKI artifacts up to 20x faster!
- Scalability: Even 20x faster might not be enough for some high-volume certificate issuers. pkimetal can run multiple instances of most linters, taking advantage of multiple CPU cores.
Every WebPKI CA is now expected to implement pre-issuance certificate linting. The availability of pkimetal ensures that no CA should struggle to meet this expectation.
General-purpose linters:
- certlint: Certificate linter (CABForum TLS; RFC5280).
- pkilint: Certificate, CRL, and OCSP response linter (CABForum TLS and S/MIME; ETSI EN 319 412 and TS 119 495; RFC5280).
- x509lint: Certificate linter (CABForum TLS; RFC5280).
- zlint: Certificate and CRL linter (CABForum TLS, S/MIME, and Code Signing; ETSI EN 319 412 and TS 119 495; RFC5280).
Special-purpose linters:
- badkeys: Detects various public key vulnerabilities.
- dwklint: Detects Debian weak keys (CVE-2008-0166), as required by CABForum Ballot SC-73.
- ftfy: Detects mojibake (character encoding mix-ups).
- rocacheck: Detects ROCA weak keys (CVE-2017-15361), as required by CABForum Ballot SC-73.
Docker containers are pre-built automatically and published on the Github Container Repository (GHCR). Two different release cycles are provided:
- Stable releases: These have a "vX.X.X" tag on GHCR and are automatically built and published whenever a corresponding pkimetal release is created. The most recent Stable release also receives the "latest" tag. Since Stable releases track versioned releases of each linter project (wherever possible), only Stable releases are recommended for production usage.
- Development releases: These have a "YYYYMMDDHHMMSS" tag on GHCR and are automatically built and published whenever a corresponding commit is pushed to the "main" branch. Since Development releases also track the latest commits to the "main"/"master" branch of each linter project, they are NOT RECOMMENDED for production usage.
Sectigo provides public instances of pkimetal that correspond to the two release cycles:
- Stable: https://pkimet.al/
- Development: https://dev.pkimet.al/
These public instances are provided as-is, on a best effort basis. They are NOT RECOMMENDED for production usage by CAs, because (due to Ballot SC-75) they may be seen as Delegated Third Parties. Your own deployment of the Docker container for the latest Stable release is the appropriate way to deploy pkimetal in a production CA environment.
Here are some projects/CAs that are known to use or integrate with pkimetal:
- Sectigo, crt.sh, and the two Public instances listed above
Please submit a pull request to update README.md if you are aware of another CA/project that uses or integrates with pkimetal.
pkimetal was created by Rob Stradling at Sectigo, and the project is currently maintained at Sectigo by Rob Stradling and Martijn Katerbarg. It is hoped that other publicly-trusted CAs and ecosystem participants will benefit and collaborate on future development. :-)
The "metal" suffix was chosen for its double-meaning: it's both an abbreviation of "meta-linter" and it conveys the idea that (meta-)linting strengthens the PKI!
The project's mascot is a cartoon lint roller pretending to be a brave knight, clad in armour (metal, obviously) to bravely fight the good fight of PKI policy compliance! Standing atop its vanquished foe (a pile of clothes, representing a marauding band of noncompliant TBSCertificates), it proudly displays the battle wounds (linter "findings") sustained during its noble quest. 😉
