zlint

README

ZLint

ZLint is a X.509 certificate linter written in Go that checks for consistency with standards (e.g. RFC 5280) and other relevant PKI requirements (e.g. CA/Browser Forum Baseline Requirements).

It can be used as a command line tool or as a library integrated into CA software.

Requirements

ZLint requires Go 1.13.x or newer be installed. The command line setup instructions assume the go command is in your $PATH.

Lint Sources

Historically ZLint was focused on only RFC 5280 and v1.4.8 of the CA/Browser Forum baseline requirements. A detailed list of the original BR coverage can be found in this spreadsheet.

More recently ZLint has been restructured to make it easier to add lints based on other sources. While not complete, presently ZLint has lints sourced from:

• CA/Browser Forum EV SSL Certificate Guidelines
• ETSI ESI
• Mozilla's PKI policy
• Apple's CT policy
• Various RFCs (e.g. RFC 6818, RFC 4055, RFC 8399)

By default ZLint will apply applicable lints from all sources but consumers may also customize which lints are used by including/exclduing specific sources.

Versioning and Releases

ZLint aims to follow semantic versioning. The addition of new lints will generally result in a MINOR version revision. Since downstream projects depend on lint results and names for policy decisions changes of this nature will result in MAJOR version revision.

Where possible we will try to make available a release candidate (RC) a week before finalizing a production ready release tag. We encourage users to test RC releases to provide feedback early enough for bugs to be addressed before the final release is made available.

Command Line Usage

ZLint can be used on the command-line through a simple bundled executable ZLint as well as through ZCertificate, a more full-fledged command-line certificate parser that links against ZLint.

Example ZLint CLI usage:

go get github.com/zmap/zlint/cmd/zlint
echo "Lint mycert.pem with all applicable lints"
zlint mycert.pem

echo "Lint mycert.pem with just the two named lints"
zlint -includeNames=e_mp_exponent_cannot_be_one,e_mp_modulus_must_be_divisible_by_8 mycert.pem

echo "List available lint sources"
zlint -list-lints-source

echo "Lint mycert.pem with all of the lints except for ETSI ESI sourced lints"
zlint -excludeSources=ESTI_ESI mycert.pem

See zlint -h for all available command line options.

Library Usage

ZLint can also be used as a library. To lint a certificate with all applicable lints is as simple as using zlint.LintCertificate with a parsed certificate:

import (
	"github.com/zmap/zcrypto/x509"
	"github.com/zmap/zlint"
)

var certDER []byte = ...
parsed, _ := x509.ParseCertificate(certDER)
zlintResultSet := zlint.LintCertificate(parsed)

To lint a certificate with a subset of lints (e.g. based on lint source, or name) filter the global lint registry and use it with zlint.LintCertificateEx:

import (
	"github.com/zmap/zcrypto/x509"
	"github.com/zmap/zlint"
	"github.com/zmap/zlint/lint"
)

var certDER []byte = ...
parsed, _ := x509.ParseCertificate(certDER)

registry, _ := lint.GlobalRegistry().Filter(lint.FilterOptions{
  ExcludeSources: lint.ETSI_ESI,
})
zlintResultSet := zlint.LintCertificateEx(parsed, registry)

See the zlint command's source code for an example.

Extending ZLint

For information on extending ZLint with new lints see CONTRIBUTING.md

Zlint Users/Integrations

Pre-issuance linting is strongly recommended by the Mozilla root program. Here are some projects/CAs known to integrate with ZLint in some fashion:

• Camerfirma
• CFSSL
• Sectigo and crt.sh
• Digicert
• EJBCA
• Google Trust Services
• Government of Spain, FNMT
• Globalsign
• GoDaddy
• Izenpe
• Let's Encrypt and Boulder
• Siemens
• QuoVadis

Please submit a pull request to update the README if you are aware of another CA/project that uses zlint.

License and Copyright

ZMap Copyright 2020 Regents of the University of Michigan

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See LICENSE for the specific language governing permissions and limitations under the License.

Documentation

Index

• Constants
• type ResultSet
  • func LintCertificate(c *x509.Certificate) *ResultSet
  • func LintCertificateEx(c *x509.Certificate, registry lint.Registry) *ResultSet

Constants

const Version int64 = 3

Types

type ResultSet

type ResultSet struct {
	Version         int64                       `json:"version"`
	Timestamp       int64                       `json:"timestamp"`
	Results         map[string]*lint.LintResult `json:"lints"`
	NoticesPresent  bool                        `json:"notices_present"`
	WarningsPresent bool                        `json:"warnings_present"`
	ErrorsPresent   bool                        `json:"errors_present"`
	FatalsPresent   bool                        `json:"fatals_present"`
}

ResultSet contains the output of running all lints in a registry against a single certificate.

func LintCertificate

func LintCertificate(c *x509.Certificate) *ResultSet

LintCertificate runs all registered lints on c using default options, producing a ResultSet.

Using LintCertificate(c) is equivalent to calling LintCertificateEx(c, nil).

func LintCertificateEx

func LintCertificateEx(c *x509.Certificate, registry lint.Registry) *ResultSet

LintCertificateEx runs lints from the provided registry on c producing a ResultSet. Providing an explicit registry allows the caller to filter the lints that will be run. (See lint.Registry.Filter())

If registry is nil then the global registry of all lints is used and this function is equivalent to calling LintCertificate(c).