hvclient

package module
v0.0.0-...-567c364 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2023 License: MIT Imports: 27 Imported by: 0

README

hvclient

GoDoc Build Status

Package hvclient provides an interface to the GlobalSign Atlas Certificate Management API.

Installation

go get github.com/globalsign/hvclient

The cmd/hvclient directory contains a command line interface utility.

Quickstart Guide

Basic usage is straightforward:

  1. Create a Client object

  2. Use it to make HVCA API calls.

Creating a Client object requires:

  1. An API key and API secret provided by GlobalSign during account set-up; and

  2. A private key and a certificate to use for mutual TLS authentication with the HVCA server. The private key should be the one associated with the public key that was provided to GlobalSign during account set-up, and the certificate should be the one provided by GlobalSign along with the API key and API secret.

The Client object may be created with either:

  1. A configuration file, useful when the account credentials are located in files; or with

  2. A Config object, useful when the account credentials are obtained programmatically from a secrets vault, from environment variables, or in some other manner.

Configuration file

An example configuration file:

{
    "url": "https://emea.api.hvca.globalsign.com:8443/v2",
    "api_key": "<your_api_key>",
    "api_secret": "<your_api_secret>",
    "cert_file": "testdata/mtls_cert.pem",
    "key_file": "testdata/mtls_private_key.pem",
    "key_passphrase": "strongpassword",
    "insecure_skip_verify": false,
    "extra_headers": [
        "Header-Name-One": "value",
        "Header-Name-Two": "value"
    ],
    "timeout": 60
}
  • key_passphrase must be provided if the mTLS private key is an encrypted PEM block as specified in RFC 1423.
  • insecure_skip_verify controls whether the client verifies the server's certificate chain and host name. If true, any certificate presented by the server and any host name in that certificate is accepted. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing.
  • extra_headers are optional additional HTTP headers to include in the requests to the server.
  • timeout specifies a request timeout in seconds.

Demo

asciicast

Documentation

Overview

Package hvclient provides an interface for making HVCA API calls.

Index

Constants

View Source
const (
	RevocationReasonUnspecified          = RevocationReason("unspecified")
	RevocationReasonAffiliationChanged   = RevocationReason("affiliationChanged")
	RevocationReasonKeyCompromise        = RevocationReason("keyCompromise")
	RevocationReasonSuperseded           = RevocationReason("superseded")
	RevocationReasonCessationOfOperation = RevocationReason("cessationOfOperation")
	RevocationReasonPrivilegeWithdrawn   = RevocationReason("privilegeWithdrawn")
)

Revocation reasons to provide when revoking a certificate and providing a reason for its revocation.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode  int
	Description string
}

APIError is an error returned by the HVCA HTTP API.

func NewAPIError

func NewAPIError(r *http.Response) APIError

NewAPIError creates a new APIError object from an HTTP response.

func (APIError) Error

func (e APIError) Error() string

Error returns a string representation of the error.

type AlgorithmPolicy

type AlgorithmPolicy struct {
	Presence Presence `json:"presence"`
	List     []string `json:"list"`
}

AlgorithmPolicy is a list of algorithm names and their presence value entry in a validation policy.

type AuthorisedEmails

type AuthorisedEmails struct {
	Constructed []string   `json:"constructed"`
	DNS         DNSResults `json:"DNS"`
}

AuthorisedEmails represents the body of a request returned when retrieving emails used for verifying DNS records

type CertInfo

type CertInfo struct {
	PEM       string            // The PEM-encoded certificate
	X509      *x509.Certificate // The parsed certificate
	Status    CertStatus        // Issued or revoked
	UpdatedAt time.Time         // When the certificate was last updated
}

CertInfo contains a certificate and associated information.

func (CertInfo) Equal

func (s CertInfo) Equal(other CertInfo) bool

Equal checks if two certificate metadata objects are equivalent.

func (CertInfo) MarshalJSON

func (s CertInfo) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of certificate metadata.

func (*CertInfo) UnmarshalJSON

func (s *CertInfo) UnmarshalJSON(b []byte) error

UnmarshalJSON parses JSON-encoded certificate metadata and stores the result in the object.

type CertMeta

type CertMeta struct {
	SerialNumber *big.Int  // Certificate serial number
	NotBefore    time.Time // Certificate not valid before this time
	NotAfter     time.Time // Certificate not valid after this time
}

CertMeta contains certificate metadata.

func (CertMeta) Equal

func (c CertMeta) Equal(other CertMeta) bool

Equal checks if two certificate metadata objects are equivalent.

func (CertMeta) MarshalJSON

func (c CertMeta) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a certificate metadata object.

func (*CertMeta) UnmarshalJSON

func (c *CertMeta) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded certificate metadata object and stores the result in the object.

type CertStatus

type CertStatus int

CertStatus is the issued/revoked status of a certificate.

const (
	StatusIssued CertStatus = iota + 1
	StatusRevoked
)

Certificate status values.

func (CertStatus) MarshalJSON

func (s CertStatus) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a certificate status value.

func (CertStatus) String

