atlas

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Mar 25, 2024 License: MPL-2.0 Imports: 16 Imported by: 0

README

GlobalSign ATLAS Client

Documentation: https://www.globalsign.com/en/resources/apis/api-documentation/globalsign_atlas_api_documentation_version_v2.html

Client Flow

  1. Configure Client
  2. Get Access Token
  3. Get Issuance Policy

Cert Issuance Flow

  1. Get Initial Request
  2. Check against policy
  3. Populate static fields
  4. Generate RSA Keypair
  5. Sign Payload
  6. Embeded Data

Error Behavior

2XX -> Continue 401 -> Reauthorize with New Token 4XX -> Abort and Error 503 -> Backoff Retry

Formatting

Outbound: application/json;charset=utf-8 Inbound: application/json;charset=utf-8 Inbound Error: application/problem+json;charset=utf-8

Cert Issuance

{
    validity: {
        not_before: now.epoch(),
    },
    subject_dn: {
        "common_name": "John Doe",
        "country": "US",
        "organization": "GlobalSign AEG Dev",
        "organizational_unit": [
            "Development"
        ],
        "email": "mailto:test_cert@aegdomain.com"
    },
    sam: {
        "emails": "test_cert@aegdomain.com"
    },
    "key_usages": {
        "content_commitment": false,
        "crl_sign": false,
        "data_encipherment": false,
        "decipher_only": false,
        "digital_signature": true,
        "encipher_only": false,
        "key_agreement": true,
        "key_certificate_sign": false,
        "key_encipherment": true
    },

}

Documentation

Overview

Package atlas is an GlobalSign Atlas API Client.

GlobalSign Atlas API Documentation: https://www.globalsign.com/en/resources/apis/api-documentation/globalsign_hvca_api_documentation_version_v2.html

Example
// Load Your client certificate
cert, err := tls.LoadX509KeyPair("testdata/example-cert.pem", "testdata/example-key.pem")
if err != nil {
	log.Fatal(err)
}

// Construct your Client.
client, err := NewDefault(&ClientConfig{
	APIKey:      String("my_atlas_api_key"),
	APISecret:   String("my_atlas_api_secret"),
	Certificate: &cert,
})
if err != nil {
	log.Fatal(err)
}

// Optional: Call Login Directly, it will be automatically called on all other calls.
err = client.Login(context.TODO())
if err != nil {
	log.Fatal(err)
}
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	MockCert = &Certificate{
		Status: "ISSUED",
		Certificate: `
-----BEGIN CERTIFICATE-----
MIIEcjCCA1qgAwIBAgIQAb4ElB1WWfbjZRykITZ+GDANBgkqhkiG9w0BAQsFADBS
MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQR2xvYmFsU2lnbiBudi1zYTEoMCYGA1UE
AxMfR2xvYmFsU2lnbiBOb24tUHVibGljIEhWQ0EgRGVtbzAeFw0yMDExMjQwODM3
NTFaFw0yMDEyMjYwODM4MjFaMEExCzAJBgNVBAYTAlVTMRswGQYDVQQKDBJHbG9i
YWxTaWduIEFFRyBEZXYxFTATBgNVBAMMDGV4YW1wbGVfcm9sZTCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBAMWU8jxBwPQquEM1VcFh1OUakvpD2q5WsJs3
9AAgI2ctksZvzw32AZNBto63noiOWQTYts+9SPNgbneaUviHwjdaJ2AOAO6yl5z7
45y12254okCLU96m8JAHFsrN5yFyV45GKpmWAWmD8iUJRgTOSWY9u2SdNWJkxmTI
PVrNPLqTPK+LuO5x+HGhQIy78Tgxoz8JXN1YO9sRoPOAjLCeTFkN0iCF+8lCfSDV
biE7iK0OSYEcmeSWV5Q/yUIxc4KPGB4snUHZLUPwJwx8+58yCdb9Q6O6Bn6zqp3l
6jRdPYD7VFHdebVLBnx9hDOtZ2RKOBTOzLLQXPcU/8gBJA7Yfg0CAwEAAaOCAVMw
ggFPMA4GA1UdDwEB/wQEAwIDqDATBgNVHSUEDDAKBggrBgEFBQcDAjAdBgNVHQ4E
FgQUhVL3S4+eVDv9rtOMlqpQM8YSHigwCQYDVR0TBAIwADCBlgYIKwYBBQUHAQEE
gYkwgYYwPAYIKwYBBQUHMAGGMGh0dHA6Ly9vY3NwLmdsb2JhbHNpZ24uY29tL2Nh
L2dzbnBodmNhZGVtb3NoYTJnMzBGBggrBgEFBQcwAoY6aHR0cDovL3NlY3VyZS5n
bG9iYWxzaWduLmNvbS9jYWNlcnQvZ3NucGh2Y2FkZW1vc2hhMmczLmNydDAfBgNV
HSMEGDAWgBRnSwfpCfHxezLMvYUcTicNzqHMbDBEBgNVHR8EPTA7MDmgN6A1hjNo
dHRwOi8vY3JsLmdsb2JhbHNpZ24uY29tL2NhL2dzbnBodmNhZGVtb3NoYTJnMy5j
cmwwDQYJKoZIhvcNAQELBQADggEBAJC92kS4QJyubFMi54GwmY0OVOj5VSzp8hb0
idct117ms63oNCU/WYDI1rC/wUvrI8PIE/dLsD3MYGKCbl2w2ZAzY6FQI646PC3J
JC7TEIPnbpcf8epfC3aglOj26IERgagVoWo137kzEsKN7bNy2zrNiTu4bZOm1zFq
LP0k4EQ6r1uCLVLj7BOkSQ8WZ552usv26eTYqppl7yL0A+nrq8CL3KFVwbfsMz2C
xV3jSxHKuZ8+oEpD+R8rPlH2WSgqPxu0TIowGXGoKwcF6/5qJBj6R5ZKC/y5E9Qm
SIWufet+dT+AvaVtKLDu1DewwXiK177L2iv6U7cc1mOV4xL91Qc=
-----END CERTIFICATE-----`,
		UpdatedAt: 1606207103,
	}

	MockCACert = `` /* 1251-byte string literal not displayed */

	MockCertSerial = "01be04941d5659f6e3651ca421367e18"
)

