acme

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 24, 2023 License: MIT Imports: 4 Imported by: 2

Documentation

Overview

Package acme contains code shared between client and server of RFC8555

Index

Constants

This section is empty.

Variables

View Source
var (
	// ContentTypeDERCA is the Content-Type used when rendering
	// binary DER encoded CA Certificates
	ContentTypeDERCA = "application/x-x509-ca-cert"

	// ContentTypeJOSE is the ContentType used when rendering
	// JWS as flattened JSON
	ContentTypeJOSE = "application/jose+json"

	// ContentTypePEM is the ContentType used for PEM encoded files
	// informally before ACME
	ContentTypePEM = "application/x-pem-file"

	// ContentTypePEMCertChain is the ContentType used when rendering
	// PEM Certificate chains
	ContentTypePEMCertChain = "application/pem-certificate-chain"

	// ContentTypeProblem is the ContentType used when rendering a Problem
	ContentTypeProblem = "application/problem+json"
)

Functions

This section is empty.

Types

type Account

type Account[EAB any] struct {
	// Status indicates the status of this account
	Status AccountStatus `json:"status"`

	// Contact is an optional array of URLs that the server can use to
	// contact the client for issues related to this account.  For
	// example, the server may wish to notify the client about
	// server-initiated revocation or certificate expiration.
	// For information on supported URL schemes, see
	// https://www.rfc-editor.org/rfc/rfc8555#section-7.3.
	Contact []string `json:"contact,omitempty" validate:"url"`

	// TermsOfServiceAgreed optionally indicates in a newAccount request
	// the client's agreement with the terms of service.
	// This field cannot be updated by the client.
	TermsOfServiceAgreed bool `json:"termsOfServiceAgreed,omitempty"`

	// ExternalAccountBinding is an optional field in a newAccount request
	// indicating approval by the holder of an existing
	// non-ACME account to bind that account to this ACME account.
	// This field is not updateable by the client, see
	// https://www.rfc-editor.org/rfc/rfc8555#section-7.3.4
	ExternalAccountBinding *json.RawMessage `json:"externalAccountBinding,omitempty"`

	// Orders is a URL from which a list of orders
	// submitted by this account can be fetched via a POST-as-GET
	// request, as described in
	// https://www.rfc-editor.org/rfc/rfc8555#section-7.1.2.1
	Orders string `json:"orders" validate:"url"`
}

Account represents a set of metadata associated with an ACME account on the server (§7.1.2)

func (*Account[EAB]) GetExternalAccountBinding

func (*Account[EAB]) GetExternalAccountBinding() (EAB, bool)

GetExternalAccountBinding retrieves ExternalAccountBinding

func (*Account[EAB]) SetExternalAccountBinding

func (*Account[EAB]) SetExternalAccountBinding(_ EAB)

SetExternalAccountBinding stores ExternalAccountBinding

type AccountStatus

type AccountStatus string

AccountStatus indicates the status of an account. See §7.1.6

const (
	// AccountValid indicates the account is valid
	AccountValid AccountStatus = "valid"
	// AccountDeactivated indicates client-initiated deactivation
	AccountDeactivated AccountStatus = "deactivated"
	// AccountRevoked indicates server-initiated deactivation
	AccountRevoked AccountStatus = "revoked"
)

type Authorization

type Authorization struct {
	// Identifier that the account is authorized to represent
	Identifier Identifier `json:"identifier"`
	// Status of the authorization
	Status AuthorizationStatus `json:"status"`
	// Expires indicates the timestamp after which the server
	// will consider this authorization invalid.
	// This field is REQUIRED for objects with "valid" status
	Expires Timestamp `json:"expires,omitempty"`
	// Challenges is an array of Challenge objects.
	//
	// - For pending authorizations, the challenges that the client
	//   can fulfill in order to prove possession of the identifier.
	// - For valid authorizations, the challenge that was validated.
	// - For invalid authorizations, the challenge that was attempted
	//   and failed.
	//
	// Each array entry is an object with parameters required to
	// validate the challenge.  A client should attempt to fulfill
	// one of these challenges, and a server should consider any one
	// of the challenges sufficient to make the authorization valid.
	Challenges []Challenge `json:"challenges"`

	// Wildcard indicates the authorization was created as a result
	// of a newOrder request containing a DNS identifier with a value
	// that was a wildcard domain name.
	Wildcard bool `json:"wildcard,omitempty"`
}