func (s CertStatus) String() string

String returns a description of the certificate status.

func (*CertStatus) UnmarshalJSON

func (s *CertStatus) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded certificate status value and stores the result in the object.

type Claim

type Claim struct {
	ID                     string
	Status                 ClaimStatus
	Token                  string
	Domain                 string
	CreatedAt              time.Time
	ExpiresAt              time.Time
	AssertBy               time.Time
	LastVerifiedAt         time.Time
	LastVerificationMethod string
	Log                    []ClaimLogEntry
}

Claim is a domain claim.

func (Claim) Equal

func (c Claim) Equal(other Claim) bool

Equal checks if two domain claims are equivalent.

func (Claim) MarshalJSON

func (c Claim) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a domain claim and stores the result in the object.

func (*Claim) UnmarshalJSON

func (c *Claim) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded domain claim and stores the result in the object.

type ClaimAssertionInfo

type ClaimAssertionInfo struct {
	Token    string
	AssertBy time.Time
	ID       string
}

ClaimAssertionInfo contains information for making a domain claim.

func (ClaimAssertionInfo) Equal

Equal checks if two domain claim assertion info objects are equivalent.

func (ClaimAssertionInfo) MarshalJSON

func (c ClaimAssertionInfo) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a domain claim assertion info object.

func (*ClaimAssertionInfo) UnmarshalJSON

func (c *ClaimAssertionInfo) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded domain claim assertion info object and stores the result in the object.

type ClaimLogEntry

type ClaimLogEntry struct {
	Status      ClaimLogEntryStatus
	Description string
	TimeStamp   time.Time
}

ClaimLogEntry is a domain claim verification log entry.

func (ClaimLogEntry) Equal

func (l ClaimLogEntry) Equal(other ClaimLogEntry) bool

Equal checks if two domain claim verification log entries are equivalent.

func (ClaimLogEntry) MarshalJSON

func (l ClaimLogEntry) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a domain claim verification log entry.

func (*ClaimLogEntry) UnmarshalJSON

func (l *ClaimLogEntry) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded domain claim verification log entry and stores the result in the object.

type ClaimLogEntryStatus

type ClaimLogEntryStatus int

ClaimLogEntryStatus is the success/error status of a domain claim verification log entry.

const (
	VerificationSuccess ClaimLogEntryStatus = iota + 1
	VerificationError
	VerificationInfo
)

Claim log entry status constants.

func (ClaimLogEntryStatus) MarshalJSON

func (s ClaimLogEntryStatus) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a domain claim verification log entry status value.

func (ClaimLogEntryStatus) String

func (s ClaimLogEntryStatus) String() string

String returns a description of the claim status.

func (*ClaimLogEntryStatus) UnmarshalJSON

func (s *ClaimLogEntryStatus) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded domain claim verification log entry status value and stores the result in the object.

type ClaimStatus

type ClaimStatus int

ClaimStatus is the pending/verified status of a domain claim.

const (
	StatusPending ClaimStatus = iota + 1
	StatusVerified
)

Domain claim status constants.

func (ClaimStatus) MarshalJSON

func (s ClaimStatus) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a claim status value.

func (ClaimStatus) String

func (s ClaimStatus) String() string

String returns a description of the claim status.

func (*ClaimStatus) UnmarshalJSON

func (s *ClaimStatus) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded claim status value and stores the result in the object.

type Client

type Client struct {
	BaseURL       *url.URL
	HTTPClient    *http.Client
	Config        *Config
	Token         string
	LastLogin     time.Time
	TokenMtx      sync.RWMutex
	LoginMtx      sync.Mutex
	ClientProfile *ClientProfile
}

Client is a fully-featured client through which HVCA API calls can be made.

A client is created from either a configuration object or a configuration file containing the account and other information. Once a client is created, it can then be used to make HVCA API calls.

The user does not need to explicitly login. The client object will log the user in automatically, and refresh their login if the authentication token expires. In the event of a HTTP 503 service unavailable response, or a response indicating that a request has been accepted but the corresponding resource is not yet available, the client will automatically wait and retry the call a predetermined number of times. The maximum wait time for this process may be controlled through the context passed to each API call.

It is safe to make concurrent API calls from a single client object.

func NewClient

func NewClient(ctx context.Context, conf *Config) (*Client, error)

NewClient creates a new HVCA client from a configuration object. An initial login is made, and the returned client is immediately ready to make API calls.

func NewClientFromFile

func NewClientFromFile(ctx context.Context, filename string) (*Client, error)

NewClientFromFile returns a new HVCA client from a configuration file. An initial login is made, and the returned client is immediately ready to make API calls.

func NewThinClient

func NewThinClient(profile *ClientProfile, httpClient *http.Client) (*Client, error)

NewThinClient creates a new client with no initial login client and a custom http client to facilitate re-use between hvclients.

func (*Client) CertificateRequest

func (c *Client) CertificateRequest(
	ctx context.Context,
	req *Request,
) (*string, error)