Functions

func String

func String(s string) *string

String provides a reference to a string inline; this is useful when setting optional configuration.

Types

type APIError

type APIError struct {
	Description string `json:"description"`
	StatusCode  int
}

func (*APIError) Error

func (e *APIError) Error() string

type CertRequestOptions

type CertRequestOptions struct {
	// OverrideSignatureAlgorithm will explicitly set the signature algorithm
	OverrideSignatureAlgorithm *string

	// OverrideSignatureHashAlgorithm will explicitly set the hash algorithm
	OverrideSignatureHashAlgorithm *string

	// OverrideHasStaticKeyUsage will omit key usage information to handle static key usage policy
	OverrideDisableKeyUsageExtensions bool

	// OverrideHasStaticKeyUsage will omit key usage information to handle static key usage policy
	OverrideDisableExtendedKeyUsageExtensions bool
}

CertRequestOptions dictates overrides and options when generating a cert request object from a template

type Certificate

type Certificate struct {
	// Status of the certificate typically ISSUED, or REVOKED
	Status string `json:"status"`

	// The PEM Encoded Certificate
	Certificate string `json:"certificate"`

	// UpdatedAt the time which the object was last updated, typically issuance or revocation time.
	UpdatedAt uint64 `json:"updated_at"`
}

Certificate is the API structured object return by GlobalSign Atlas

type Client

type Client interface {
	// Login performs the exchange of
	Login(ctx context.Context) error

	// GetConfig gets the configuration profile for your Atlas Instance, Refer to the API documentation for more info.
	GetConfig(ctx context.Context) (ValidationPolicy, error)

	// GetTrustChain returns the Certificate Authority chain used by the instance, output is an array of PEM encoded certs.
	GetTrustChain(ctx context.Context) ([]string, error)

	// IssueCertificate will that the provided CSR and Parameters to request issuance of a certificate from your Atlas Instance.
	IssueCertificate(ctx context.Context, req *IssueCertRequest) (*Certificate, error)

	// GetCert gets the certificate for the provided serial number.
	GetCert(ctx context.Context, id string) (*Certificate, error)
	// RevokeCert revokes the certificate with the provided serial number.
	RevokeCert(ctx context.Context, id string) error
}

Client acts as a interface between the local process and Globalsign ATLAS.

func New

func New(conf *ClientConfig) (Client, error)

New constructs a ready to use ATLAS client.

type ClientConfig

type ClientConfig struct {
	APIKey      *string
	APISecret   *string
	HVCAUrl     string
	Certificate *tls.Certificate

	// Retries is the number of attempts a 5XX class error or 202 status will be retried
	Retries int

	// InitialBackoff is the initial backoff used in the exponential backoff.
	InitialBackoff time.Duration
}

ClientConfig represents configuration options available to the ATLAS client.

type EKUPolicy

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

Types requied to unmarshal Valiation Policy from HVCA