An Authorization object represents a server's authorization for an account to represent an identifier. (§7.1.4)

type AuthorizationStatus

type AuthorizationStatus string

AuthorizationStatus represents the status of an Authorization

const (
	// AuthorizationPending is the initial state after creation
	AuthorizationPending AuthorizationStatus = "pending"
	// AuthorizationValid indicates at least one challenge transitioned
	// to ChallengeValid
	AuthorizationValid AuthorizationStatus = "valid"
	// AuthorizationInvalid indicates the client attempted to fulfill a
	// challenge and failed, or there was an error while the authorization
	// was still pending.
	AuthorizationInvalid AuthorizationStatus = "invalid"
	// AuthorizationExpired indicates a valid Authorization has expired
	AuthorizationExpired AuthorizationStatus = "expired"
	// AuthorizationDeactivated indicates a valid Authorization has been
	// deactivated by the client
	AuthorizationDeactivated AuthorizationStatus = "deactivated"
	// AuthorizationRevoked indicates a valid Authorization has been
	// revoked by the server
	AuthorizationRevoked AuthorizationStatus = "revoked"
)

type Challenge

type Challenge any

A Challenge object represents a server's offer to validate a client's possession of an identifier in a specific way. Unlike the other objects listed above, there is not a single standard structure for a challenge object. The contents of a challenge object depend on the validation method being used. The general structure of challenge objects and an initial set of validation methods are described in §8

type ChallengeState

type ChallengeState string

ChallengeState indicates the status of a Challenge (§7.1.6)

const (
	// ChallengePending is the initial state of a Challenge
	// once it's created
	ChallengePending ChallengeState = "pending"
	// ChallengeProcessing is the state after ChallengePending
	// when the client responds to the challenge ([§7.1.5])
	//
	// [§7.1.5]: https://www.rfc-editor.org/rfc/rfc8555#section-7.1.5
	ChallengeProcessing ChallengeState = "processing"
	// ChallengeValid indicates the validation was successful
	ChallengeValid ChallengeState = "valid"
	// ChallengeInvalid indicates there was an error on the validation
	ChallengeInvalid ChallengeState = "invalid"
)

type Directory

type Directory struct {
	NewNonce   string         `json:"newNonce"`
	NewAccount string         `json:"newAccount"`
	NewOrder   string         `json:"newOrder"`
	NewAuthz   string         `json:"newAuthz,omitempty"`
	RevokeCert string         `json:"revokeCert"`
	KeyChange  string         `json:"keyChange"`
	Meta       *DirectoryMeta `json:"meta,omitempty"`
}

Directory is the index of ACME resources on a server (§7.1.1).

There is no constraint on the URL of the directory except that it should be different from the other ACME server resources' URLs, and that it should not clash with other services. For instance:

  • a host that functions as both an ACME and a Web server may want to keep the root path "/" for an HTML "front page" and place the ACME directory under the path "/acme".

  • a host that only functions as an ACME server could place the directory under the path "/".

If the ACME server does not implement pre-authorization (§7.4.1) it MUST omit the "newAuthz" field of the directory.

type DirectoryMeta

type DirectoryMeta struct {
	// TermsOfService is a URL identifying the current terms of service.
	TermsOfService string `json:"termsOfService,omitempty"`

	// Website is an HTTP or HTTPS URL locating a website
	// providing more information about the ACME server.
	Website string `json:"website,omitempty"`

	// CAAIdentities indicates hostnames that the
	// ACME server recognizes as referring to itself for the purposes of
	// CAA record validation as defined in [RFC6844].  Each string MUST
	// represent the same sequence of ASCII code points that the server
	// will expect to see as the "Issuer Domain Name" in a CAA issue or
	// issuewild property tag.  This allows clients to determine the
	// correct issuer domain name to use when configuring CAA records.
	CAAIdentities []string `json:"caaIdentities,omitempty"`

	// ExternalAccountRequired indicates if the CA requires that all
	// newAccount requests include an "externalAccountBinding" field
	// associating the new account with an external account.
	ExternalAccountRequired bool `json:"externalAccountRequired,omitempty"`
}

DirectoryMeta is an optional field of Directory that provides additional information about the ACME server

type ErrorType

type ErrorType string

ErrorType is a type of error defined by §6.7

