zerossl

README

ZeroSSL API client

This package implements the ZeroSSL REST API in Go.

The REST API is distinct from the ACME endpoint, which is a standardized way of obtaining certificates.

Documentation

Overview

Package zerossl implements the ZeroSSL REST API. See the API documentation on the ZeroSSL website: https://zerossl.com/documentation/api/

Index

• Constants
• type APIError
  • func (ae APIError) Error() string
• type CNAMEValidationError
• type CertificateBundle
• type CertificateList
• type CertificateObject
• type Client
  • func (c Client) CancelCertificate(ctx context.Context, certificateID string) error
  • func (c Client) CreateCertificate(ctx context.Context, csr *x509.CertificateRequest, validityDays int) (CertificateObject, error)
  • func (c Client) DownloadCertificate(ctx context.Context, certificateID string, includeCrossSigned bool) (CertificateBundle, error)
  • func (c Client) DownloadCertificateFile(ctx context.Context, certificateID string, includeCrossSigned bool, ...) error
  • func (c Client) GenerateEABCredentials(ctx context.Context) (keyID, hmacKey string, err error)
  • func (c Client) GetCertificate(ctx context.Context, certificateID string) (CertificateObject, error)
  • func (c Client) ListCertificates(ctx context.Context, params ListCertificatesParameters) (CertificateList, error)
  • func (c Client) ResendVerificationEmail(ctx context.Context, certificateID string) error
  • func (c Client) RevokeCertificate(ctx context.Context, certificateID string, reason RevocationReason) error
  • func (c Client) ValidateCSR(ctx context.Context, csrASN1DER []byte) error
  • func (c Client) VerificationStatus(ctx context.Context, certificateID string) (ValidationStatus, error)
  • func (c Client) VerifyIdentifiers(ctx context.Context, certificateID string, method VerificationMethod, ...) (CertificateObject, error)
• type HTTPValidationError
• type ListCertificatesParameters
  • func ListAllCertificates() ListCertificatesParameters
• type RevocationReason
• type ValidationError
• type ValidationObject
• type ValidationStatus
• type VerificationMethod

Constants

const BaseURL = "https://api.zerossl.com"

The base URL to the ZeroSSL API.

Types

type APIError

type APIError struct {
	Success   anyBool `json:"success"`
	ErrorInfo struct {
		Code int    `json:"code"`
		Type string `json:"type"`

		// for domain verification only; each domain is grouped into its
		// www and non-www variant for CNAME validation, or its URL
		// for HTTP validation
		Details map[string]map[string]ValidationError `json:"details"`
	} `json:"error"`
}

func (APIError) Error

func (ae APIError) Error() string

type CNAMEValidationError

type CNAMEValidationError struct {
	CNAMEFound    int    `json:"cname_found"`
	RecordCorrect int    `json:"record_correct"`
	TargetHost    string `json:"target_host"`
	TargetRecord  string `json:"target_record"`
	ActualRecord  string `json:"actual_record"`
}

type CertificateBundle

type CertificateBundle struct {
	CertificateCrt string `json:"certificate.crt"`
	CABundleCrt    string `json:"ca_bundle.crt"`
}

type CertificateList

type CertificateList struct {
	TotalCount     int                 `json:"total_count"`
	ResultCount    int                 `json:"result_count"`
	Page           string              `json:"page"` // don't ask me why this is a string
	Limit          int                 `json:"limit"`
	ACMEUsageLevel string              `json:"acmeUsageLevel"`
	ACMELocked     bool                `json:"acmeLocked"`
	Results        []CertificateObject `json:"results"`
}

type CertificateObject

type CertificateObject struct {
	ID                string  `json:"id"` // "certificate hash"
	Type              string  `json:"type"`
	CommonName        string  `json:"common_name"`
	AdditionalDomains string  `json:"additional_domains"`
	Created           string  `json:"created"`
	Expires           string  `json:"expires"`
	Status            string  `json:"status"`
	ValidationType    *string `json:"validation_type,omitempty"`
	ValidationEmails  *string `json:"validation_emails,omitempty"`
	ReplacementFor    string  `json:"replacement_for,omitempty"`
	FingerprintSHA1   *string `json:"fingerprint_sha1"`
	BrandValidation   any     `json:"brand_validation"`
	Validation        *struct {
		EmailValidation map[string][]string         `json:"email_validation,omitempty"`
		OtherMethods    map[string]ValidationObject `json:"other_methods,omitempty"`
	} `json:"validation,omitempty"`
}

type Client

type Client struct {
	// REQUIRED: Your ZeroSSL account access key.
	AccessKey string `json:"access_key"`

	// Optionally adjust the base URL of the API.
	// Default: https://api.zerossl.com
	BaseURL string `json:"base_url,omitempty"`

	// Optionally configure a custom HTTP client.
	HTTPClient *http.Client `json:"-"`
}

Client acts as a ZeroSSL API client. It facilitates ZeroSSL certificate operations.

func (Client) CancelCertificate

func (c Client) CancelCertificate(ctx context.Context, certificateID string) error

