Skip to content

Latest commit

 

History

History
224 lines (184 loc) · 14.7 KB

README.md

File metadata and controls

224 lines (184 loc) · 14.7 KB
Raw

Go Client SDK for Keyfactor EJBCA

The Go Client SDK for Keyfactor EJBCA enables management of EJBCA resources utilizing the Go programming language.

Support for the Keyfactor EJBCA Go Client SDK

We welcome contributions.

The Keyfactor EJBCA Go Client SDK is open source and community supported, meaning that there is no SLA applicable for these tools.

To report a problem or suggest a new feature, use the Issues tab. If you want to contribute actual bug fixes or proposed enhancements, use the Pull requests tab.

Installation

Install the Go Client SDK for Keyfactor EJBCA using the go get command:

go get github.com/Keyfactor/ejbca-go-client-sdk

Put the package under your project folder and add the following in import:

import "github.com/Keyfactor/ejbca-go-client-sdk/api/ejbca"

Configuration

Communication with the EJBCA REST API is authenticated using mTLS (client certificate) or OAuth 2.0 (token). Authentication is handled via the ejbca.Authenticator interface, and the SDK ships with two default implementations, described below.

Both the mTLS and OAuth authenticators enable configuration of a CA Certificate if the target EJBCA server doesn't serve a certificate signed by a publically trusted root. Your application may elect to source this CA certificate via an appropriate authentication mechanism, or provide the appropriate authenticator builder with a path. Both methods are demonstrated below.

The following code snippets demonstrate how to configure the EJBCA client with an mTLS authenticator:

import (
    "crypto/x509"
    "fmt"
    "crypto/tls"

    "github.com/Keyfactor/ejbca-go-client-sdk/api/ejbca"
)

// Source the CA chain by an appropriate method for your application
caChain := []byte("<ca chain source by your application>")

caCerts, err := x509.ParseCertificates(caChain)
if err != nil {
    panic(err)
}

// Source the client certificate and key by an appropriate method for your application
clientCertificate := []byte("<client certificate source by your application>")
clientKey := []byte("<client key source by your application>")

tlsCert, err := tls.X509KeyPair(clientCertificate, clientKey)
if err != nil {
    panic(err)
}

authenticator, err := ejbca.NewMTLSAuthenticatorBuilder().
    WithClientCertificate(&tlsCert).
    WithCaCertificates(caCerts).
    Build()
if err != nil {
    panic(err)
}

The ejbca.MTLSAuthenticatorBuilder can also source the client certificate, key and CA certificate from a provided path. It's important that the certificates at the specified paths be PEM encoded X.509 certificates, and the private key must be an unencrypted PKCS#8 key.

import "github.com/Keyfactor/ejbca-go-client-sdk/api/ejbca"

authenticator, err := ejbca.NewMTLSAuthenticatorBuilder().
    WithClientCertificatePath("<path to client certificate>").
    WithClientCertificateKeyPath("<path to client key>").
    WithCaCertificatePath("<path to ca certificate>").
    Build()
if err != nil {
    panic(err)
}

OAuth2.0 is configured using the ejbca.OAuthAuthenticatorBuilder. Under the hood, this authenticator uses the golang.org/x/oauth2/clientcredentials package to implement the OAuth2.0 "client credentials" token flow, since the client is acting on its own behalf.

import "github.com/Keyfactor/ejbca-go-client-sdk/api/ejbca"

authenticator, err := ejbca.NewOAuthAuthenticatorBuilder().
    WithCaCertificates(caCerts).
//  WithCaCertificatePath("<path to ca certificate>").
    WithTokenUrl("<url to token endpoint>").
    WithClientId("<client ID>").
    WithClientSecret("<client secret>").
    WithAudience("<optional audience").
    WithScopes("<optional scopes>").
    Build()
if err != nil {
    panic(err)
}

Finally, the EJBCA client is configured with the authenticator and the hostname of the EJBCA server:

import "github.com/Keyfactor/ejbca-go-client-sdk/api/ejbca"

configuration := ejbca.NewConfiguration()
configuration.Host = "<hostname>:<optional port>"
configuration.SetAuthenticator(authenticator)

ejbcaClient, err := ejbca.NewAPIClient(configuration)
if err != nil {
    panic(err)
}

If neither authentication mechanism is suitable for your application, you can implement your own authenticator by implementing the ejbca.Authenticator interface.

Documentation for API Endpoints

All URIs are relative to http://localhost/ejbca/ejbca-rest-api