CertificateRequest requests a new certificate based. The HVCA API is asynchronous, and on success this method returns the serial number of the new certificate. After a short delay, the certificate itself may be retrieved via the CertificateRetrieve method.

func (*Client) CertificateRetrieve

func (c *Client) CertificateRetrieve(
	ctx context.Context,
	serial *big.Int,
) (*CertInfo, error)

CertificateRetrieve retrieves a certificate.

func (*Client) CertificateRevoke

func (c *Client) CertificateRevoke(
	ctx context.Context,
	serial *big.Int,
) error

func (*Client) CertificateRevokeWithReason

func (c *Client) CertificateRevokeWithReason(
	ctx context.Context,
	serial *big.Int,
	reason RevocationReason,
	time int64,
	keyCompromiseAttestation string,
) error

CertificateRevokeWithReason revokes a certificate with a specified reason and UTC UNIX timestamp indicating when the private key was compromised if supported by the HVCA server. A special case holds when time is 0 which indicates that the current time should be used.

func (*Client) ClaimADNRetrieve

func (c *Client) ClaimADNRetrieve(ctx context.Context, id string) ([]string, error)

ClaimADNRetrieve retrieves a list of ADNs allowed for given domain

func (*Client) ClaimDNS

func (c *Client) ClaimDNS(ctx context.Context, id, authDomain string) (bool, error)

ClaimDNS requests assertion of domain control using DNS once the appropriate token has been placed in the relevant DNS records. A return value of false indicates that the assertion request was created. A return value of true indicates that domain control was verified.

func (*Client) ClaimDelete

func (c *Client) ClaimDelete(ctx context.Context, id string) error

ClaimDelete deletes a domain claim.

func (*Client) ClaimEmail

func (c *Client) ClaimEmail(ctx context.Context, id, emailAddress string) (bool, error)

ClaimEmail requests for an email with a verification link be sent to the provided emailAddress in order for the user to assert control of a domain by following the link inside the sent email. A return value of false indicates that the assertion request was created. A return value of true indicates that domain control was verified.

func (*Client) ClaimEmailRetrieve

func (c *Client) ClaimEmailRetrieve(ctx context.Context, id string) (*AuthorisedEmails, error)

ClaimEmailRetrieve retrieves a list of email addresses authorized to perform Email validation.

func (*Client) ClaimHTTP

func (c *Client) ClaimHTTP(ctx context.Context, id, authDomain, scheme string) (bool, error)

ClaimHTTP requests assertion of domain control using HTTP once the appropriate token has been placed at the expected path. A return value of false indicates that the assertion request was created. A return value of true indicates that domain control was verified.

func (*Client) ClaimReassert

func (c *Client) ClaimReassert(ctx context.Context, id string) (*ClaimAssertionInfo, error)

ClaimReassert reasserts an existing domain claim, for example if the assert-by time of a previous assertion request has expired.

func (*Client) ClaimRetrieve

func (c *Client) ClaimRetrieve(ctx context.Context, id string) (*Claim, error)

ClaimRetrieve returns a domain claim.

func (*Client) ClaimSubmit

func (c *Client) ClaimSubmit(ctx context.Context, domain string) (*ClaimAssertionInfo, error)

ClaimSubmit submits a new domain claim and returns the token value that should be used to verify control of that domain.

func (*Client) ClaimsDomains

func (c *Client) ClaimsDomains(
	ctx context.Context,
	page, perPage int,
	status ClaimStatus,
) ([]Claim, int64, error)

ClaimsDomains returns a slice of either pending or verified domain claims along with the total count of domain claims in either category. The total count may be higher than the number of claims in the slice if the total count is higher than the specified number of claims per page. The HVCA API enforces a maximum number of claims per page. If the total count is higher than the number of claims in the slice, the remaining claims may be retrieved by incrementing the page number in subsequent calls of this method.

func (*Client) CounterCertsIssued

func (c *Client) CounterCertsIssued(ctx context.Context) (int64, error)

CounterCertsIssued returns the number of certificates issued by the calling account.

func (*Client) CounterCertsRevoked

func (c *Client) CounterCertsRevoked(ctx context.Context) (int64, error)

CounterCertsRevoked returns the number of certificates revoked by the calling account.

func (*Client) DefaultTimeout

func (c *Client) DefaultTimeout() time.Duration

DefaultTimeout returns the timeout specified in the configuration object or file used to create the client, or the default timeout provided if no value was specified. This is useful for honoring the timeout requested by the configuration when creating the context to pass to an API method if the original configuration information is no longer available.

func (*Client) GetToken

func (c *Client) GetToken() string

GetToken performs a synchronized read of the stored authentication token.

func (*Client) Policy

func (c *Client) Policy(ctx context.Context) (*Policy, error)

Policy returns the calling account's validation policy.

func (*Client) QuotaIssuance

func (c *Client) QuotaIssuance(ctx context.Context) (int64, error)

QuotaIssuance returns the remaining quota of certificate issuances for the calling account.

func (*Client) SetToken

func (c *Client) SetToken(token string)

SetToken sets the stored authentication token and sets the last login time to the current time.