CancelCertificate cancels a certificate that has not been issued yet (is in draft or pending_validation state).

func (Client) CreateCertificate

func (c Client) CreateCertificate(ctx context.Context, csr *x509.CertificateRequest, validityDays int) (CertificateObject, error)

CreateCertificate creates a certificate. After creating a certificate, its identifiers must be verified before the certificate can be downloaded. The CSR must have been fully created using x509.CreateCertificateRequest (its Raw field must be filled out).

func (Client) DownloadCertificate

func (c Client) DownloadCertificate(ctx context.Context, certificateID string, includeCrossSigned bool) (CertificateBundle, error)

func (Client) DownloadCertificateFile

func (c Client) DownloadCertificateFile(ctx context.Context, certificateID string, includeCrossSigned bool, output io.Writer) error

DownloadCertificateFile writes the certificate bundle as a zip file to the provided output writer.

func (Client) GenerateEABCredentials

func (c Client) GenerateEABCredentials(ctx context.Context) (keyID, hmacKey string, err error)

func (Client) GetCertificate

func (c Client) GetCertificate(ctx context.Context, certificateID string) (CertificateObject, error)

func (Client) ListCertificates

func (c Client) ListCertificates(ctx context.Context, params ListCertificatesParameters) (CertificateList, error)

func (Client) ResendVerificationEmail

func (c Client) ResendVerificationEmail(ctx context.Context, certificateID string) error

func (Client) RevokeCertificate

func (c Client) RevokeCertificate(ctx context.Context, certificateID string, reason RevocationReason) error

Only revoke a certificate if the private key is compromised, the certificate was a mistake, or the identifiers are no longer in use. Do not revoke a certificate when renewing it.

func (Client) ValidateCSR

func (c Client) ValidateCSR(ctx context.Context, csrASN1DER []byte) error

ValidateCSR sends the CSR to ZeroSSL for validation. Pass in the ASN.1 DER-encoded bytes; this is found in x509.CertificateRequest.Raw after calling x5p9.CreateCertificateRequest.

func (Client) VerificationStatus

func (c Client) VerificationStatus(ctx context.Context, certificateID string) (ValidationStatus, error)

func (Client) VerifyIdentifiers

func (c Client) VerifyIdentifiers(ctx context.Context, certificateID string, method VerificationMethod, emails []string) (CertificateObject, error)

VerifyIdentifiers tells ZeroSSL that you are ready to prove control over your domain/IP using the method specified. The credentials from CreateCertificate must be used to verify identifiers. At least one email is required if using email verification method.

type HTTPValidationError

type HTTPValidationError struct {
	FileFound int    `json:"file_found"`
	Error     bool   `json:"error"`
	ErrorSlug string `json:"error_slug"`
	ErrorInfo string `json:"error_info"`
}

type ListCertificatesParameters

type ListCertificatesParameters struct {
	// Return certificates with this status.
	Status string

	// Return these types of certificates.
	Type string

	// The CommonName or SAN.
	Search string

	// The page number. Default: 1
	Page int

	// How many per page. Default: 100
	Limit int
}

ListCertificateParameters specifies how to search or list certificates on the account. An empty set of parameters will return no results.

func ListAllCertificates

func ListAllCertificates() ListCertificatesParameters

ListAllCertificates returns parameters that lists all the certificates on the account; be sure to set Page and Limit if paginating.

type RevocationReason

type RevocationReason string

RevocationReason represents various reasons for revoking a certificate.

const (
	UnspecifiedReason    RevocationReason = "unspecified"          // default
	KeyCompromise        RevocationReason = "keyCompromise"        // lost control of private key
	AffiliationChanged   RevocationReason = "affiliationChanged"   // identify information changed
	Superseded           RevocationReason = "Superseded"           // certificate replaced -- do not revoke for this reason, however
	CessationOfOperation RevocationReason = "cessationOfOperation" // domains are no longer in use
)

type ValidationError

type ValidationError struct {
	CNAMEValidationError
	HTTPValidationError
}

type ValidationObject

type ValidationObject struct {
	FileValidationURLHTTP  string   `json:"file_validation_url_http"`
	FileValidationURLHTTPS string   `json:"file_validation_url_https"`
	FileValidationContent  []string `json:"file_validation_content"`
	CnameValidationP1      string   `json:"cname_validation_p1"`
	CnameValidationP2      string   `json:"cname_validation_p2"`
}

type ValidationStatus

type ValidationStatus struct {
	ValidationCompleted int `json:"validation_completed"`
	Details             map[string]struct {
		Method string `json:"method"`
		Status string `json:"status"`
	} `json:"details"`
}

type VerificationMethod

type VerificationMethod string

VerificationMethod represents a way of verifying identifiers with ZeroSSL.

const (
	EmailVerification VerificationMethod = "EMAIL"
	CNAMEVerification VerificationMethod = "CNAME_CSR_HASH"
	HTTPVerification  VerificationMethod = "HTTP_CSR_HASH"
	HTTPSVerification VerificationMethod = "HTTPS_CSR_HASH"
)

Verification methods.