tkesdk

Documentation

Index

• Constants
• func CheckTransition(ci CommonInputs, hc HsmConfig) ([]string, error)
• func CreateAdminCertForECKey(pemBytes []byte, savedSKI string, adminName string) ([]byte, error)
• func CreateAdminCertForRSAKey(pemBytes []byte, savedSKI string, adminName string) ([]byte, error)
• func CreateAdminCertFromFile(sigkey string, ski string, sigkeyToken string, adminName string) ([]byte, error)
• func GetSigKeySKI(sigkey string, sigkeyToken string) (string, error)
• func GetSignatureKeysFromResourceBlock(hc HsmConfig) (map[string]bool, map[string]string, map[string]string, map[string]string, ...)
• func SetDomainAttributes(authToken string, urlStart string, domain common.DomainEntry, newSigThr int, ...) error
• func Update(ci CommonInputs, hc HsmConfig) ([]string, error)
• func Zeroize(ci CommonInputs, hc HsmConfig) error
• type AdminInfo
• type CommonInputs
• type ECPublicKey
• type HsmConfig
• type HsmInfo
  • func Query(ci CommonInputs) ([]HsmInfo, error)
• type ReturnedAdminInfo

Constants

const XCP_ADMP_ZERO_1SIGN = 0x00000040

Permission bit to zeroize with one signature

Functions

func CheckTransition

func CheckTransition(ci CommonInputs, hc HsmConfig) ([]string, error)

----------------------------------------------------------------------------

Checks for invalid inputs and checks that the transition from initial
state to final state is possible.

Inputs:
CommonInputs -- A structure containing inputs needed for all TKE SDK
     functions.  This includes: the API endpoint and region, the HPCS
     service instance id, and an IBM Cloud authentication token.
HsmConfig -- A structure containing information from the hsm_config
     section of the resource block for the HPCS service instance.  This
     provides access to signature keys for signing commands to crypto
     units.

Outputs:
[]string -- set of messages identifying either an invalid input or a
     reason the transition from initial state to desired final state is
     not possible
error -- identifies any error encountered when running the function

----------------------------------------------------------------------------

func CreateAdminCertForECKey

func CreateAdminCertForECKey(pemBytes []byte, savedSKI string, adminName string) ([]byte, error)

----------------------------------------------------------------------------

Creates an administrator certificate containing a P521 EC public key
using the PEM representation of an EC private key.

Inputs:
[]byte pemBytes -- PEM encoded representation of EC private key
string savedSKI -- subject key identifier for the EC public key from the
    signature key file, represented as a hexadecimal string
string adminName -- administrator name

Outputs:
[]byte -- an administrator certificate containing the EC public key
error -- reports any errors

----------------------------------------------------------------------------

func CreateAdminCertForRSAKey

func CreateAdminCertForRSAKey(pemBytes []byte, savedSKI string, adminName string) ([]byte, error)

----------------------------------------------------------------------------

Creates an administrator certificate containing a 2048-bit RSA public key
using the PEM representation of an RSA private key.

Inputs:
[]byte pemBytes -- PEM encoded representation of RSA private key
string savedSKI -- subject key identifier for the RSA public key from the
    signature key file, represented as a hexadecimal string
string adminName -- administrator name

Outputs:
[]byte -- an administrator certificate containing the RSA public key
error -- reports any errors

----------------------------------------------------------------------------

func CreateAdminCertFromFile

func CreateAdminCertFromFile(sigkey string, ski string,
	sigkeyToken string, adminName string) ([]byte, error)

----------------------------------------------------------------------------

Creates an administrator certificate using the signature key in a file on
the local workstation.  The file can contain either a 2048-bit RSA key or
a P521 EC key.

Inputs:
string sigkey -- the full path and name of the signature key file
string ski -- the Subject Key Identifier of the signature key,
    represented as a hexadecimal string
string sigkeyToken -- the file password
string adminName -- administrator name

Outputs:
[]byte -- an administrator certificate containing the public key for the
    signature key
error -- reports any errors

----------------------------------------------------------------------------

func GetSigKeySKI

func GetSigKeySKI(sigkey string, sigkeyToken string) (string, error)

----------------------------------------------------------------------------

Returns the Subject Key Identifier (SKI) for a signature key.  Checks an
environment variable to determine whether a signing service should be used
or whether the signature key is in a signature key file on the local
workstation.

Inputs:
sigkey string -- a string identifying which signature key to access
sigkeyToken string -- associated authentication token for the signature
    key

Outputs:
string -- Subject Key Identifier for the signature key, represented as a
    hexadecimal string.
error -- reports any error during processing

----------------------------------------------------------------------------

func GetSignatureKeysFromResourceBlock