func (*Client) StatsExpiring

func (c *Client) StatsExpiring(
	ctx context.Context,
	page, perPage int,
	from, to time.Time,
) ([]CertMeta, int64, error)

StatsExpiring returns a slice of the certificates which expired or which will expire during the specified time window, along with the total count of those certificates. The total count may be higher than the number of certificates in the slice if the total count is higher than the specified number of certificates per page. The HVCA API enforces a maximum number of certificates per page. If the total count is higher than the number of certificates in the slice, the remaining certificates may be retrieved by incrementing the page number in subsequent calls of this method.

func (*Client) StatsIssued

func (c *Client) StatsIssued(
	ctx context.Context,
	page, perPage int,
	from, to time.Time,
) ([]CertMeta, int64, error)

StatsIssued returns a slice of the certificates which were issued during the specified time window, along with the total count of those certificates. The total count may be higher than the number of certificates in the slice if the total count is higher than the specified number of certificates per page. The HVCA API enforces a maximum number of certificates per page. If the total count is higher than the number of certificates in the slice, the remaining certificates may be retrieved by incrementing the page number in subsequent calls of this method.

func (*Client) StatsRevoked

func (c *Client) StatsRevoked(
	ctx context.Context,
	page, perPage int,
	from, to time.Time,
) ([]CertMeta, int64, error)

StatsRevoked returns a slice of the certificates which were revoked during the specified time window, along with the total count of those certificates. The total count may be higher than the number of certificates in the slice if the total count is higher than the specified number of certificates per page. The HVCA API enforces a maximum number of certificates per page. If the total count is higher than the number of certificates in the slice, the remaining certificates may be retrieved by incrementing the page number in subsequent calls of this method.

func (*Client) TrustChain

func (c *Client) TrustChain(ctx context.Context) ([]*x509.Certificate, error)

TrustChain returns the chain of trust for the certificates issued by the calling account.

type ClientProfile

type ClientProfile struct {
	// Configuration
	Config *Config

	// User Token
	Token string
}

ClientProfile is a configuration object for HVCA client and contains a Config field and a token field

type Config

type Config struct {
	// URL is the URL of the HVCA service, including any version number.
	URL string

	// TLSCert is the certificate to use for mutual TLS authentication to HVCA,
	// provided by GlobalSign when the HVCA account was set up.
	TLSCert *x509.Certificate

	// TLSKey is the private key corresponding to the public key provided to
	// GlobalSign when the HVCA account was set up. This is used for mutual TLS
	// authentication with HVCA, and is NOT related to any public key to be
	// included in a certificate request.
	TLSKey interface{}

	// APIKey is the API key for the HVCA account, provided by GlobalSign when
	// the account was set up.
	APIKey string

	// APISecret is the API secret for the HVCA account, provided by GlobalSign
	// when the account was set up.
	APISecret string

	// TLSRoots contain the root certificates used to validate HVCA's TLS
	// server certificate. If nil, the system pool will be used.
	TLSRoots *x509.CertPool

	// ExtraHeaders contains custom HTTP request headers to be passed to the
	// HVCA server with each request.
	ExtraHeaders map[string]string

	// If InsecureSkipVerify is true, TLS accepts any certificate
	// presented by the server and any host name in that certificate.
	// In this mode, TLS is susceptible to man-in-the-middle attacks.
	// This should be used only for testing.
	InsecureSkipVerify bool

	// Timeout is the number of seconds to wait before cancelling an HVCA API
	// request. If this is omitted or set to zero, a reasonable default will
	// be used.
	Timeout time.Duration
	// contains filtered or unexported fields
}

Config is a configuration object for an HVCA client.

func NewConfigFromFile

func NewConfigFromFile(filename string) (*Config, error)

NewConfigFromFile creates a new HVCA client configuration object from a configuration file.

func (*Config) UnmarshalJSON

func (c *Config) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON encoded configuration and stores the result in the object.

func (*Config) Validate

func (c *Config) Validate() error

Validate returns an error if any fields in the configuration object are missing or malformed. It also calculates a default timeout, if the Timeout field is zero.

type CustomExtensionsPolicy

type CustomExtensionsPolicy struct {
	OID         asn1.ObjectIdentifier `json:"-"`
	Presence    Presence              `json:"presence"`
	Critical    bool                  `json:"critical"`
	ValueType   ValueType             `json:"value_type"`
	ValueFormat string                `json:"value_format,omitempty"`
}

CustomExtensionsPolicy is the custom extensions field in a validation policy.

type DA

type DA struct {
	Gender               string
	DateOfBirth          time.Time
	PlaceOfBirth         string
	CountryOfCitizenship []string
	CountryOfResidence   []string
	ExtraAttributes      []OIDAndString
}

DA is a list of Subject Directory Attributes to include in a certificate. See RFC 3739.

func (*DA) Equal

func (d *DA) Equal(other *DA) bool

Equal checks if two subject directory attributes lists are equivalent.

func (*DA) MarshalJSON

func (d *DA) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a subject directory attributes list.

func (*DA) UnmarshalJSON

