Documentation ¶
Index ¶
- Constants
- Variables
- func B64dec(x string) ([]byte, error)
- func B64enc(x []byte) string
- func Fingerprint256(data []byte) string
- func GetBuildHost() (retID string)
- func GetBuildID() (retID string)
- func GetBuildTime() (retID string)
- func GoodKey(key crypto.PublicKey, maxKeySize int) error
- func GoodKeyECDSA(key ecdsa.PublicKey, maxKeySize int) (err error)
- func GoodKeyRSA(key rsa.PublicKey, maxKeySize int) (err error)
- func KeyDigest(key crypto.PublicKey) (string, error)
- func KeyDigestEquals(j, k crypto.PublicKey) bool
- func NewToken() string
- func RandomString(byteLength int) string
- func SerialToString(serial *big.Int) string
- func StringToSerial(serial string) (*big.Int, error)
- func UniqueNames(names []string) (unique []string)
- func VerifyCSR(csr *x509.CertificateRequest) error
- type AcmeIdentifier
- type AcmeStatus
- type AcmeURL
- type Authorization
- type Buffer
- type CRL
- type Certificate
- type CertificateAuthority
- type CertificateAuthorityDatabase
- type CertificateIssuanceError
- type CertificateRequest
- type CertificateStatus
- type Challenge
- type DNSResolver
- type DNSResolverImpl
- func (dnsResolver *DNSResolverImpl) ExchangeOne(hostname string, qtype uint16) (rsp *dns.Msg, rtt time.Duration, err error)
- func (dnsResolver *DNSResolverImpl) LookupCAA(hostname string) ([]*dns.CAA, time.Duration, error)
- func (dnsResolver *DNSResolverImpl) LookupCNAME(hostname string) (string, time.Duration, error)
- func (dnsResolver *DNSResolverImpl) LookupDNAME(hostname string) (string, time.Duration, error)
- func (dnsResolver *DNSResolverImpl) LookupHost(hostname string) ([]net.IP, time.Duration, time.Duration, error)
- func (dnsResolver *DNSResolverImpl) LookupMX(hostname string) ([]string, time.Duration, error)
- func (dnsResolver *DNSResolverImpl) LookupTXT(hostname string) ([]string, time.Duration, error)
- type DeniedCSR
- type IdentifierType
- type InternalServerError
- type JSONBuffer
- type MalformedRequestError
- type NonceService
- type NotFoundError
- type NotSupportedError
- type OCSPResponse
- type OCSPSigningRequest
- type OCSPStatus
- type PolicyAuthority
- type ProblemDetails
- type ProblemType
- type Registration
- type RegistrationAuthority
- type SignatureValidationError
- type StorageAdder
- type StorageAuthority
- type StorageGetter
- type SyntaxError
- type UnauthorizedError
- type ValidationAuthority
- type WebFrontEnd
Constants ¶
const ( StatusUnknown = AcmeStatus("unknown") // Unknown status; the default StatusPending = AcmeStatus("pending") // In process; client has next action StatusProcessing = AcmeStatus("processing") // In process; server has next action StatusValid = AcmeStatus("valid") // Validation succeeded StatusInvalid = AcmeStatus("invalid") // Validation failed StatusRevoked = AcmeStatus("revoked") // Object no longer valid )
These statuses are the states of authorizations
const ( OCSPStatusGood = OCSPStatus("good") OCSPStatusRevoked = OCSPStatus("revoked") )
These status are the states of OCSP
const ( ConnectionProblem = ProblemType("urn:acme:error:connection") MalformedProblem = ProblemType("urn:acme:error:malformed") ServerInternalProblem = ProblemType("urn:acme:error:serverInternal") TLSProblem = ProblemType("urn:acme:error:tls") UnknownHostProblem = ProblemType("urn:acme:error:unknownHost") )
Error types that can be used in ACME payloads
const ( ChallengeTypeSimpleHTTP = "simpleHttp" ChallengeTypeDVSNI = "dvsni" ChallengeTypeDNS = "dns" ChallengeTypeRecoveryToken = "recoveryToken" )
These types are the available challenges
const (
IdentifierDNS = IdentifierType("dns")
)
These types are the available identification mechanisms
const MaxUsed = 65536
MaxUsed defines the maximum number of Nonces we're willing to hold in memory.
Variables ¶
var BuildHost string
BuildHost is set by the compiler and is used by GetBuildHost
var BuildID string
BuildID is set by the compiler (using -ldflags "-X core.BuildID $(git rev-parse --short HEAD)") and is used by GetBuildID
var BuildTime string
BuildTime is set by the compiler and is used by GetBuildTime
Functions ¶
func Fingerprint256 ¶
Fingerprint256 produces an unpadded, URL-safe Base64-encoded SHA256 digest of the data.
func GetBuildTime ¶
func GetBuildTime() (retID string)
GetBuildTime identifies when this build was made
func GoodKey ¶
GoodKey returns true iff the key is acceptable for both TLS use and account key use (our requirements are the same for either one), according to basic strength and algorithm checking. TODO: Support JsonWebKeys once go-jose migration is done.
func GoodKeyECDSA ¶
GoodKeyECDSA determines if an ECDSA pubkey meets our requirements
func GoodKeyRSA ¶
GoodKeyRSA determines if a RSA pubkey meets our requirements
func KeyDigest ¶
KeyDigest produces a padded, standard Base64-encoded SHA256 digest of a provided public key.
func KeyDigestEquals ¶
KeyDigestEquals determines whether two public keys have the same digest.
func RandomString ¶
RandomString returns a randomly generated string of the requested length.
func SerialToString ¶
SerialToString converts a certificate serial number (big.Int) to a String consistently.
func StringToSerial ¶
StringToSerial converts a string into a certificate serial number (big.Int) consistently.
func UniqueNames ¶
UniqueNames returns the set of all unique names in the input.
func VerifyCSR ¶
func VerifyCSR(csr *x509.CertificateRequest) error
VerifyCSR verifies that a Certificate Signature Request is well-formed.
Note: this is the missing CertificateRequest.Verify() method
Types ¶
type AcmeIdentifier ¶
type AcmeIdentifier struct { Type IdentifierType `json:"type"` // The type of identifier being encoded Value string `json:"value"` // The identifier itself }
An AcmeIdentifier encodes an identifier that can be validated by ACME. The protocol allows for different types of identifier to be supported (DNS names, IP addresses, etc.), but currently we only support domain names.
type AcmeURL ¶
AcmeURL is a URL that automatically marshal/unmarshal to JSON strings
func (AcmeURL) MarshalJSON ¶
MarshalJSON encodes an AcmeURL for transfer
func (AcmeURL) PathSegments ¶
PathSegments splits an AcmeURL into segments on the '/' characters
func (*AcmeURL) UnmarshalJSON ¶
UnmarshalJSON decodes an AcmeURL from transfer
type Authorization ¶
type Authorization struct { // An identifier for this authorization, unique across // authorizations and certificates within this instance. ID string `json:"id,omitempty" db:"id"` // The identifier for which authorization is being given Identifier AcmeIdentifier `json:"identifier,omitempty" db:"identifier"` // The registration ID associated with the authorization RegistrationID int64 `json:"regId,omitempty" db:"registrationID"` // The status of the validation of this authorization Status AcmeStatus `json:"status,omitempty" db:"status"` // The date after which this authorization will be no // longer be considered valid Expires *time.Time `json:"expires,omitempty" db:"expires"` // An array of challenges objects used to validate the // applicant's control of the identifier. For authorizations // in process, these are challenges to be fulfilled; for // final authorizations, they describe the evidence that // the server used in support of granting the authorization. Challenges []Challenge `json:"challenges,omitempty" db:"challenges"` // The server may suggest combinations of challenges if it // requires more than one challenge to be completed. Combinations [][]int `json:"combinations,omitempty" db:"combinations"` }
Authorization represents the authorization of an account key holder to act on behalf of a domain. This struct is intended to be used both internally and for JSON marshaling on the wire. Any fields that should be suppressed on the wire (e.g., ID, regID) must be made empty before marshaling.
type CRL ¶
type CRL struct { // serial: Same as certificate serial. Serial string `db:"serial"` // createdAt: The date the CRL was signed. CreatedAt time.Time `db:"createdAt"` // crl: The encoded and signed CRL. CRL string `db:"crl"` }
CRL is a large table of signed CRLs. This contains all historical CRLs we've signed, is append-only, and is likely to get quite large. It must be administratively truncated outside of Boulder.
type Certificate ¶
type Certificate struct { RegistrationID int64 `db:"registrationID"` // The revocation status of the certificate. // * "valid" - not revoked // * "revoked" - revoked Status AcmeStatus `db:"status"` Serial string `db:"serial"` Digest string `db:"digest"` DER []byte `db:"der"` Issued time.Time `db:"issued"` Expires time.Time `db:"expires"` }
Certificate objects are entirely internal to the server. The only thing exposed on the wire is the certificate itself.
func (Certificate) MatchesCSR ¶
func (cert Certificate) MatchesCSR(csr *x509.CertificateRequest, earliestExpiry time.Time) (err error)
MatchesCSR tests the contents of a generated certificate to make sure that the PublicKey, CommonName, and DNSNames match those provided in the CSR that was used to generate the certificate. It also checks the following fields for:
- notAfter is after earliestExpiry
- notBefore is not more than 24 hours ago
- BasicConstraintsValid is true
- IsCA is false
- ExtKeyUsage only contains ExtKeyUsageServerAuth & ExtKeyUsageClientAuth
- Subject only contains CommonName & Names
type CertificateAuthority ¶
type CertificateAuthority interface { // [RegistrationAuthority] IssueCertificate(x509.CertificateRequest, int64, time.Time) (Certificate, error) RevokeCertificate(string, int) error GenerateOCSP(OCSPSigningRequest) ([]byte, error) }
CertificateAuthority defines the public interface for the Boulder CA
type CertificateAuthorityDatabase ¶
type CertificateAuthorityDatabase interface { CreateTablesIfNotExists() error IncrementAndGetSerial(*gorp.Transaction) (int64, error) Begin() (*gorp.Transaction, error) }
CertificateAuthorityDatabase represents an atomic sequence source
type CertificateIssuanceError ¶
type CertificateIssuanceError string
CertificateIssuanceError indicates the certificate failed to be issued for some reason.
func (CertificateIssuanceError) Error ¶
func (e CertificateIssuanceError) Error() string
type CertificateRequest ¶
type CertificateRequest struct { CSR *x509.CertificateRequest // The CSR Authorizations []AcmeURL // Links to Authorization over the account key Bytes []byte // The original bytes of the CSR, for logging. }
CertificateRequest is just a CSR together with URIs pointing to authorizations that should collectively authorize the certificate being requsted.
This data is unmarshalled from JSON by way of rawCertificateRequest, which represents the actual structure received from the client.
func (CertificateRequest) MarshalJSON ¶
func (cr CertificateRequest) MarshalJSON() ([]byte, error)
MarshalJSON provides an implementation for encoding CertificateRequest objects.
func (*CertificateRequest) UnmarshalJSON ¶
func (cr *CertificateRequest) UnmarshalJSON(data []byte) error
UnmarshalJSON provides an implementation for decoding CertificateRequest objects.
type CertificateStatus ¶
type CertificateStatus struct { Serial string `db:"serial"` // subscriberApproved: true iff the subscriber has posted back to the server // that they accept the certificate, otherwise 0. SubscriberApproved bool `db:"subscriberApproved"` // status: 'good' or 'revoked'. Note that good, expired certificates remain // with status 'good' but don't necessarily get fresh OCSP responses. Status OCSPStatus `db:"status"` // ocspLastUpdated: The date and time of the last time we generated an OCSP // response. If we have never generated one, this has the zero value of // time.Time, i.e. Jan 1 1970. OCSPLastUpdated time.Time `db:"ocspLastUpdated"` // revokedDate: If status is 'revoked', this is the date and time it was // revoked. Otherwise it has the zero value of time.Time, i.e. Jan 1 1970. RevokedDate time.Time `db:"revokedDate"` // revokedReason: If status is 'revoked', this is the reason code for the // revocation. Otherwise it is zero (which happens to be the reason // code for 'unspecified'). RevokedReason int `db:"revokedReason"` LockCol int64 `json:"-"` }
CertificateStatus structs are internal to the server. They represent the latest data about the status of the certificate, required for OCSP updating and for validating that the subscriber has accepted the certificate.
type Challenge ¶
type Challenge struct { // The type of challenge Type string `json:"type"` // The status of this challenge Status AcmeStatus `json:"status,omitempty"` // Contains the error that occured during challenge validation, if any Error *ProblemDetails `json:"error,omitempty"` // If successful, the time at which this challenge // was completed by the server. Validated *time.Time `json:"validated,omitempty"` // A URI to which a response can be POSTed URI AcmeURL `json:"uri"` // Used by simpleHTTP, recoveryToken, and dns challenges Token string `json:"token,omitempty"` // Used by simpleHTTP challenges Path string `json:"path,omitempty"` TLS *bool `json:"tls,omitempty"` // Used by dvsni challenges R string `json:"r,omitempty"` S string `json:"s,omitempty"` Nonce string `json:"nonce,omitempty"` }
Challenge is an aggregate of all data needed for any challenges.
Rather than define individual types for different types of challenge, we just throw all the elements into one bucket, together with the common metadata elements.
func DvsniChallenge ¶
func DvsniChallenge() Challenge
DvsniChallenge constructs a random DVSNI challenge
func SimpleHTTPChallenge ¶
func SimpleHTTPChallenge() Challenge
SimpleHTTPChallenge constructs a random HTTP challenge
func (Challenge) IsSane ¶
IsSane checks the sanity of a challenge object before issued to the client (completed = false) and before validation (completed = true).
func (Challenge) MergeResponse ¶
MergeResponse copies a subset of client-provided data to the current Challenge. Note: This method does not update the challenge on the left side of the '.'
type DNSResolver ¶
type DNSResolver interface { ExchangeOne(string, uint16) (*dns.Msg, time.Duration, error) LookupTXT(string) ([]string, time.Duration, error) LookupHost(string) ([]net.IP, time.Duration, time.Duration, error) LookupCNAME(string) (string, time.Duration, error) LookupDNAME(string) (string, time.Duration, error) LookupCAA(string) ([]*dns.CAA, time.Duration, error) LookupMX(string) ([]string, time.Duration, error) }
DNSResolver defines methods used for DNS resolution
type DNSResolverImpl ¶
DNSResolverImpl represents a resolver system
func NewDNSResolverImpl ¶
func NewDNSResolverImpl(dialTimeout time.Duration, servers []string) *DNSResolverImpl
NewDNSResolverImpl constructs a new DNS resolver object that utilizes the provided list of DNS servers for resolution.
func (*DNSResolverImpl) ExchangeOne ¶
func (dnsResolver *DNSResolverImpl) ExchangeOne(hostname string, qtype uint16) (rsp *dns.Msg, rtt time.Duration, err error)
ExchangeOne performs a single DNS exchange with a randomly chosen server out of the server list, returning the response, time, and error (if any). This method sets the DNSSEC OK bit on the message to true before sending it to the resolver in case validation isn't the resolvers default behaviour.
func (*DNSResolverImpl) LookupCAA ¶
LookupCAA sends a DNS query to find all CAA records associated with the provided hostname. If the response code from the resolver is SERVFAIL an empty slice of CAA records is returned.
func (*DNSResolverImpl) LookupCNAME ¶
LookupCNAME returns the target name if a CNAME record exists for the given domain name. If the CNAME does not exist (NXDOMAIN, NXRRSET, or a successful response with no CNAME records), it returns the empty string and a nil error.
func (*DNSResolverImpl) LookupDNAME ¶
LookupDNAME is LookupCNAME, but for DNAME.
func (*DNSResolverImpl) LookupHost ¶
func (dnsResolver *DNSResolverImpl) LookupHost(hostname string) ([]net.IP, time.Duration, time.Duration, error)
LookupHost sends a DNS query to find all A/AAAA records associated with the provided hostname.
type IdentifierType ¶
type IdentifierType string
IdentifierType defines the available identification mechanisms for domains
type InternalServerError ¶
type InternalServerError string
InternalServerError indicates that something has gone wrong unrelated to the user's input, and will be considered by the Load Balancer as an indication that this Boulder instance may be malfunctioning. Minimally, returning this will cause an error page to be generated at the CDN/LB for the client. Consequently, you should only use this error when Boulder's internal constraints have been violated.
func (InternalServerError) Error ¶
func (e InternalServerError) Error() string
type JSONBuffer ¶
type JSONBuffer []byte
JSONBuffer fields get encoded and decoded JOSE-style, in base64url encoding with stripped padding.
func (JSONBuffer) MarshalJSON ¶
func (jb JSONBuffer) MarshalJSON() (result []byte, err error)
MarshalJSON encodes a JSONBuffer for transmission.
func (*JSONBuffer) UnmarshalJSON ¶
func (jb *JSONBuffer) UnmarshalJSON(data []byte) (err error)
UnmarshalJSON decodes a JSONBuffer to an object.
type MalformedRequestError ¶
type MalformedRequestError string
MalformedRequestError indicates the user data was improper
func (MalformedRequestError) Error ¶
func (e MalformedRequestError) Error() string
type NonceService ¶
type NonceService struct {
// contains filtered or unexported fields
}
NonceService generates, cancels, and tracks Nonces.
func NewNonceService ¶
func NewNonceService() (NonceService, error)
NewNonceService constructs a NonceService with defaults
func (*NonceService) Nonce ¶
func (ns *NonceService) Nonce() (string, error)
Nonce provides a new Nonce.
func (*NonceService) Valid ¶
func (ns *NonceService) Valid(nonce string) bool
Valid determines whether the provided Nonce string is valid, returning true if so.
type NotFoundError ¶
type NotFoundError string
NotFoundError indicates the destination was unknown. Whoa oh oh ohhh.
func (NotFoundError) Error ¶
func (e NotFoundError) Error() string
type NotSupportedError ¶
type NotSupportedError string
NotSupportedError indicates a method is not yet supported
func (NotSupportedError) Error ¶
func (e NotSupportedError) Error() string
type OCSPResponse ¶
type OCSPResponse struct { ID int `db:"id"` // serial: Same as certificate serial. Serial string `db:"serial"` // createdAt: The date the response was signed. CreatedAt time.Time `db:"createdAt"` // response: The encoded and signed CRL. Response []byte `db:"response"` }
OCSPResponse is a (large) table of OCSP responses. This contains all historical OCSP responses we've signed, is append-only, and is likely to get quite large. It must be administratively truncated outside of Boulder.
type OCSPSigningRequest ¶
OCSPSigningRequest is a transfer object representing an OCSP Signing Request
type PolicyAuthority ¶
type PolicyAuthority interface { WillingToIssue(AcmeIdentifier) error ChallengesFor(AcmeIdentifier) ([]Challenge, [][]int) }
PolicyAuthority defines the public interface for the Boulder PA
type ProblemDetails ¶
type ProblemDetails struct { Type ProblemType `json:"type,omitempty"` Detail string `json:"detail,omitempty"` }
ProblemDetails objects represent problem documents https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00
func (*ProblemDetails) Error ¶
func (pd *ProblemDetails) Error() string
type Registration ¶
type Registration struct { // Unique identifier ID int64 `json:"id" db:"id"` // Account key to which the details are attached Key jose.JsonWebKey `json:"key" db:"jwk"` // Recovery Token is used to prove connection to an earlier transaction RecoveryToken string `json:"recoveryToken" db:"recoveryToken"` // Contact URIs Contact []AcmeURL `json:"contact,omitempty" db:"contact"` // Agreement with terms of service Agreement string `json:"agreement,omitempty" db:"agreement"` LockCol int64 `json:"-"` }
Registration objects represent non-public metadata attached to account keys.
func (*Registration) MergeUpdate ¶
func (r *Registration) MergeUpdate(input Registration)
MergeUpdate copies a subset of information from the input Registration into this one.
type RegistrationAuthority ¶
type RegistrationAuthority interface { // [WebFrontEnd] NewRegistration(Registration) (Registration, error) // [WebFrontEnd] NewAuthorization(Authorization, int64) (Authorization, error) // [WebFrontEnd] NewCertificate(CertificateRequest, int64) (Certificate, error) // [WebFrontEnd] UpdateRegistration(Registration, Registration) (Registration, error) // [WebFrontEnd] UpdateAuthorization(Authorization, int, Challenge) (Authorization, error) // [WebFrontEnd] RevokeCertificate(x509.Certificate) error // [ValidationAuthority] OnValidationUpdate(Authorization) error }
RegistrationAuthority defines the public interface for the Boulder RA
type SignatureValidationError ¶
type SignatureValidationError string
SignatureValidationError indicates that the user's signature could not be verified, either through adversarial activity, or misconfiguration of the user client.
func (SignatureValidationError) Error ¶
func (e SignatureValidationError) Error() string
type StorageAdder ¶
type StorageAdder interface { NewRegistration(Registration) (Registration, error) UpdateRegistration(Registration) error NewPendingAuthorization(Authorization) (Authorization, error) UpdatePendingAuthorization(Authorization) error FinalizeAuthorization(Authorization) error MarkCertificateRevoked(serial string, ocspResponse []byte, reasonCode int) error UpdateOCSP(serial string, ocspResponse []byte) error AddCertificate([]byte, int64) (string, error) }
StorageAdder are the Boulder SA's write/update methods
type StorageAuthority ¶
type StorageAuthority interface { StorageGetter StorageAdder }
StorageAuthority interface represents a simple key/value store. It is divided into StorageGetter and StorageUpdater interfaces for privilege separation.
type StorageGetter ¶
type StorageGetter interface { GetRegistration(int64) (Registration, error) GetRegistrationByKey(jose.JsonWebKey) (Registration, error) GetAuthorization(string) (Authorization, error) GetCertificate(string) (Certificate, error) GetCertificateByShortSerial(string) (Certificate, error) GetCertificateStatus(string) (CertificateStatus, error) AlreadyDeniedCSR([]string) (bool, error) }
StorageGetter are the Boulder SA's read-only methods
type SyntaxError ¶
type SyntaxError string
SyntaxError indicates the user improperly formatted their data.
func (SyntaxError) Error ¶
func (e SyntaxError) Error() string
type UnauthorizedError ¶
type UnauthorizedError string
UnauthorizedError indicates the user did not satisfactorily prove identity
func (UnauthorizedError) Error ¶
func (e UnauthorizedError) Error() string
type ValidationAuthority ¶
type ValidationAuthority interface { // [RegistrationAuthority] UpdateValidations(Authorization, int) error CheckCAARecords(AcmeIdentifier) (bool, bool, error) }
ValidationAuthority defines the public interface for the Boulder VA
type WebFrontEnd ¶
type WebFrontEnd interface { // Set the base URL for authorizations SetAuthzBase(path string) // Set the base URL for certificates SetCertBase(path string) // This method represents the ACME new-registration resource NewRegistration(response http.ResponseWriter, request *http.Request) // This method represents the ACME new-authorization resource NewAuthz(response http.ResponseWriter, request *http.Request) // This method represents the ACME new-certificate resource NewCert(response http.ResponseWriter, request *http.Request) // Provide access to requests for registration resources Registration(response http.ResponseWriter, request *http.Request) // Provide access to requests for authorization resources Authz(response http.ResponseWriter, request *http.Request) // Provide access to requests for authorization resources Cert(response http.ResponseWriter, request *http.Request) }
A WebFrontEnd object supplies methods that can be hooked into the Go http module's server functions, principally http.HandleFunc()
It also provides methods to configure the base for authorization and certificate URLs.
It is assumed that the ACME server is laid out as follows: * One URL for new-authorization -> NewAuthz * One URL for new-certificate -> NewCert * One path for authorizations -> Authz * One path for certificates -> Cert