func GetSignatureKeysFromResourceBlock(hc HsmConfig) (map[string]bool,
	map[string]string, map[string]string, map[string]string, error)

----------------------------------------------------------------------------

Assembles information on the signature keys identified in the Terraform
resource block.

Handles both signature key files on the local workstation and a
user-provided signing service.

Inputs:
HsmConfig -- A structure containing information from the hsm_config
    section of the resource block for the HPCS service instance.  This
    provides access to the signature keys for signing commands.

Outputs:
map[string]bool -- set of the Subject Key Identifiers for the signature
    keys identified in the resource block.  maps SKI --> true.
map[string]string -- maps SKI --> signature key
map[string]string -- maps SKI --> signature key token
map[string]string -- maps SKI --> administrator name
error -- reports any error during processing

----------------------------------------------------------------------------

func SetDomainAttributes

func SetDomainAttributes(authToken string, urlStart string,
	domain common.DomainEntry, newSigThr int, newRevThr int,
	sigkeys []string, sigkeySkis []string, sigkeyTokens []string) error

----------------------------------------------------------------------------

Sets the domain attributes.  Different attributes are set for recovery
HSMs and operational HSMs.

Inputs:
PluginContext -- contains the IAM access token and parameters identifying
   what resource group the user is working with
DomainEntry -- identifies the domain whose attributes are to be set
int -- new signature threshold value to set
int -- new revocation signature threshold value to set
[]string -- identifies the signature keys to use to sign the command
[]string -- the Subject Key Identifiers for the signature keys
[]string -- authentication tokens for the signature keys

Output:
error -- reports any errors accessing the domain

----------------------------------------------------------------------------

func Update

func Update(ci CommonInputs, hc HsmConfig) ([]string, error)

----------------------------------------------------------------------------

Updates the crypto units in an HPCS service instance to match the desired
final configuration.

Inputs:
CommonInputs -- A structure containing inputs needed for all TKE SDK
     functions.  This includes: the API endpoint and region, the HPCS
     service instance id, and an IBM Cloud authentication token.
HsmConfig -- A structure containing information from the hsm_config
     section of the resource block for the HPCS service instance.  This
     provides access to signature keys for signing commands to crypto
     units.

Outputs:
[]string -- set of messages identifying either an invalid input or a
     reason the transition from initial state to desired final state is
     not possible
error -- identifies any error encountered when running the function

----------------------------------------------------------------------------

func Zeroize

func Zeroize(ci CommonInputs, hc HsmConfig) error

----------------------------------------------------------------------------

Zeroizes the crypto units assigned to a service instance, or returns an
error if that is not possible.

Inputs:
CommonInputs -- A structure containing inputs needed for all TKE SDK
     functions.  This includes: the API endpoint and region, the HPCS
     service instance id, and an IBM Cloud authentication token.
HsmConfig -- A structure containing information from the hsm_config
     section of the resource block for the HPCS service instance.  This
     provides access to signature keys for signing commands to crypto
     units.

----------------------------------------------------------------------------

Types

type AdminInfo

type AdminInfo struct {
	Name string
	Key  string
	// This identifies the administrator signature key to be used.
	// For initial development, this will be the fully qualified path
	// and file name of a signature key file.
	// When user-defined signing services are supported, the signing
	// service will define how this field is set.
	Token string
}

Structure describing administrators to be created or used

type CommonInputs

type CommonInputs struct {
	Region      string
	ApiEndpoint string
	AuthToken   string
	InstanceId  string
}

Structure containing common inputs to TKE SDK commands All TKE SDK commands need these inputs

type ECPublicKey

type ECPublicKey struct {
	X *big.Int
	Y *big.Int
}

* Used to work with an ASN.1 sequence representing an EC public key

type HsmConfig

type HsmConfig struct {
	SignatureThreshold  int
	RevocationThreshold int
	Admins              []AdminInfo
}

Structure representing the hsm_config section of a resource block

type HsmInfo

type HsmInfo struct {
	HsmId               string
	HsmLocation         string
	HsmType             string
	SignatureThreshold  int
	RevocationThreshold int
	Admins              []ReturnedAdminInfo
	NewMKStatus         string
	NewMKVP             string
	CurrentMKStatus     string
	CurrentMKVP         string
}

Structure containing information describing a crypto unit assigned to the service instance

func Query

func Query(ci CommonInputs) ([]HsmInfo, error)

----------------------------------------------------------------------------

Collects and returns information on how the crypto units assigned to a
service instance are configured.

----------------------------------------------------------------------------

type ReturnedAdminInfo

type ReturnedAdminInfo struct {
	AdminName string
	AdminSKI  string
}

Structure containing information on an installed administrator