func (d *DA) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded subject directory attributes list and stores the result in the object.

type DN

type DN struct {
	Country            string         `json:"country,omitempty"`
	State              string         `json:"state,omitempty"`
	Locality           string         `json:"locality,omitempty"`
	StreetAddress      string         `json:"street_address,omitempty"`
	Organization       string         `json:"organization,omitempty"`
	OrganizationalUnit []string       `json:"organizational_unit,omitempty"`
	CommonName         string         `json:"common_name,omitempty"`
	SerialNumber       string         `json:"serial_number,omitempty"`
	Email              string         `json:"email,omitempty"`
	JOILocality        string         `json:"jurisdiction_of_incorporation_locality_name,omitempty"`
	JOIState           string         `json:"jurisdiction_of_incorporation_state_or_province_name,omitempty"`
	JOICountry         string         `json:"jurisdiction_of_incorporation_country_name,omitempty"`
	BusinessCategory   string         `json:"business_category,omitempty"`
	ExtraAttributes    []OIDAndString `json:"extra_attributes,omitempty"`
}

DN is a list of Distinguished Name attributes to include in a certificate. See RFC 5280 4.1.2.6.

func (*DN) Equal

func (n *DN) Equal(other *DN) bool

Equal checks if two subject distinguished names are equivalent.

func (*DN) PKIXName

func (n *DN) PKIXName() pkix.Name

PKIXName converts a subject distinguished name into a pkix.Name object.

type DNSResults

type DNSResults struct {
	SOA SOAResults `json:"SOA"`
}

DNSResults is a set of maps for all queried record types. Record types are the keys of the maps.

type EKUPolicy

type EKUPolicy struct {
	EKUs     ListPolicy `json:"ekus"`
	Critical bool       `json:"critical"`
}

EKUPolicy is the extended key usages field in a validation policy.

type ETSIPDsPolicy

type ETSIPDsPolicy struct {
	Presence Presence          `json:"presence"`
	Policies map[string]string `json:"policies"`
}

ETSIPDsPolicy is the PKI disclosure statements field in the qualified statements field in a validation policy.

type IntegerPolicy

type IntegerPolicy struct {
	Presence Presence `json:"presence"`
	Min      int      `json:"min"`
	Max      int      `json:"max"`
}

IntegerPolicy is an integer value entry in a validation policy.

type KeyFormat

type KeyFormat int

KeyFormat is the allowed format of a public key.

const (
	PKCS8 KeyFormat = iota + 1
	PKCS10
)

Key format value constants.

func (KeyFormat) MarshalJSON

func (f KeyFormat) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a key format value.

func (KeyFormat) String

func (f KeyFormat) String() string

String returns a description of the key format value.

func (*KeyFormat) UnmarshalJSON

func (f *KeyFormat) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded key format value and stores the result in the object.

type KeyType

type KeyType int

KeyType is the type of a public key.

const (
	RSA KeyType = iota + 1
	ECDSA
)

Key type value constants.

func (KeyType) MarshalJSON

func (t KeyType) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a key type value.

func (KeyType) String

func (t KeyType) String() string

String returns a description of the key type value.

func (*KeyType) UnmarshalJSON

func (t *KeyType) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded key type value and stores the result in the object.

type ListPolicy

type ListPolicy struct {
	Static   bool     `json:"static"`
	List     []string `json:"list"`
	MinCount int      `json:"mincount"`
	MaxCount int      `json:"maxcount"`
}

ListPolicy is a list value entry in a validation policy.

type MSExtension

type MSExtension struct {
	OID          asn1.ObjectIdentifier
	MajorVersion int
	MinorVersion int
}

MSExtension contains values with which to populate a Microsoft template extension (91.3.6.1.4.1.311.21.7) with.

func (*MSExtension) Equal

func (m *MSExtension) Equal(other *MSExtension) bool

Equal checks if two MS template extensions are equivalent.

func (*MSExtension) MarshalJSON

func (m *MSExtension) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a MS template extension.

func (*MSExtension) UnmarshalJSON

func (m *MSExtension) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded MS template extension and stores the result in the object.

type MSExtensionTemplatePolicy

type MSExtensionTemplatePolicy struct {
	Critical     bool           `json:"critical"`
	TemplateID   *StringPolicy  `json:"template_id,omitempty"`
	MajorVersion *IntegerPolicy `json:"major_version,omitempty"`
	MinorVersion *IntegerPolicy `json:"minor_version,omitempty"`
}

MSExtensionTemplatePolicy is the Microsoft template extension field in a validation policy.

type OIDAndString

type OIDAndString struct {
	OID   asn1.ObjectIdentifier
	Value string
}

OIDAndString is an ASN.1 object identifier (OID) together with an associated string value.

func (OIDAndString) AttributeTypeAndValue

func (o OIDAndString) AttributeTypeAndValue() pkix.AttributeTypeAndValue

AttributeTypeAndValue converts an OIDAndString object into a pkix.AttributeTypeAndValue object.

func (OIDAndString) Equal