type IssueCertRequest

type IssueCertRequest struct {
	Validity            *Validity            `json:"validity,omitempty" validate:"required"`
	SubjectDN           *SubjectDN           `json:"subject_dn,omitempty" validate:"required"`
	SAN                 *SAN                 `json:"san,omitempty"`
	SubjectDA           *SubjectDA           `json:"subject_da,omitempty"`
	KeyUsages           *KeyUsages           `json:"key_usages,omitempty"`
	ExtendedKeyUsages   []string             `json:"extended_key_usages,omitempty"`
	QualifiedStatements *QualifiedStatements `json:"qualified_statements,omitempty"`
	MsExtensionTemplate *MsExtensionTemplate `json:"ms_extension_template,omitempty"`
	CustomExtensions    map[string]string    `json:"custom_extensions,omitempty"`
	Signature           *Signature           `json:"signature,omitempty"`
	PublicKey           string               `json:"public_key" validate:"required"`
	PublicKeySignature  string               `json:"public_key_signature,omitempty"`
}

IssueCertRequest is the base structure for certificate requests

func NewIssueCertRequest

func NewIssueCertRequest(csr []byte, certTemplate *x509.Certificate, opts *CertRequestOptions) (*IssueCertRequest, error)

NewIssueCertRequest calculates an Atlas Certificate request payload based on a CSR and x509 certificate acting as a template.

func (*IssueCertRequest) ValidateIssueCertRequest

func (req *IssueCertRequest) ValidateIssueCertRequest(vp ValidationPolicy) error

ValidateIssueCertRequest Compare request against Validation Policy and remove static/forbidden fields

type KeyUsagePolicy

type KeyUsagePolicy struct {
	ContentCommitment  string `json:"content_commitment"`
	CrlSign            string `json:"crl_sign"`
	DataEncipherment   string `json:"data_encipherment"`
	DecipherOnly       string `json:"decipher_only"`
	DigitalSignature   string `json:"digital_signature"`
	EncipherOnly       string `json:"encipher_only"`
	KeyAgreement       string `json:"key_agreement"`
	KeyCertificateSign string `json:"key_certificate_sign"`
	KeyEncipherment    string `json:"key_encipherment"`
}

Types requied to unmarshal Valiation Policy from HVCA

type KeyUsages

type KeyUsages struct {
	DigitalSignature   *bool `json:"digital_signature,omitempty"`
	ContentCommitment  *bool `json:"content_commitment,omitempty"`
	KeyEncipherment    *bool `json:"key_encipherment,omitempty"`
	DataEncipherment   *bool `json:"data_encipherment,omitempty"`
	KeyAgreement       *bool `json:"key_agreement,omitempty"`
	KeyCertificateSign *bool `json:"key_certificate_sign,omitempty"`
	CrlSign            *bool `json:"crl_sign,omitempty"`
	EncipherOnly       *bool `json:"encipher_only,omitempty"`
	DecipherOnly       *bool `json:"decipher_only,omitempty"`
}

KeyUsages defines how a certificate can be used within a certifcate request.

type ListPolicy

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

Types requied to unmarshal Valiation Policy from HVCA

type MockClient

type MockClient struct {
	OutError    error
	OutCert     *Certificate
	OutCertList []string
	OutPolicy   ValidationPolicy
}

func (*MockClient) GetCert

func (c *MockClient) GetCert(ctx context.Context, id string) (*Certificate, error)

GetCert gets the certificate for the provided serial number.

func (*MockClient) GetConfig

func (c *MockClient) GetConfig(ctx context.Context) (ValidationPolicy, error)

GetConfig gets the configuration profile for your Atlas Instance, Refer to the API documentation for more info.

func (*MockClient) GetTrustChain

func (c *MockClient) GetTrustChain(ctx context.Context) ([]string, error)

GetTrustChain returns the Certificate Authority chain used by the instance, output is an array of PEM encoded certs.

func (*MockClient) IssueCertificate

func (c *MockClient) IssueCertificate(ctx context.Context, req *IssueCertRequest) (*Certificate, error)

IssueCertificate will that the provided CSR and Parameters to request issuance of a certificate from your Atlas Instance.

Note that this issuance call actually performs a Issue then GET for convince.

func (*MockClient) Login

func (c *MockClient) Login(ctx context.Context) error

func (*MockClient) RevokeCert

func (c *MockClient) RevokeCert(ctx context.Context, id string) error

RevokeCert revokes the certificate with the provided serial number.

type MsExtensionTemplate

type MsExtensionTemplate struct {
	ID           string `json:"id,omitempty"`
	MajorVersion int    `json:"major_version,omitempty"`
	MinorVersion int    `json:"minor_version,omitempty"`
}

