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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.