func (o OIDAndString) Equal(other OIDAndString) bool

Equal checks if two OID and string objects are equivalent.

func (OIDAndString) MarshalJSON

func (o OIDAndString) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of an OID and string.

func (*OIDAndString) UnmarshalJSON

func (o *OIDAndString) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded OID and string and stores the result in the object.

type OptionalStaticPresence

type OptionalStaticPresence int

OptionalStaticPresence denotes whether a static boolean is optional, or true, or false.

const (
	StaticOptional OptionalStaticPresence = iota + 1
	StaticTrue
	StaticFalse
)

Optional static presence values.

func (OptionalStaticPresence) MarshalJSON

func (v OptionalStaticPresence) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of an optional static presence value.

func (OptionalStaticPresence) String

func (v OptionalStaticPresence) String() string

String returns a description of the optional static presence value.

func (*OptionalStaticPresence) UnmarshalJSON

func (v *OptionalStaticPresence) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded optional static presence value and stores the result in the object.

type Policy

type Policy struct {
	Validity            *ValidityPolicy            `json:"validity,omitempty"`
	SubjectDN           *SubjectDNPolicy           `json:"subject_dn,omitempty"`
	SAN                 *SANPolicy                 `json:"san,omitempty"`
	EKUs                *EKUPolicy                 `json:"extended_key_usages,omitempty"`
	SubjectDA           *SubjectDAPolicy           `json:"subject_da,omitempty"`
	QualifiedStatements *QualifiedStatementsPolicy `json:"qualified_statements,omitempty"`
	MSExtensionTemplate *MSExtensionTemplatePolicy `json:"ms_extension_template,omitempty"`
	SignaturePolicy     *SignaturePolicy           `json:"signature,omitempty"`
	PublicKey           *PublicKeyPolicy           `json:"public_key,omitempty"`
	PublicKeySignature  Presence                   `json:"public_key_signature"`
	CustomExtensions    []CustomExtensionsPolicy   `json:"custom_extensions,omitempty"`
}

Policy is a certificate request validation policy.

func (Policy) MarshalJSON

func (p Policy) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a validation policy.

func (*Policy) UnmarshalJSON

func (p *Policy) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded validation policy and stores the result in the object.

type Presence

type Presence int

Presence is the presence field in a validation policy.

const (
	Optional Presence = iota + 1
	Required
	Forbidden
	Static
)

Presence value constants.

func (Presence) MarshalJSON

func (p Presence) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a presence value.

func (Presence) String

func (p Presence) String() string

String returns a description of the presence value.

func (*Presence) UnmarshalJSON

func (p *Presence) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded presence value and stores the result in the object.

type PublicKeyPolicy

type PublicKeyPolicy struct {
	KeyType        KeyType   `json:"key_type"`
	AllowedLengths []int     `json:"allowed_lengths"`
	KeyFormat      KeyFormat `json:"key_format"`
}

PublicKeyPolicy is the public key field in a validation policy.

type QualifiedStatements

type QualifiedStatements struct {
	Semantics         Semantics
	QCCompliance      bool
	QCSSCDCompliance  bool
	QCType            asn1.ObjectIdentifier
	QCRetentionPeriod int
	QCPDs             map[string]string
}

QualifiedStatements is a list of qualified statements to include in a certificate. See RFC 3739 3.2.6.

func (*QualifiedStatements) Equal

func (q *QualifiedStatements) Equal(other *QualifiedStatements) bool

Equal checks if two qualified statements lists are equivalent.

func (*QualifiedStatements) MarshalJSON

func (q *QualifiedStatements) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a qualified statements list.

func (*QualifiedStatements) UnmarshalJSON

func (q *QualifiedStatements) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded qualified statements list and stores the result in the object.

type QualifiedStatementsPolicy

type QualifiedStatementsPolicy struct {
	Semantics             *SemanticsPolicy       `json:"semantics"`
	ETSIQCCompliance      OptionalStaticPresence `json:"etsi_qc_compliance"`
	ETSIQCSSCDCompliance  OptionalStaticPresence `json:"etsi_qc_sscd_compliance"`
	ETSIQCType            *StringPolicy          `json:"etsi_qc_type"`
	ETSIQCRetentionPeriod *IntegerPolicy         `json:"etsi_qc_retention_period"`
	ETSIQCPDs             *ETSIPDsPolicy         `json:"etsi_qc_pds"`
}

QualifiedStatementsPolicy is the qualified statements field in a validation policy.

type Request

type Request struct {
	Validity            *Validity
	Subject             *DN
	SAN                 *SAN
	EKUs                []asn1.ObjectIdentifier
	DA                  *DA
	QualifiedStatements *QualifiedStatements
	MSExtension         *MSExtension
	CustomExtensions    []OIDAndString
	CSR                 *x509.CertificateRequest
	Signature           *Signature
	PrivateKey          interface{}
	PublicKey           string
}

Request is a request to HVCA for the issuance of a new certificate.

An HVCA account will be set up with one of three options regarding proof-of-possession of the private key corresponding to the public key to be included in the certificate:

1. No proof required

2. Provide the public key signed by the private key

3. Provide a signed PKCS#10 certificate signing request.

For case 1, simply assign the public key in question to the PublicKey field of the Request. For case 2, leave the PublicKey field empty and assign the private key to the PrivateKey field of the Request, and the public key will be automatically extracted and the appropriate signature generated. For case 3, leave both the PublicKey and PrivateKey fields empty and assign the PKCS#10 certificate signed request to the CSR field. Note that when providing a PKCS#10 certificate signing request, none of the fields in the CSR are examined by HVCA except for the public key and the signature, and none of the fields in the CSR are automatically copied to the Request object.

func (Request) Equal

func (r Request) Equal(other Request) bool

Equal checks if two certificate requests are equivalent.

func (Request) MarshalJSON

func (r Request) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a certificate request.

func (*Request) PKCS10

func (r *Request) PKCS10() (*x509.CertificateRequest, error)

PKCS10 converts a Request object into a PKCS#10 certificate signing request.

BUG(paul): Not all fields are currently marshalled into the PKCS#10 request. The fields currently marshalled include: subject distinguished name (all fields, including extra attributes); subject alternative names (excluding other names); and extended key usages.

func (*Request) UnmarshalJSON

func (r *Request) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded certificate request and stores the result in the object.

type RevocationReason

type RevocationReason string

RevocationReason is a type for specifying the reason why a certificate is being revoked when requesting revocation.

type SAN

type SAN struct {
	DNSNames    []string
	Emails      []string
	IPAddresses []net.IP
	URIs        []*url.URL
	OtherNames  []OIDAndString
}

SAN is a list of Subject Alternative Name attributes to include in a certificate. See RFC 5280 4.2.1.6.

func (*SAN) Equal

func (s *SAN) Equal(other *SAN) bool

Equal checks if two subject alternative names lists are equivalent.

func (*SAN) MarshalJSON

func (s *SAN) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a subject alternative names list.

func (*SAN) UnmarshalJSON

func (s *SAN) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded subject alternative names list and stores the result in the object.

type SANPolicy

type SANPolicy struct {
	DNSNames    *ListPolicy
	Emails      *ListPolicy
	IPAddresses *ListPolicy
	URIs        *ListPolicy
	OtherNames  []TypeAndValuePolicy
}

SANPolicy is the subject alternative names field in a validation policy.

func (SANPolicy) MarshalJSON

func (p SANPolicy) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a subject alternative names policy.

func (*SANPolicy) UnmarshalJSON

func (p *SANPolicy) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded subject alternative names policy and stores the result in the object.

type SOAResults

type SOAResults struct {
	Emails []string `json:"emails"`
	Errors []string `json:"errors,omitempty"`
}

SOAResults is a map of SOA records for DNS results

type Semantics

type Semantics struct {
	OID             asn1.ObjectIdentifier
	NameAuthorities []string
}

Semantics is the OID and optional name authorities for a qualified certificate statement. See RFC 3739 3.2.6.1.

func (Semantics) Equal

func (s Semantics) Equal(other Semantics) bool

Equal checks if two semantics objects are equivalent.

func (Semantics) MarshalJSON

func (s Semantics) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a semantics object.

func (*Semantics) UnmarshalJSON

func (s *Semantics) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded semantics object and stores the result in the object.

type SemanticsPolicy

type SemanticsPolicy struct {
	Identifier      *StringPolicy `json:"identifier"`
	NameAuthorities *ListPolicy   `json:"name_authorities"`
}

SemanticsPolicy is the semantics field in the qualified statements field in a validation policy.

type Signature

type Signature struct {
	Algorithm     string `json:"algorithm"`
	HashAlgorithm string `json:"hash_algorithm"`
}

Signature is the signature field in Request.

type SignaturePolicy

type SignaturePolicy struct {
	Algorithm     *AlgorithmPolicy `json:"algorithm"`
	HashAlgorithm *AlgorithmPolicy `json:"hash_algorithm"`
}

SignaturePolicy is the signature field in a validation policy.

type StringPolicy

type StringPolicy struct {
	Presence Presence `json:"presence"`
	Format   string   `json:"format"`
}

StringPolicy is a string value entry in a validation policy.

type SubjectDAPolicy

type SubjectDAPolicy struct {
	Gender               *StringPolicy        `json:"gender,omitempty"`
	DateOfBirth          Presence             `json:"date_of_birth,omitempty"`
	PlaceOfBirth         *StringPolicy        `json:"place_of_birth,omitempty"`
	CountryOfCitizenship *ListPolicy          `json:"country_of_citizenship,omitempty"`
	CountryOfResidence   *ListPolicy          `json:"country_of_residence,omitempty"`
	ExtraAttributes      []TypeAndValuePolicy `json:"extra_attributes,omitempty"`
}

SubjectDAPolicy is the subject directory attributes field in a validation policy.

func (SubjectDAPolicy) MarshalJSON

func (p SubjectDAPolicy) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a subject directory attributes policy.

func (*SubjectDAPolicy) UnmarshalJSON