type QualifiedStatements

type QualifiedStatements struct {
	Semantics             *QualifiedStatementsSemantics `json:"semantics,omitempty"`
	EtsiQcCompliance      bool                          `json:"etsi_qc_compliance,omitempty"`
	EtsiQcType            string                        `json:"etsi_qc_type,omitempty"`
	EtsiQcSscdCompliance  bool                          `json:"etsi_qc_sscd_compliance,omitempty"`
	EtsiQcRetentionPeriod int                           `json:"etsi_qc_retention_period,omitempty"`
	EtsiQcPds             map[string]string             `json:"etsi_qc_pds,omitempty"`
}

type QualifiedStatementsSemantics

type QualifiedStatementsSemantics struct {
	Identifier      string   `json:"identifier,omitempty"`
	NameAuthorities []string `json:"name_authorities,omitempty"`
}

type SAN

type SAN struct {
	DNSNames    []string         `json:"dns_names,omitempty"`
	IPAddresses []string         `json:"ip_addresses,omitempty"`
	URIs        []string         `json:"uris,omitempty"`
	Emails      []string         `json:"emails,omitempty"`
	OtherNames  []*SANOtherNames `json:"other_names,omitempty"`
}

SAN represents Subject Alternative Names in a certificate request.

type SANOtherNames

type SANOtherNames struct {
	Type  string `json:"type"`
	Value string `json:"value,omitempty"`
}

SANOtherNames represents subject alternative names: other names in the certificate request.

type Signature

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

Signature represents the parameters used for generating the CSR within a Certificate Request

type SignaturePolicy

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

Types requied to unmarshal Valiation Policy from HVCA

type SimpleListPolicy

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

Types requied to unmarshal Valiation Policy from HVCA

type SubjectDA

type SubjectDA struct {
	Gender               string                     `json:"gender,omitempty"`
	DateOfBirth          string                     `json:"date_of_birth,omitempty"`
	PlaceOfBirth         string                     `json:"place_of_birth,omitempty"`
	CountryOfCitizenship []string                   `json:"country_of_citizenship,omitempty"`
	CountryOfResidence   []string                   `json:"country_of_residence,omitempty"`
	ExtraAttributes      []*SubjectDaExtraAttribute `json:"extra_attributes,omitempty"`
}

SubjectDA is used to define SubjectDA within a certificate request.

type SubjectDN

type SubjectDN struct {
	CommonName                                     string                     `json:"common_name,omitempty"`
	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"`
	Email                                          string                     `json:"email,omitempty"`
	JurisdictionOfIncorporationLocalityName        string                     `json:"jurisdiction_of_incorporation_locality_name,omitempty"`
	JurisdictionOfIncorporationStateOrProvinceName string                     `json:"jurisdiction_of_incorporation_state_or_province_name,omitempty"`
	JurisdictionOfIncorporationCountryName         string                     `json:"jurisdiction_of_incorporation_country_name,omitempty"`
	BusinessCategory                               string                     `json:"business_category,omitempty"`
	ExtraAttributes                                []*SubjectDnExtraAttribute `json:"extra_attributes,omitempty"`
}

SubjectDN represents the certificate SubjectDN within the Certificate request.

func NewSubjectDN

func NewSubjectDN(sub *pkix.Name) *SubjectDN

NewSubjectDN calculates the Subject DN payload based on the provided pkix.Name

type SubjectDaExtraAttribute

type SubjectDaExtraAttribute struct {
	Type  string `json:"type"`
	Value string `json:"value,omitempty"`
}

SubjectDaExtraAttribute is used for defining Extra SubjectDA within a certifcate request

type SubjectDnExtraAttribute

type SubjectDnExtraAttribute struct {
	Type  string `json:"type" validate:"required"`
	Value string `json:"value"`
}

SubjectDnExtraAttribute represents Extra Subject DN Attributes within a Certificate Request

type ValidationPolicy

type ValidationPolicy struct {
	ExtendedKeyUsages EKUPolicy       `json:"extended_key_usages,omitempty"`
	KeyUsages         KeyUsagePolicy  `json:"key_usages,omitempty"`
	Signature         SignaturePolicy `json:"signature,omitemtpy"`
}

Types requied to unmarshal Valiation Policy from HVCA

type Validity

type Validity struct {
	NotBefore int64 `json:"not_before" validate:"required"`
	NotAfter  int64 `json:"not_after,omitempty"`
}

Validity represents the valid time range for the Certificate request

Jump to

Keyboard shortcuts

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