Class Method HTTP request Description
V1CaApi CreateCrl Post /v1/ca/{issuer_dn}/createcrl Create CRL(main, partition and delta) issued by this CA
V1CaApi GetCertificateAsPem Get /v1/ca/{subject_dn}/certificate/download Get PEM file with the active CA certificate chain
V1CaApi GetLatestCrl Get /v1/ca/{issuer_dn}/getLatestCrl Returns the latest CRL issued by this CA
V1CaApi ImportCrl Post /v1/ca/{issuer_dn}/importcrl Import a certificate revocation list (CRL) for a CA
V1CaApi ListCas Get /v1/ca Returns the Response containing the list of CAs with general information per CA as Json
V1CaApi Status1 Get /v1/ca/status Get the status of this REST Resource
V1CaManagementApi Activate Put /v1/ca_management/{ca_name}/activate Activate a CA
V1CaManagementApi Deactivate Put /v1/ca_management/{ca_name}/deactivate Deactivate a CA
V1CaManagementApi Status Get /v1/ca_management/status Get the status of this REST Resource
V1CertificateApi CertificateRequest Post /v1/certificate/certificaterequest Enrollment with client generated keys for an existing End Entity
V1CertificateApi EnrollKeystore Post /v1/certificate/enrollkeystore Keystore enrollment
V1CertificateApi EnrollPkcs10Certificate Post /v1/certificate/pkcs10enroll Enrollment with client generated keys, using CSR subject
V1CertificateApi FinalizeEnrollment Post /v1/certificate/{request_id}/finalize Finalize enrollment
V1CertificateApi GetCertificatesAboutToExpire Get /v1/certificate/expire Get a list of certificates that are about to expire
V1CertificateApi RevocationStatus Get /v1/certificate/{issuer_dn}/{certificate_serial_number}/revocationstatus Checks revocation status of the specified certificate
V1CertificateApi RevokeCertificate Put /v1/certificate/{issuer_dn}/{certificate_serial_number}/revoke Revokes the specified certificate
V1CertificateApi SearchCertificates Post /v1/certificate/search Searches for certificates confirming given criteria.
V1CertificateApi Status2 Get /v1/certificate/status Get the status of this REST Resource
V1ConfigdumpApi GetJsonConfigdump Get /v1/configdump Get the configuration in JSON.
V1ConfigdumpApi GetJsonConfigdumpForType Get /v1/configdump/{type} Get the configuration for type in JSON.
V1ConfigdumpApi GetJsonConfigdumpForTypeAndSetting Get /v1/configdump/{type}/{setting} Get the configuration for a type and setting in JSON.
V1ConfigdumpApi GetZipExport Get /v1/configdump/configdump.zip Get the configuration as a ZIP file.
V1ConfigdumpApi PostJsonImport Post /v1/configdump Put the configuration in JSON.
V1ConfigdumpApi PostZipImport Post /v1/configdump/configdump.zip Put the configuration as a ZIP file.
V1ConfigdumpApi Status4 Get /v1/configdump/status Get the status of this REST Resource
V1CryptotokenApi Activate1 Put /v1/cryptotoken/{cryptotoken_name}/activate Activate a Crypto Token
V1CryptotokenApi Deactivate1 Put /v1/cryptotoken/{cryptotoken_name}/deactivate Deactivate a Crypto Token
V1CryptotokenApi GenerateKeys Post /v1/cryptotoken/{cryptotoken_name}/generatekeys Generate keys
V1CryptotokenApi RemoveKeys Post /v1/cryptotoken/{cryptotoken_name}/{key_pair_alias}/removekeys Remove keys
V1CryptotokenApi Status5 Get /v1/cryptotoken/status Get the status of this REST Resource
V1EndentityApi Add Post /v1/endentity Add new end entity, if it does not exist
V1EndentityApi Delete Delete /v1/endentity/{endentity_name} Deletes end entity
V1EndentityApi Revoke Put /v1/endentity/{endentity_name}/revoke Revokes all end entity certificates
V1EndentityApi Search Post /v1/endentity/search Searches for end entity confirming given criteria.
V1EndentityApi Setstatus Post /v1/endentity/{endentity_name}/setstatus Edits end entity setting new status
V1EndentityApi Status6 Get /v1/endentity/status Get the status of this REST Resource
V1SshApi Pubkey Get /v1/ssh/{ca_name}/pubkey Retrieves a CA's public key in SSH format.
V1SshApi Status8 Get /v1/ssh/status Get the status of this REST Resource
V2CertificateApi GetCertificateProfileInfo Get /v2/certificate/profile/{profile_name} Get Certificate Profile Info.
V2CertificateApi SearchCertificates1 Post /v2/certificate/search Searches for certificates confirming given criteria and pagination.
V2CertificateApi Status3 Get /v2/certificate/status Get the status of this REST Resource
V2EndentityApi GetAuthorizedEndEntityProfiles Get /v2/endentity/profiles/authorized List of authorized end entity profiles for the current admin.
V2EndentityApi Profile Get /v2/endentity/profile/{endentity_profile_name} Get End Entity Profile content
V2EndentityApi SortedSearch Post /v2/endentity/search Searches and sorts for end entity conforming given criteria.
V2EndentityApi Status7 Get /v2/endentity/status Get the status of this REST Resource

Documentation For Models

Application Notes

This API client was generated by the OpenAPI Generator project. By using the OpenAPI-spec from a remote server, you can easily generate an API client.

  • API version: 1.0
  • Package version: 1.0.0
  • Build package: org.openapitools.codegen.languages.GoClientCodegen