func (p *SubjectDAPolicy) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded subject directory attributes names policy and stores the result in the object.

type SubjectDNPolicy

type SubjectDNPolicy struct {
	CommonName               *StringPolicy        `json:"common_name,omitempty"`
	GivenName                *StringPolicy        `json:"given_name,omitempty"`
	Surname                  *StringPolicy        `json:"surname,omitempty"`
	Organization             *StringPolicy        `json:"organization,omitempty"`
	OrganizationalUnit       *ListPolicy          `json:"organizational_unit,omitempty"`
	OrganizationalIdentifier *StringPolicy        `json:"organization_identifier,omitempty"`
	Country                  *StringPolicy        `json:"country,omitempty"`
	State                    *StringPolicy        `json:"state,omitempty"`
	Locality                 *StringPolicy        `json:"locality,omitempty"`
	StreetAddress            *StringPolicy        `json:"street_address,omitempty"`
	PostalCode               *StringPolicy        `json:"postal_code,omitempty"`
	Email                    *StringPolicy        `json:"email,omitempty"`
	JOILocality              *StringPolicy        `json:"jurisdiction_of_incorporation_locality_name,omitempty"`
	JOIState                 *StringPolicy        `json:"jurisdiction_of_incorporation_state_or_province_name,omitempty"`
	JOICountry               *StringPolicy        `json:"jurisdiction_of_incorporation_country_name,omitempty"`
	BusinessCategory         *StringPolicy        `json:"business_category,omitempty"`
	SerialNumber             *StringPolicy        `json:"serial_number,omitempty"`
	ExtraAttributes          []TypeAndValuePolicy `json:"-"`
}

SubjectDNPolicy is a subject distinguished name field in a validation policy.

func (SubjectDNPolicy) MarshalJSON

func (p SubjectDNPolicy) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a subject distinguished name policy.

func (*SubjectDNPolicy) UnmarshalJSON

func (p *SubjectDNPolicy) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded subject distinguished name policy and stores the result in the object.

type TypeAndValuePolicy

type TypeAndValuePolicy struct {
	OID         asn1.ObjectIdentifier `json:"-"`
	Static      bool                  `json:"static"`
	ValueType   ValueType             `json:"value_type"`
	ValueFormat string                `json:"value_format"`
	MinCount    int                   `json:"mincount"`
	MaxCount    int                   `json:"maxcount"`
}

TypeAndValuePolicy is a type and value entry in a validation policy.

type Validity

type Validity struct {
	NotBefore time.Time
	NotAfter  time.Time
}

Validity contains the requested not-before and not-after times for a certificate. If NotAfter is set to time.Unix(0, 0), the maximum duration allowed by the validation policy will be applied.

func (*Validity) Equal

func (v *Validity) Equal(other *Validity) bool

Equal checks if two validity objects are equivalent.

func (*Validity) MarshalJSON

func (v *Validity) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a validity object.

func (*Validity) UnmarshalJSON

func (v *Validity) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded validity object and stores the result in the object.

type ValidityPolicy

type ValidityPolicy struct {
	SecondsMin            int64 `json:"secondsmin"`
	SecondsMax            int64 `json:"secondsmax"`
	NotBeforeNegativeSkew int64 `json:"not_before_negative_skew"`
	NotBeforePositiveSkew int64 `json:"not_before_positive_skew"`
	IssuerExpiry          int64 `json:"issuer_expiry"`
}

ValidityPolicy is a validity field in a validation policy.

type ValueType

type ValueType int

ValueType is a value_type field in a validation policy.

const (
	IA5String ValueType = iota + 1
	PrintableString
	UTF8String
	Integer
	DER
	Nil
)

ValueType value constants.

func (ValueType) MarshalJSON

func (v ValueType) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of a value type value.

func (ValueType) String

func (v ValueType) String() string

String returns a description of the value type value.

func (*ValueType) UnmarshalJSON

func (v *ValueType) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON-encoded value type value and stores the result in the object.

Notes

Bugs

  • Not all fields are currently marshalled into the PKCS#10 request. The fields currently marshalled include: subject distinguished name (all fields, including extra attributes); subject alternative names (excluding other names); and extended key usages.

Directories

Path Synopsis
cmd
hvclient
Program hvclient provides a commandline utility for interfacing with the HVCA system.
Program hvclient provides a commandline utility for interfacing with the HVCA system.
internal
config
Package config contains functionality for extracting configuration options from a JSON-encoded configuration file.
Package config contains functionality for extracting configuration options from a JSON-encoded configuration file.
httputils
Package httputils contains assorted HTTP-related functionality.
Package httputils contains assorted HTTP-related functionality.
oids
Package oids contains functionality for working with ASN.1 object identifiers.
Package oids contains functionality for working with ASN.1 object identifiers.
pki
Package pki provides various generally useful PKI functionality.
Package pki provides various generally useful PKI functionality.
testhelpers
Package testhelpers contains various testing helper functions.
Package testhelpers contains various testing helper functions.

Jump to

Keyboard shortcuts

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