const (
	// ErrorAccountDoesNotExist indicates the request specified an
	// account that does not exist
	ErrorAccountDoesNotExist ErrorType = "accountDoesNotExist"

	// ErrorAlreadyRevoked indicates the request specified a
	// certificate to be revoked that has already been revoked
	ErrorAlreadyRevoked ErrorType = "alreadyRevoked"

	// ErrorBadCSR indicates the CSR is unacceptable
	// (e.g., due to a short key)
	ErrorBadCSR ErrorType = "badCSR"

	// ErrorBadNonce indicates the client sent an unacceptable
	// anti-replay nonce
	ErrorBadNonce ErrorType = "badNonce"

	// ErrorBadPublicKey indicates the JWS was signed by a public key
	// the server does not support
	ErrorBadPublicKey ErrorType = "badPublicKey"

	// ErrorBadRevocationReason indicates the revocation reason provided
	// is not allowed by the server
	ErrorBadRevocationReason ErrorType = "badRevocationReason"

	// ErrorBadSignatureAlgorithm indicates the JWS was signed with an
	// algorithm the server does not support
	ErrorBadSignatureAlgorithm ErrorType = "badSignatureAlgorithm"

	// ErrorCAA indicates Certification Authority Authorization (CAA)
	// records forbid the CA from issuing a certificate
	ErrorCAA ErrorType = "caa"

	// ErrorCompound indicates specific error conditions are indicated
	// in the "subproblems" array
	ErrorCompound ErrorType = "compound"

	// ErrorConnection indicates the server could not connect to
	// the validation target
	ErrorConnection ErrorType = "connection"

	// ErrorDNS indicates there was a problem with a DNS query during
	// identifier validation
	ErrorDNS ErrorType = "dns"

	// ErrorExternalAccountRequired indicates the request must include
	// a value for the "externalAccountBinding" field
	ErrorExternalAccountRequired ErrorType = "externalAccountRequired"

	// ErrorIncorrectResponse indicates the response received didn't
	// match the challenge's requirements
	ErrorIncorrectResponse ErrorType = "incorrectResponse"

	// ErrorInvalidContact indicates a contact URL for an account was invalid
	ErrorInvalidContact ErrorType = "invalidContact"

	// ErrorMalformed indicates the request message was malformed
	ErrorMalformed ErrorType = "malformed"

	// ErrorOrderNotReady indicates the request attempted to finalize an order
	// that is not ready to be finalized
	ErrorOrderNotReady ErrorType = "orderNotReady"

	// ErrorRateLimited indicates the request exceeds a rate limit
	ErrorRateLimited ErrorType = "rateLimited"

	// ErrorRejectedIdentifier indicates the server will not issue certificates
	// for the identifier
	ErrorRejectedIdentifier ErrorType = "rejectedIdentifier"

	// ErrorServerInternal indicates the server experienced an internal error
	ErrorServerInternal ErrorType = "serverInternal"

	// ErrorTLS the server received a TLS error during validation
	ErrorTLS ErrorType = "tls"

	// ErrorUnauthorized indicates the client lacks sufficient authorization
	ErrorUnauthorized ErrorType = "unauthorized"

	// ErrorUnsupportedContact indicates a contact URL for an account used
	// an unsupported protocol scheme
	ErrorUnsupportedContact ErrorType = "unsupportedContact"

	// ErrorUnsupportedIdentifier indicates an identifier is of an unsupported
	// type
	ErrorUnsupportedIdentifier ErrorType = "unsupportedIdentifier"

	// ErrorUserActionRequired indicates visit the "instance" URL and take actions
	// specified there
	ErrorUserActionRequired ErrorType = "userActionRequired"
)

func (ErrorType) String

func (e ErrorType) String() string

String renders an error type

type Identifier

type Identifier struct {
	// Type indicates the type of identifier
	Type IdentifierType `json:"type"`
	// Value indicates the identifier itself
	Value string `json:"value"`
}

Identifier is an entity the account is authorized to represent

type IdentifierType

type IdentifierType string

IdentifierType indicates the type of identifier that is present in ACME authorization objects (§9.7.7).

const (
	// IdentifierDNS defined by [RFC8555] for fully
	// qualified domain names.
	//
	// [RFC8555]: https://www.rfc-editor.org/rfc/rfc8555
	IdentifierDNS IdentifierType = "dns"
)

type Order

