resources

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2020 License: MPL-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package resources provides types for representing and interacting with ACME protocol resources.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SaveAccount

func SaveAccount(path string, account *Account) error

SaveAccount persists the given Account object (which must not be nil) to the given file path. If any errors occur serializing the account it will be returned.

Types

type Account

type Account struct {
	// The server assigned Account ID. This is used for the JWS KeyID when
	// authenticating ACME requests using the Account's registered keypair.
	ID string
	// If not nil, a slice of one or more email addresses to be used as the ACME
	// Account's "mailto://" Contact addresses.
	Contact []string
	// A signer to use to sign protocol messages and to access the ACME account's
	// public key
	Signer crypto.Signer
	// If not nil, a slice of URLs for Order resources the Account created with
	// the ACME server.
	Orders []string
	// contains filtered or unexported fields
}

Account holds information related to a single ACME Account resource. If the account has an empty ID it has not yet been created server-side with the ACME server using the client.CreateAccount function.

The ID field holds the server assigned Account ID that is assigned at the time of account creation and used as the JWS KeyID for authenticating ACME requests with the Account's registered keypair.

The Contact field is either nil or a slice of one or more email addresses to be used as the ACME Account's "mailto://" Contact addresses.

The Signer field is a pointer to a private key used for the ACME account's keypair. The public component is computed from this private key automatically.

The Orders field is either nil or a slice of one or more Order resource URLs. These URLs correspond to Orders that the Account created with the ACME server.

For information about the Account resource see https://tools.ietf.org/html/rfc8555#section-7.1.2

func NewAccount

func NewAccount(emails []string, privKey crypto.Signer) (*Account, error)

NewAccount creates an ACME account in-memory. *Important:* the created Account is *not* registered with the ACME server until it is explicitly "created" server-side using a Client instance's CreateAccount function.

the emails argument is a slice of zero or more email addresses that should be used as the Account's Contact information.

the privKey argument is a crypto.Signer to that should be used for the Account keypair. It will be used to create JWS for requests when the Account is a Client's ActiveAccount. If the privKey argument is nil a new randomly generated ECDSA private key will be used for the Account key.

func RestoreAccount

func RestoreAccount(path string) (*Account, error)

RestoreAccount loads a previously saved Account object from the given file path. This file should have been created using SaveAccount in a previous session. If any errors occur deserializing an Account from the data in the provided filepath a nil Account instance and a non-nil error will be returned.

func (*Account) OrderURL

func (a *Account) OrderURL(i int) (string, error)

OrderURL returns the Order URL for the ith Order the Account owns. An error is returned if the Account has no Orders or if the index is out of bounds.

func (Account) Path

func (a Account) Path() string

func (Account) String

func (a Account) String() string

String returns the Account's ID or an empty string if it has not been created with the ACME server.

type Authorization

type Authorization struct {
	// The server-assigned ID (typically a URL) identifying the Authorization.
	ID string
	// The status of this authorization. Possible values are: “pending”, “valid”,
	// “invalid”, “deactivated”, “expired”, and “revoked”.
	// See:
	// https://tools.ietf.org/html/rfc8555#section-7.1.6
	Status string
	// The identifier that the account holding this Authorization is authorized to
	// represent
	Identifier Identifier
	// 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.
	Challenges []Challenge
	// A string representing a RFC 3339 date at which time the Authorization is
	// considered expired by the server.
	Expires string
	// For authorizations created as a result of a newOrder request containing
	// a DNS identifier with a value that contained a wildcard prefix this field
	// MUST be present, and true
	Wildcard bool
}

The ACME Authorization resource represents an Account's authorization to issue for a specified identifier, based on interactions with associated Challenges. Authorization for an identifier allows issuing certificates containing that identifier.

For information about the Authorization resource see https://tools.ietf.org/html/rfc8555#section-7.1.4

To understand the Authorization Status changes specified by ACME see https://tools.ietf.org/html/rfc8555#section-7.1.6

func (Authorization) String

func (a Authorization) String() string

String returns the Authorization's server-assigned ID.

type Challenge

type Challenge struct {
	// The Type of the challenge (expected values include "http-01", "dns-01", "tls-alpn-01")
	Type string
	// The URL/ID of the challenge (provided by the server in the associated
	// Authorization)
	//
	// TODO(@cpu): This should be renamed to ID for consistency with
	// Authorization, Order and Account.
	URL string
	// The Token used for constructing the challenge response for this challenge.
	Token string
	// The Status of the challenge.
	Status string
	// The Error associated with an invalid challenge
	Error *Problem `json:",omitempty"`
}

The ACME Challenge resource represents an action that the client must take to authorize a given account for a specific identifier in order to issue a certificate containing that identifier.

For information about the Challenge resource see https://tools.ietf.org/html/rfc8555#section-7.1.5

To understand the Challenge types specified by RFC 8555 see https://tools.ietf.org/html/rfc8555#section-8

To understand the Challenge Status changes specified by RFC 8555 see https://tools.ietf.org/html/rfc8555#section-7.1.6

func (Challenge) String

func (c Challenge) String() string

String returns the URL of the Challenge.

type Identifier

type Identifier struct {
	// The Type of the Identifier value.
	Type string
	// The Identifier value.
	Value string
}

The Identifier resource represents a subject identifier that can be included in a certificate.

See: https://tools.ietf.org/html/rfc8555#section-7.5 https://tools.ietf.org/html/rfc8555#section-9.7.7

In practice most ACME servers only support "DNS" type identifiers where the value specifies a fully qualified domain name.

A DNS type identifier that is used in a NewOrder request is allowed to contain a wildcard prefix (e.g. "*."). A DNS type identifier that is used in an Authorization resource is *not* allowed to contain a wildcard prefix and should instead have the Wildcard field of the Authorization set to true and the identifier value represented without the "*." prefix.

type Order

type Order struct {
	// The server-assigned ID (a URL) identifying the Order.
	ID string
	// The Status of the Order.
	Status string
	// The timestamp after which the server will consider this order invalid.
	Expires string
	// The Error associated with an invalid order
	Error *Problem `json:",omitempty"`
	// NotBefore and NotAfter are the requested values of the notBefore and
	// notAfter fields of the resulting certificate. Ignored by Boulder.
	NotBefore string
	NotAfter  string
	// The Identifiers the Order wishes to finalize a Certificate for once the
	// Order is ready.
	Identifiers []Identifier
	// A list of URLs for Authorization resources the server specifies for the
	// Order Identifiers.
	Authorizations []string
	// A URL used to Finalize the Order with a CSR once the Order has a status of
	// "ready".
	Finalize string
	// A URL used to fetch the Certificate issued by the server for the Order
	// after being Finalized. The Certificate field should be present and
	// not-empty when the Order has a status of "valid".
	Certificate string `json:",omitempty"`
}

The Order resource represents a collection of identifiers that an account wishes to create a Certificate for.

See https://tools.ietf.org/html/rfc8555#section-7.1.3

To understand the Status changes specified by RFC 8555 for the Order resource see https://tools.ietf.org/html/rfc8555#section-7.1.6

func (Order) String

func (o Order) String() string

String returns the Order's ID URL.

type Problem

type Problem struct {
	Type   string
	Detail string
	Status int
}

Problem is a struct representing a problem document from the server.

TODO(@cpu): implement RFC 8555 subproblem support

Jump to

Keyboard shortcuts

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