cert-payload

Support for encoding and decoding certificate metadata payloads associated with the check_cert plugin from the atc0005/check-cert project.

Table of contents

• Overview
• Status
• Contributions
• Features
• Additional notes
• Changelog
• Examples
  • Imports
  • Encoding a payload
  • Decoding a payload
• License
• Used by
• References

Overview

This library provides support and functionality for encoding and decoding certificate metadata payloads in JSON format.

Using this library, the check_cert plugin (from the atc0005/check-cert project) creates fixed format version payloads. Those payloads (using a different library), are embedded in monitoring plugin output where they can later be extracted and decoded and then unmarshalled back into a specific format version of a native Go type provided by this project.

This library exists to allow the check_cert plugin (and other client code) to easily generate certificate metadata payloads and various other tools to unpack them for analysis, reporting and actionable/automation purposes.

Status

While attempts are made to provide stability, this codebase is subject to change without notice and may break client code that depends on it. You are encouraged to vendor this package if you find it useful until such time that the API is considered stable. You are also encouraged to only use tagged (non-alpha/beta) releases for the same reason.

The specific certificate metadata payload format versions provided by this project are intended to be supported indefinitely once the format is declared stable. Any breaking changes to a format would be provided by releasing a new format version with those changes.

Warning

format0 is an unstable/development format version used for testing changes in behavior prior to potentially including them in a later stable format version. You are encouraged to use a stable format version (e.g., 1) instead of using this version.

Top-level library constants are provided which identity the oldest and newest stable format versions along with separate constants which identify the oldest and newest format versions regardless of stability expectations. See those constants for more information.

Contributions

This library has a very narrow focus. While PRs may be accepted to resolve typos, logic errors and enhance documentation, behavioral changes and feature additions will likely be rejected as out of scope. If there is any doubt, please open a new discussion and ask for feedback.

Features

• support for generating a JSON payload from a specified metadata payload format version
  • this can be generated by calling the Encode function from a specific format version or by calling the top-level Encode function and specifying a valid format version number (e.g., 0 or 1)
• support for decoding a given (valid) certificate metadata payload
  • the intent is to support decoding any given payload matching the set of supported format versions (e.g., 0, 1)
  • the caller provides an instance of a specific format version of the certificate metadata payload and the Decode function for that format version is used
  • once a format version is stable, the intent is to support creating and decoding it using this library indefinitely
    • this should allow the sysadmin using the check_cert plugin to specify what version of the payload format they wish to create
    • this should allow the sysadmin using a reporting tool to consume a certificate metadata payload generated by the check_cert plugin in the same fixed version as the one they asked the check_cert plugin to create
    • this process should continue to work as-is until the sysadmin decides to explicitly change the certificate metadata payload format version they're working with; updating this dependency should not break payload generation or consumption

Additional notes

For additional details, please see the formats.md doc file for design notes and potential future feature implementation work. See also GH-46 for initial implementation notes and related GH issues.

Changelog

See the CHANGELOG.md file for the changes associated with each release of this application. Changes that have been merged to master, but not yet an official release may also be noted in the file under the Unreleased section. A helpful link to the Git commit history since the last official release is also provided for further review.

Examples

Imports

Add this line to your imports like so:

package main

import (
  "fmt"
  "log"
  "os"

  payload "github.com/atc0005/cert-payload"
)

and pull in a specific version of this library that you'd like to use.

go get github.com/atc0005/cert-payload@v0.1.0

Alternatively, you can use the latest stable tag available to get started:

go get github.com/atc0005/cert-payload@latest

See https://pkg.go.dev/github.com/atc0005/cert-payload for specific examples.

See https://pkg.go.dev/github.com/atc0005/cert-payload?tab=importedby for projects that are using this library.

Encoding a payload

See the check_cert monitoring plugin from the atc0005/check-cert project for an example of how a certificate metadata payload is generated and embedded within plugin output (for later retrieval and parsing).

Decoding a payload

See the Nagios XI API example in this repo for how to combine the use of this library with the atc0005/go-nagios library to extract, decode and unmarshal an embedded payload to a specific format version of a certificate metadata payload.

License

From the LICENSE file:

MIT License

Copyright (c) 2024 Adam Chalkley

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Used by

See the Known importers lists below for a dynamically updated list of projects using either this library or the original project.

• Known importers (pkg.go.dev)

References

• https://github.com/atc0005/go-nagios
• https://github.com/atc0005/check-cert

See also the Used by section for projects known to be using this package. Please report any additional projects that we've missed!