type Order struct {
	// Status indicates the status of this order
	Status OrderStatus `json:"status"`

	// Expires indicates the timestamp after which the server
	// will consider this order invalid
	Expires Timestamp `json:"expires,omitempty"`

	// Identifiers is an array of identifier objects that the
	// order pertains to
	Identifiers []Identifier `json:"identifiers"`

	// NotBefore is the requested notBefore value in the
	// certificate
	NotBefore Timestamp `json:"notBefore,omitempty"`

	// NotAfter is the requested notAfter value in the
	// certificate
	NotAfter Timestamp `json:"notAfter,omitempty"`

	// Error indicates a problem that occurred while processing
	// the order
	Error Problem `json:"error,omitempty"`

	// Authorizations is the array of authorizations
	// associated to this Order. For pending orders, the
	// authorizations that the client needs to complete before the
	// requested certificate can be issued (see Section 7.5), including
	// unexpired authorizations that the client has completed in the past
	// for identifiers specified in the order.  The authorizations
	// required are dictated by server policy; there may not be a 1:1
	// relationship between the order identifiers and the authorizations
	// required.  For final orders (in the "valid" or "invalid" state),
	// the authorizations that were completed.  Each entry is a URL from
	// which an authorization can be fetched with a POST-as-GET request.
	Authorizations []Authorization `json:"authorizations"`

	// Finalize is a URL that a CSR must be POSTed to once
	// all of the order's authorizations are satisfied to finalize the
	// order.  The result of a successful finalization will be the
	// population of the certificate URL for the order.
	Finalize string `json:"finalize" validate:"url"`

	// Certificate is a URL for the certificate that has
	// been issued in response to this order.
	Certificate string `json:"certificate" validate:"url"`
}

An Order represents a client's request for a certificate and is used to track the progress of that order through to issuance. Thus, the object contains information about the requested certificate, the authorizations that the server requires the client to complete, and any certificates that have resulted from this order. (§7.1.3)

type OrderStatus

type OrderStatus string

OrderStatus indicates the status of an order (§7.1.6)

const (
	// OrderPending is the initial state of an Order
	OrderPending OrderStatus = "pending"
	// OrderReady indicates all authorizations listed in the
	// Order are in AuthorizationValid state
	OrderReady OrderStatus = "ready"
	// OrderProcessing indicates the client has submitted the
	// CSR to the finalize URL and the CA begins the issuance process
	// for the certificate
	OrderProcessing OrderStatus = "processing"
	// OrderValid indicates the certificate has been issued
	OrderValid OrderStatus = "valid"
	// OrderInvalid indicates if it expires or one of its
	// authorizations enters a final state other than "valid"
	// ("expired", "revoked", or "deactivated")
	OrderInvalid OrderStatus = "invalid"
)

type Orders

type Orders struct {
	Orders []string `json:"orders,omitempty" validate:"url"`
}

Orders is a list of orders belonging to the account. The server SHOULD include pending orders and SHOULD NOT include orders that are invalid in the array of URLs. The server MAY return an incomplete list, along with a Link header field with a "next" link relation indicating where further entries can be acquired. (§7.1.2.1)

type Problem

type Problem struct {
	// Type is a URI that identifies the problem type
	Type ErrorType `json:"type" validate:"uri"`

	// Status is the HTTP status code generated by the server
	// for this occurrence of the problem.
	Status int `json:"status,omitempty"`

	// Detail is a human-readable explanation specific to this
	// occurrence of the problem
	Detail string `json:"detail,omitempty"`

	// Instance is a URI reference that identifies the specific
	// occurrence of the problem.
	Instance string `json:"instance,omitempty" validate:"uri"`

	// Subproblems is an optional slice of particular problems.
	// Subproblems need not all have the same type, and they
	// do not need to match the top level type.
	Subproblems []Problem `json:"subproblems,omitempty"`

	// Identifier refers to the cause of the Problem.
	// The "identifier" field MUST NOT be present at the top
	// level in ACME problem documents.  It can only be
	// present in subproblems.
	Identifier Identifier `json:"identifier,omitempty"`
}

Problem is an error that occurred while processing a request, if any. This field is structured as a problem document RFC7807

func (Problem) Error

func (p Problem) Error() string

Error returns the type and details of the Problem

func (Problem) Errors

func (p Problem) Errors() []error

Errors returns the list of subproblems

type Timestamp

type Timestamp time.Time

Timestamp renders in the format defined in [RFC3339]

func (Timestamp) String

func (ts Timestamp) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL