Documentation ¶
Index ¶
- Variables
- func NewRegistry() *registryImpl
- func RegisterCertificateLint(l *CertificateLint)
- func RegisterLint(l *Lint)
- func RegisterProfile(profile Profile)
- func RegisterRevocationListLint(l *RevocationListLint)
- type AppleRootStorePolicyConfig
- type CABFBaselineRequirementsConfig
- type CABFEVGuidelinesConfig
- type CertificateLint
- type CertificateLintInterface
- type CertificateLinterLookup
- type CommunityConfig
- type Configurable
- type Configuration
- type EtsiEsiConfig
- type FilterOptions
- type Global
- type GlobalConfiguration
- type Lint
- type LintInterface
- type LintMetadata
- type LintResult
- type LintSource
- type LintStatus
- type MozillaRootStorePolicyConfig
- type Profile
- type RFC5280Config
- type RFC5480Config
- type RFC5891Config
- type Registry
- type RevocationListLint
- type RevocationListLintInterface
- type RevocationListLinterLookup
- type SourceList
Constants ¶
This section is empty.
Variables ¶
var ( // StatusLabelToLintStatus is used to work backwards from // a LintStatus.String() to the LintStatus. This is used by // LintStatus.Unmarshal. StatusLabelToLintStatus = map[string]LintStatus{ Reserved.String(): Reserved, NA.String(): NA, NE.String(): NE, Pass.String(): Pass, Notice.String(): Notice, Warn.String(): Warn, Error.String(): Error, Fatal.String(): Fatal, } )
Functions ¶
func NewRegistry ¶
func NewRegistry() *registryImpl
NewRegistry constructs a Registry implementation that can be used to register lints.
func RegisterCertificateLint ¶ added in v3.5.0
func RegisterCertificateLint(l *CertificateLint)
RegisterCertificateLint must be called once for each CertificateLint to be executed. Normally, RegisterCertificateLint is called from the Go init() function of a lint implementation.
IMPORTANT: RegisterCertificateLint will panic if given a nil lint, or a lint with a nil Lint pointer, or if the lint name matches a previously registered lint's name. These conditions all indicate a bug that should be addressed by a developer.
func RegisterLint ¶
func RegisterLint(l *Lint)
RegisterLint must be called once for each lint to be executed. Normally, RegisterLint is called from the Go init() function of a lint implementation.
IMPORTANT: RegisterLint will panic if given a nil lint, or a lint with a nil Lint pointer, or if the lint name matches a previously registered lint's name. These conditions all indicate a bug that should be addressed by a developer.
@deprecated - use RegisterCertificateLint instead.
func RegisterProfile ¶ added in v3.5.0
func RegisterProfile(profile Profile)
RegisterProfile registered the provided profile into the global profile mapping.
func RegisterRevocationListLint ¶ added in v3.5.0
func RegisterRevocationListLint(l *RevocationListLint)
RegisterRevocationListLint must be called once for each RevocationListLint to be executed. Normally, RegisterRevocationListLint is called from the Go init() function of a lint implementation.
IMPORTANT: RegisterRevocationListLint will panic if given a nil lint, or a lint with a nil Lint pointer, or if the lint name matches a previously registered lint's name. These conditions all indicate a bug that should be addressed by a developer.
Types ¶
type AppleRootStorePolicyConfig ¶ added in v3.4.0
type AppleRootStorePolicyConfig struct{}
AppleRootStorePolicyConfig is the higher scoped configuration which services as the deserialization target for...
AppleRootStorePolicyConfig ... ...
type CABFBaselineRequirementsConfig ¶ added in v3.4.0
type CABFBaselineRequirementsConfig struct{}
CABFBaselineRequirementsConfig is the higher scoped configuration which services as the deserialization target for...
CABFBaselineRequirementsConfig ... ...
type CABFEVGuidelinesConfig ¶ added in v3.4.0
type CABFEVGuidelinesConfig struct{}
CABFEVGuidelinesConfig is the higher scoped configuration which services as the deserialization target for...
CABFEVGuidelinesConfig ... ...
type CertificateLint ¶ added in v3.5.0
type CertificateLint struct { // Metadata associated with the linter. LintMetadata // A constructor which returns the implementation of the linter. Lint func() CertificateLintInterface `json:"-"` }
CertificateLint represents a single x509 certificate linter.
func (*CertificateLint) CheckEffective ¶ added in v3.5.0
func (l *CertificateLint) CheckEffective(c *x509.Certificate) bool
CheckEffective returns true if c was issued on or after the EffectiveDate AND before (but not on) the Ineffective date. That is, CheckEffective returns true if...
c.NotBefore in [EffectiveDate, IneffectiveDate)
If EffectiveDate is zero, then only IneffectiveDate is checked. Conversely, if IneffectiveDate is zero then only EffectiveDate is checked. If both EffectiveDate and IneffectiveDate are zero then CheckEffective always returns true.
func (*CertificateLint) Execute ¶ added in v3.5.0
func (l *CertificateLint) Execute(cert *x509.Certificate, config Configuration) *LintResult
Execute runs the lint against a certificate. For lints that are sourced from the CA/B Forum Baseline Requirements, we first determine if they are within the purview of the BRs. See CertificateLintInterface for details about the other methods called. The ordering is as follows:
Configure() ----> only if the lint implements Configurable CheckApplies() CheckEffective() Execute()
type CertificateLintInterface ¶ added in v3.5.0
type CertificateLintInterface interface { // CheckApplies runs once per certificate. It returns true if the Lint should // run on the given certificate. If CheckApplies returns false, the Lint // result is automatically set to NA without calling CheckEffective() or // Run(). CheckApplies(c *x509.Certificate) bool // Execute is the body of the lint. It is called for every certificate for // which CheckApplies returns true. Execute(c *x509.Certificate) *LintResult }
CertificateLintInterface is implemented by each certificate linter.
type CertificateLinterLookup ¶ added in v3.5.0
type CertificateLinterLookup interface { // ByName returns a pointer to the registered lint with the given name, or nil // if there is no such lint registered in the registry. ByName(name string) *CertificateLint // BySource returns a list of registered lints that have the same LintSource as // provided (or nil if there were no such lints in the registry). BySource(s LintSource) []*CertificateLint // Lints returns a list of all the lints registered. Lints() []*CertificateLint // contains filtered or unexported methods }
CertificateLinterLookup is an interface describing how registered certificate lints can be looked up.
type CommunityConfig ¶ added in v3.4.0
type CommunityConfig struct{}
CommunityConfig is the higher scoped configuration which services as the deserialization target for...
CommunityConfig ... ...
type Configurable ¶ added in v3.4.0
type Configurable interface {
Configure() interface{}
}
Configurable lints return a pointer into a struct that they wish to receive their configuration into.
type Configuration ¶ added in v3.4.0
type Configuration struct {
// contains filtered or unexported fields
}
Configuration is a ZLint configuration which serves as a target to hold the full TOML tree that is a physical ZLint configuration./
func NewConfig ¶ added in v3.4.0
func NewConfig(r io.Reader) (Configuration, error)
NewConfig attempts to instantiate a configuration by consuming the contents of the provided reader.
The contents of the provided reader MUST be in a valid TOML format. The caller of this function is responsible for closing the reader, if appropriate.
func NewConfigFromFile ¶ added in v3.4.0
func NewConfigFromFile(path string) (Configuration, error)
NewConfigFromFile attempts to instantiate a configuration from the provided filesystem path.
The file pointed to by `path` MUST be valid TOML file. If `path` is the empty string then an empty configuration is returned.
func NewConfigFromString ¶ added in v3.4.0
func NewConfigFromString(config string) (Configuration, error)
NewConfigFromString attempts to instantiate a configuration from the provided string.
The provided string MUST be in a valid TOML format.
func NewEmptyConfig ¶ added in v3.4.0
func NewEmptyConfig() Configuration
NewEmptyConfig returns a configuration that is backed by an entirely empty TOML tree.
This is useful if no particular configuration is set at all by the user of ZLint as any attempt to resolve a namespace in `deserializeConfigInto` fails and thus results in all defaults for all lints being maintained.
func (Configuration) Configure ¶ added in v3.4.0
func (c Configuration) Configure(lint interface{}, namespace string) error
Configure attempts to deserialize the provided namespace into the provided empty interface.
For example, let's say that the name of your lint is MyLint, then the configuration file might look something like the following...
```
[MyLint] A = 1 B = 2
```
Given this, our target struct may look like the following...
```
type MytLint struct { A int B uint }
```
So deserializing into this struct would look like...
``` configuration.Configure(&myLint, myLint.Name()) ```
func (Configuration) MaybeConfigure ¶ added in v3.5.0
func (c Configuration) MaybeConfigure(lint interface{}, namespace string) error
MaybeConfigure is a thin wrapper over Configure.
If the provided lint object does not implement the Configurable interface then this function is a noop and nil is always returned.
Otherwise, configuration of the provided lint is attempted.
type EtsiEsiConfig ¶ added in v3.4.0
type EtsiEsiConfig struct{}
EtsiEsiConfig is the higher scoped configuration which services as the deserialization target for...
EtsiEsiConfig ... ...
type FilterOptions ¶
type FilterOptions struct { // NameFilter is a regexp used to filter lints by their name. It is mutually // exclusive with IncludeNames and ExcludeNames. NameFilter *regexp.Regexp // IncludeNames is a case sensitive list of lint names to include in the // registry being filtered. IncludeNames []string // ExcludeNames is a case sensitive list of lint names to exclude from the // registry being filtered. ExcludeNames []string // IncludeSource is a SourceList of LintSource's to be included in the // registry being filtered. IncludeSources SourceList // ExcludeSources is a SourceList of LintSources's to be excluded in the // registry being filtered. ExcludeSources SourceList }
FilterOptions is a struct used by Registry.Filter to create a sub registry containing only lints that meet the filter options specified.
Source based exclusion/inclusion is evaluated before Lint name based exclusion/inclusion. In both cases exclusion is processed before inclusion.
Only one of NameFilter or IncludeNames/ExcludeNames can be provided at a time.
func (*FilterOptions) AddProfile ¶ added in v3.5.0
func (f *FilterOptions) AddProfile(profile Profile)
AddProfile takes in a Profile and appends all Profile.LintNames into FilterOptions.IncludeNames.
func (FilterOptions) Empty ¶
func (f FilterOptions) Empty() bool
Empty returns true if the FilterOptions is empty and does not specify any elements to filter by.
type Global ¶ added in v3.4.0
type Global struct{}
Global is what one would intuitive think of as being the global context of the configuration file. That is, given the following configuration...
some_flag = true some_string = "the greatest song in the world"
[e_some_lint] some_other_flag = false
The fields `some_flag` and `some_string` will be targeted to land into this struct.
type GlobalConfiguration ¶ added in v3.4.0
type GlobalConfiguration interface {
// contains filtered or unexported methods
}
GlobalConfiguration acts both as an interface that can be used to obtain the TOML namespace of configuration as well as a way to mark a fielf in a struct as one of our own, higher scoped, configurations.
the interface itself is public, however the singular `namespace` method is package private, meaning that normal lint struct cannot accidentally implement this.
type Lint ¶
type Lint struct { // Name is a lowercase underscore-separated string describing what a given // Lint checks. If Name beings with "w", the lint MUST NOT return Error, only // Warn. If Name beings with "e", the Lint MUST NOT return Warn, only Error. Name string `json:"name,omitempty"` // A human-readable description of what the Lint checks. Usually copied // directly from the CA/B Baseline Requirements or RFC 5280. Description string `json:"description,omitempty"` // The source of the check, e.g. "BRs: 6.1.6" or "RFC 5280: 4.1.2.6". Citation string `json:"citation,omitempty"` // Programmatic source of the check, BRs, RFC5280, or ZLint Source LintSource `json:"source"` // Lints automatically returns NE for all certificates where CheckApplies() is // true but with NotBefore < EffectiveDate. This check is bypassed if // EffectiveDate is zero. Please see CheckEffective for more information. EffectiveDate time.Time `json:"-"` // Lints automatically returns NE for all certificates where CheckApplies() is // true but with NotBefore >= IneffectiveDate. This check is bypassed if // IneffectiveDate is zero. Please see CheckEffective for more information. IneffectiveDate time.Time `json:"-"` // A constructor which returns the implementation of the lint logic. Lint func() LintInterface `json:"-"` }
A Lint struct represents a single lint, e.g. "e_basic_constraints_not_critical". It contains an implementation of LintInterface.
@deprecated - use CertificateLint instead.
func (*Lint) CheckEffective ¶
func (l *Lint) CheckEffective(c *x509.Certificate) bool
CheckEffective returns true if c was issued on or after the EffectiveDate AND before (but not on) the Ineffective date. That is, CheckEffective returns true if...
c.NotBefore in [EffectiveDate, IneffectiveDate)
If EffectiveDate is zero, then only IneffectiveDate is checked. Conversely, if IneffectiveDate is zero then only EffectiveDate is checked. If both EffectiveDate and IneffectiveDate are zero then CheckEffective always returns true.
@deprecated - use CertificateLint instead.
func (*Lint) Execute ¶
func (l *Lint) Execute(cert *x509.Certificate, config Configuration) *LintResult
Execute runs the lint against a certificate. For lints that are sourced from the CA/B Forum Baseline Requirements, we first determine if they are within the purview of the BRs. See LintInterface for details about the other methods called. The ordering is as follows:
Configure() ----> only if the lint implements Configurable CheckApplies() CheckEffective() Execute()
@deprecated - use CertificateLint instead
type LintInterface ¶
type LintInterface = CertificateLintInterface
LintInterface is implemented by each certificate linter.
@deprecated - use CertificateLintInterface instead.
type LintMetadata ¶ added in v3.5.0
type LintMetadata struct { // Name is a lowercase underscore-separated string describing what a given // Lint checks. If Name beings with "w", the lint MUST NOT return Error, only // Warn. If Name beings with "e", the Lint MUST NOT return Warn, only Error. Name string `json:"name,omitempty"` // A human-readable description of what the Lint checks. Usually copied // directly from the CA/B Baseline Requirements or RFC 5280. Description string `json:"description,omitempty"` // The source of the check, e.g. "BRs: 6.1.6" or "RFC 5280: 4.1.2.6". Citation string `json:"citation,omitempty"` // Programmatic source of the check, BRs, RFC5280, or ZLint Source LintSource `json:"source"` // Lints automatically returns NE for all certificates where CheckApplies() is // true but with NotBefore < EffectiveDate. This check is bypassed if // EffectiveDate is zero. Please see CheckEffective for more information. EffectiveDate time.Time `json:"-"` // Lints automatically returns NE for all certificates where CheckApplies() is // true but with NotBefore >= IneffectiveDate. This check is bypassed if // IneffectiveDate is zero. Please see CheckEffective for more information. IneffectiveDate time.Time `json:"-"` }
LintMetadata represents the metadata that are broadly associated across all types of lints.
That is, all lints (irrespective of being a certificate lint, a CRL lint, and OCSP, etc.) have a Name, a Description, a Citation, and so on.
In this way, this struct may be embedded in any linting type in order to maintain this data, while each individual linting type provides the behavior over this data.
type LintResult ¶
type LintResult struct { Status LintStatus `json:"result"` Details string `json:"details,omitempty"` LintMetadata LintMetadata `json:"-"` }
LintResult contains a LintStatus, and an optional human-readable description. The output of a lint is a LintResult.
type LintSource ¶
type LintSource string
LintSource is a type representing a known lint source that lints cite requirements from.
const ( UnknownLintSource LintSource = "Unknown" RFC3279 LintSource = "RFC3279" RFC5280 LintSource = "RFC5280" RFC5480 LintSource = "RFC5480" RFC5891 LintSource = "RFC5891" RFC6962 LintSource = "RFC6962" RFC8813 LintSource = "RFC8813" CABFBaselineRequirements LintSource = "CABF_BR" CABFCSBaselineRequirements LintSource = "CABF_CS_BR" CABFSMIMEBaselineRequirements LintSource = "CABF_SMIME_BR" CABFEVGuidelines LintSource = "CABF_EV" MozillaRootStorePolicy LintSource = "Mozilla" AppleRootStorePolicy LintSource = "Apple" Community LintSource = "Community" EtsiEsi LintSource = "ETSI_ESI" )
func (*LintSource) FromString ¶
func (s *LintSource) FromString(src string)
FromString sets the LintSource value based on the source string provided (case sensitive). If the src string does not match any of the known LintSource's then s is set to the UnknownLintSource.
func (*LintSource) UnmarshalJSON ¶
func (s *LintSource) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the json.Unmarshaler interface. It ensures that the unmarshaled value is a known LintSource.
type LintStatus ¶
type LintStatus int
LintStatus is an enum returned by lints inside of a LintResult.
const ( // Unused / unset LintStatus Reserved LintStatus = 0 // Not Applicable NA LintStatus = 1 // Not Effective NE LintStatus = 2 Pass LintStatus = 3 Notice LintStatus = 4 Warn LintStatus = 5 Error LintStatus = 6 Fatal LintStatus = 7 )
Known LintStatus values
func (LintStatus) MarshalJSON ¶
func (e LintStatus) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (LintStatus) String ¶
func (e LintStatus) String() string
String returns the canonical representation of a LintStatus as a string.
func (*LintStatus) UnmarshalJSON ¶
func (e *LintStatus) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
type MozillaRootStorePolicyConfig ¶ added in v3.4.0
type MozillaRootStorePolicyConfig struct{}
MozillaRootStorePolicyConfig is the higher scoped configuration which services as the deserialization target for...
MozillaRootStorePolicyConfig ... ...
type Profile ¶ added in v3.5.0
type Profile struct { // Name is a lowercase underscore-separated string describing what a given // profile aggregates. Name string `json:"name"` // A human-readable description of what the Profile checks. Usually copied // directly from the CA/B Baseline Requirements, RFC 5280, or other published // document. Description string `json:"description,omitempty"` // The source of the check, e.g. "BRs: 6.1.6" or "RFC 5280: 4.1.2.6". Citation string `json:"citation,omitempty"` // Programmatic source of the check, BRs, RFC5280, or ZLint Source LintSource `json:"source,omitempty"` // The names of the lints that compromise this profile. These names // MUST be the exact same found within Lint.Name. LintNames []string `json:"lints"` }
func AllProfiles ¶ added in v3.5.0
func AllProfiles() []Profile
AllProfiles returns a slice of all Profiles currently registered globally.
func GetProfile ¶ added in v3.5.0
GetProfile returns the Profile for which the provided name matches Profile.Name. If no such Profile exists then the `ok` returns false, else true.
type RFC5280Config ¶ added in v3.4.0
type RFC5280Config struct{}
RFC5280Config is the higher scoped configuration which services as the deserialization target for...
RFC5280Config ... ...
type RFC5480Config ¶ added in v3.4.0
type RFC5480Config struct{}
RFC5480Config is the higher scoped configuration which services as the deserialization target for...
RFC5480Config ... ...
type RFC5891Config ¶ added in v3.4.0
type RFC5891Config struct{}
RFC5891Config is the higher scoped configuration which services as the deserialization target for...
RFC5891Config ... ...
type Registry ¶
type Registry interface { // Names returns a list of all of the lint names that have been registered // in string sorted order. Names() []string // Sources returns a SourceList of registered LintSources. The list is not // sorted but can be sorted by the caller with sort.Sort() if required. Sources() SourceList // @TODO DefaultConfiguration() ([]byte, error) // ByName returns a pointer to the registered lint with the given name, or nil // if there is no such lint registered in the registry. // // @deprecated - use CertificateLints instead. ByName(name string) *Lint // BySource returns a list of registered lints that have the same LintSource as // provided (or nil if there were no such lints in the registry). // // @deprecated - use CertificateLints instead. BySource(s LintSource) []*Lint // Filter returns a new Registry containing only lints that match the // FilterOptions criteria. Filter(opts FilterOptions) (Registry, error) // WriteJSON writes a description of each registered lint as // a JSON object, one object per line, to the provided writer. WriteJSON(w io.Writer) SetConfiguration(config Configuration) GetConfiguration() Configuration // CertificateLints returns an interface used to lookup CertificateLints. CertificateLints() CertificateLinterLookup // RevocationListLitns returns an interface used to lookup RevocationListLints. RevocationListLints() RevocationListLinterLookup }
Registry is an interface describing a collection of registered lints. A Registry instance can be given to zlint.LintCertificateEx() to control what lints are run for a given certificate.
Typically users will interact with the global Registry returned by GlobalRegistry(), or a filtered Registry created by applying FilterOptions to the GlobalRegistry()'s Filter function.
func GlobalRegistry ¶
func GlobalRegistry() Registry
GlobalRegistry is the Registry used by RegisterLint and contains all of the lints that are loaded.
If you want to run only a subset of the globally registered lints use GloablRegistry().Filter with FilterOptions to create a filtered Registry.
type RevocationListLint ¶ added in v3.5.0
type RevocationListLint struct { // Metadata associated with the linter. LintMetadata // A constructor which returns the implementation of the linter. Lint func() RevocationListLintInterface `json:"-"` }
RevocationListLint represents a single x509 CRL linter.
func (*RevocationListLint) CheckEffective ¶ added in v3.5.0
func (l *RevocationListLint) CheckEffective(r *x509.RevocationList) bool
CheckEffective returns true if r was generated on or after the EffectiveDate AND before (but not on) the Ineffective date. That is, CheckEffective returns true if...
r.ThisUpdate in [EffectiveDate, IneffectiveDate)
If EffectiveDate is zero, then only IneffectiveDate is checked. Conversely, if IneffectiveDate is zero then only EffectiveDate is checked. If both EffectiveDate and IneffectiveDate are zero then CheckEffective always returns true.
func (*RevocationListLint) Execute ¶ added in v3.5.0
func (l *RevocationListLint) Execute(r *x509.RevocationList, config Configuration) *LintResult
Execute runs the lint against a revocation list. The ordering is as follows:
Configure() ----> only if the lint implements Configurable CheckApplies() CheckEffective() Execute()
type RevocationListLintInterface ¶ added in v3.5.0
type RevocationListLintInterface interface { // CheckApplies runs once per revocation list. It returns true if the // Lint should run on the given certificate. If CheckApplies returns // false, the Lint result is automatically set to NA without calling // CheckEffective() or Run(). CheckApplies(r *x509.RevocationList) bool // Execute is the body of the lint. It is called for every revocation list // for which CheckApplies returns true. Execute(r *x509.RevocationList) *LintResult }
RevocationListLintInterface is implemented by each revocation list linter.
type RevocationListLinterLookup ¶ added in v3.5.0
type RevocationListLinterLookup interface { // ByName returns a pointer to the registered lint with the given name, or nil // if there is no such lint registered in the registry. ByName(name string) *RevocationListLint // BySource returns a list of registered lints that have the same LintSource as // provided (or nil if there were no such lints in the registry). BySource(s LintSource) []*RevocationListLint // Lints returns a list of all the lints registered. Lints() []*RevocationListLint // contains filtered or unexported methods }
RevocationListLinterLookup is an interface describing how registered revocation list lints can be looked up.
type SourceList ¶
type SourceList []LintSource
SourceList is a slice of LintSources that can be sorted.
func (*SourceList) FromString ¶
func (l *SourceList) FromString(raw string) error
FromString populates a SourceList (replacing any existing content) with the comma separated list of sources provided in raw. If any of the comma separated values are not known LintSource's an error is returned.
func (SourceList) Less ¶
func (l SourceList) Less(i, j int) bool
Less compares the LintSources at index i and j lexicographically.
func (SourceList) Swap ¶
func (l SourceList) Swap(i, j int)
Swap swaps the LintSource at index i and j in the list.