evervault

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: May 14, 2024 License: MIT Imports: 24 Imported by: 0

README

Evervault

Evervault Go SDK

Go Report Card Go Reference

For up to date usage docs please refer to Evervault docs and godocs

Testing

To Test the sdk run

go test -v -count=1 -race ./...
Linting

Linting is run on all PR with golangci-lint.

To test locally you can run

golangci-lint run ./...

Documentation

Overview

Evervault Go SDK. Supported functions are:

  • Encrypt data server-side including files
  • Invoke Functions
  • Invoke Cages
  • Proxy requests through Outbound Relay

For up to date usage docs please refer to Evervault docs

Index

Constants

View Source 
const ClientVersion = "1.2.0"

Current version of the evervault SDK.

Variables

View Source 
var ErrAppCredentialsRequired = errors.New("evervault client requires an api key and app uuid")

ErrAppCredentialsRequired is returned when the required application credentials for initialisation are missing.

View Source 
var ErrAttestionFailure = errors.New("attestation failed")

ErrAttestionFailure is retuned when a connection to a cage cannot be attested.

View Source 
var ErrClientNotInitilization = errors.New("evervault client unable to initialize")

ErrClientNotInitilization is returned when Evervault client has not been initialized.

View Source 
var ErrCryptoKeyImportError = errors.New("unable to import crypto key")

ErrCryptoKeyImportError is returned when the client is unable to the import Keys for crypto.

View Source 
var ErrCryptoUnableToPerformEncryption = errors.New("unable to perform encryption")

ErrCryptoUnableToPerformEncryption is reutrned when the encryption function is unable to encrypt data.

View Source 
var ErrInvalidDataType = errors.New("Error: Invalid datatype")

ErrInvalidDataType is returned when an unsupported data type was specified for encryption.

View Source 
var ErrInvalidPCRProvider = errors.New("unsupported type, must be array or callback: func() ([]types.PCRs, error)")

ErrInvalidPCRProvider is returned when an invalid PCR provider type is passed to CagesClient.

View Source 
var ErrNoPCRs = errors.New("Error: no PCRs where provided to attest with")

ErrNoPCRs is returned when a PCRs is created without any PCR in it to attest with.

View Source 
var ErrUnVerifiedSignature = errors.New("unable to verify certificate signature")

ErrUnVerifiedSignature is returned when a attestation docs signature cant be verified.

View Source 
var ErrUnsupportedNetworkType = errors.New("error: unsupported network type")

ErrUnsupportedNetworkType is returned when an unsupported network type was supplied. Only TCP is supported for Enclaves.

Functions

func ExtractAPIError added in v1.0.0 

func ExtractAPIError(resp []byte) error

Types

type APIError 

type APIError struct {
	Code    string `json:"code"`
	Message string `json:"detail"`
}

APIError represents an error returned from the Evervault API servers.

func (APIError) Error 

func (e APIError) Error() string

type Client 

type Client struct {
	Config Config
	// contains filtered or unexported fields
}

Evervault Client. Client will connect to Evervault API and retrieve public key. The Client can be used to:

  • perform encryptions
  • Create Outbound relay client
  • Create Cage clients
  • run evervault Functions.

func MakeClient added in v0.1.2 

func MakeClient(appUUID, apiKey string) (*Client, error)

MakeClient creates a new Client instance if an API key and Evervault App ID is provided. The client will connect to Evervaults API to retrieve the public keys from your Evervault App. 

import "github.com/evervault/evervault-go"
evClient, err := evervault.MakeClient("<API_KEY>", "<APP_UUID>")

If an apiKey is not passed then ErrAppCredentialsRequired is returned. If the client cannot be created then nil will be returned.

func MakeCustomClient added in v0.1.2 

func MakeCustomClient(appUUID, apiKey string, config Config) (*Client, error)

MakeCustomClient creates a new Client instance but can be specified with a Config. The client will connect to Evervaults API to retrieve the public keys from your Evervault App.

If an apiKey or appUUID is not passed then ErrAppCredentialsRequired is returned. If the client cannot be created then nil will be returned.

func (*Client) CagesClient deprecated added in v0.5.0 

func (c *Client) CagesClient(cageHostname string, pcrs []attestation.PCRs) (*http.Client, error)

Will return a http.Client that is connected to a specified cage hostname with a fully attested client. The Client will attest the connection every time it makes a HTTP request and will return an error on request if it fails attestation 

cageURL = "<CAGE_NAME>.<APP_UUID>.cages.evervault.com"
expectedPCRs := evervault.PCRs{
	PCR0: "f039c31c536749ac6b2a9344fcb36881dd1cf066ca44afcaf9369a9877e2d3c85fa738c427d502e01e35994da7458e2d",
	PCR1: "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f",
	PCR2: "71c478711438fe252fbd9b1da56218bea5d630da55aa56431257df77bd42f65a434601bf53be9a1901fcd61680e425c7",
	PCR8: "1650274b27bf44fba6f1779602399763af9e4567927d771b1b37aeb1ac502c84fbd6a7ab7b05600656a257247529fbb8",
}

cageClient, err := evClient.CagesClient(cageURL, []evervault.PCRs{expectedPCRs})
if err != nil {
	log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
	log.Fatal(err)
}

req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("https://%s/", cageURL), bytes.NewBuffer(payload))
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := cageClient.Do(req)

Deprecated: Use EnclaveClient instead.

func (*Client) CagesClientWithProvider deprecated added in v1.0.0 

func (c *Client) CagesClientWithProvider(cageHostname string,
	pcrsProvider func() ([]attestation.PCRs, error),
) (*http.Client, error)

Will return a http.Client that is connected to a specified cage hostname with a fully attested client. Specify a callback to be polled periodically to pick up the latest PCRs to attest with. The Client will attest the connection every time it makes a HTTP request and will return an error on request if it fails attestation 

cageURL = "<CAGE_NAME>.<APP_UUID>.cages.evervault.com"
func GetPCRs() ([]attestation.PCRs, error) {
	// logic to get PCRs
	return pcrs, nil
}

cageClient, err := evClient.CagesClientWithProvider(cageURL, GetPCRs)
if err != nil {
	log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
	log.Fatal(err)
}

req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("https://%s/", cageURL), bytes.NewBuffer(payload))
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := cageClient.Do(req)

Deprecated: Use EnclaveClientWithProvider instead.

func (*Client) CreateClientSideDecryptToken added in v0.4.0 

func (c *Client) CreateClientSideDecryptToken(payload any, expiry ...time.Time) (TokenResponse, error)

CreateClientSideDecryptToken creates a time bound token that can be used to perform decrypts. The payload is required and ensures the token can only be used to decrypt that specific payload.

The expiry is the time the token should expire. The max time is 10 minutes in the future and defaults to 5 minutes if not provided.

It returns a TokenResponse or an error

token, err := CreateClientSideDecryptToken(payload, timeInFiveMinutes).

func (*Client) CreateFunctionRunToken 

func (c *Client) CreateFunctionRunToken(functionName string, payload any) (RunTokenResponse, error)

Passing the name of your Evervault Function along with the data to be sent to that function will return a RunTokenResponse. This response contains a token that can be returned to your client for Function invocation.

func (*Client) DecryptBool added in v1.0.0 

func (c *Client) DecryptBool(encryptedData string) (bool, error)

DecryptBool decrypts data previously encrypted with Encrypt or through Relay 

decrypted := evClient.DecryptBool(encrypted);

func (*Client) DecryptByteArray deprecated added in v1.0.0 

func (c *Client) DecryptByteArray(encryptedData string) ([]byte, error)

DecryptByteArray decrypts data previously encrypted with Encrypt or through Relay 

decrypted := evClient.DecryptByteArray(encrypted);

Deprecated: Use DecryptString for utf-8 encoded encrypted byte arrays.

func (*Client) DecryptFloat64 added in v1.0.0 

func (c *Client) DecryptFloat64(encryptedData string) (float64, error)

DecryptFloat64 decrypts data previously encrypted with Encrypt or through Relay 

decrypted := evClient.DecryptInt(encrypted);

func (*Client) DecryptInt added in v1.0.0 

func (c *Client) DecryptInt(encryptedData string) (int, error)

DecryptInt decrypts data previously encrypted with Encrypt or through Relay 

decrypted := evClient.DecryptInt(encrypted);

func (*Client) DecryptString added in v1.0.0 

func (c *Client) DecryptString(encryptedData string) (string, error)

DecryptString decrypts data previously encrypted with Encrypt or through Relay 

decrypted := evClient.Decrypt(encrypted);

func (*Client) EnclaveClient added in v1.1.0 

func (c *Client) EnclaveClient(enclaveHostname string, pcrs []attestation.PCRs) (*http.Client, error)

Will return a http.Client that is connected to a specified enclave hostname with a fully attested client. The Client will attest the connection every time it makes a HTTP request and will return an error on request if it fails attestation 

enclaveURL = "<ENCLAVE_NAME>.<APP_UUID>.enclave.evervault.com"
expectedPCRs := evervault.PCRs{
	PCR0: "f039c31c536749ac6b2a9344fcb36881dd1cf066ca44afcaf9369a9877e2d3c85fa738c427d502e01e35994da7458e2d",
	PCR1: "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f",
	PCR2: "71c478711438fe252fbd9b1da56218bea5d630da55aa56431257df77bd42f65a434601bf53be9a1901fcd61680e425c7",
	PCR8: "1650274b27bf44fba6f1779602399763af9e4567927d771b1b37aeb1ac502c84fbd6a7ab7b05600656a257247529fbb8",
}

enclaveClient, err := evClient.EnclaveClient(enclaveURL, []evervault.PCRs{expectedPCRs})
if err != nil {
	log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
	log.Fatal(err)
}

req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("https://%s/", enclaveURL), bytes.NewBuffer(payload))
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := enclaveClient.Do(req)

func (*Client) EnclaveClientWithProvider added in v1.1.0 

func (c *Client) EnclaveClientWithProvider(
	enclaveHostname string,
	pcrsProvider func() ([]attestation.PCRs, error),
) (*http.Client, error)

Will return an http.Client that is connected to a specified enclave hostname with a fully attested client. Specify a callback to be polled periodically to pick up the latest PCRs to attest with. The Client will attest the connection every time it makes a HTTP request and will return an error on request if it fails attestation 

enclaveURL = "<ENCLAVE_NAME>.<APP_UUID>.enclave.evervault.com"
func GetPCRs() ([]attestation.PCRs, error) {
	// logic to get PCRs
	return pcrs, nil
}

enclaveClient, err := evClient.EnclaveClientWithProvider(enclaveURL, GetPCRs)
if err != nil {
	log.Fatal(err)
}

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
	log.Fatal(err)
}

req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("https://%s/", enclaveURL), bytes.NewBuffer(payload))
req.Close = true
req.Header.Set("API-KEY", "<API_KEY>")
req.Header.Set("Content-Type", "application/json; charset=UTF-8")

resp, err := enclaveClient.Do(req)

func (*Client) EnclaveTCPConnectionWithProvider added in v1.1.0 

func (c *Client) EnclaveTCPConnectionWithProvider(
	enclaveHostname string,
	pcrsProvider func() ([]attestation.PCRs, error),
) (func(ctx context.Context, network, addr string) (net.Conn, error), error)

Will return a http.Client that is connected to a specified enclave hostname with a fully attested client. The Client will attest the connection every time it makes a HTTP request and will return an error on request if it fails attestation 

	enclaveURL = "<ENCLAVE_NAME>.<APP_UUID>.enclave.evervault.com"

	func GetPCRs() ([]attestation.PCRs, error) {
		// logic to get PCRs
		return evervault.PCRs{
			PCR0: "f039c31c536749ac6b2a9344fcb36881dd1cf066ca44afcaf9369a9877e2d3c85fa738c427d502e01e35994da7458e2d",
			PCR1: "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f",
			PCR2: "71c478711438fe252fbd9b1da56218bea5d630da55aa56431257df77bd42f65a434601bf53be9a1901fcd61680e425c7",
			PCR8: "1650274b27bf44fba6f1779602399763af9e4567927d771b1b37aeb1ac502c84fbd6a7ab7b05600656a257247529fbb8",
		}, nil
	}

	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	enclaveDial, err := evClient.EnclaveTCPConnectionWithProvider(enclaveURL, GetPCRs)
	if err != nil {
		log.Fatal(err)
	}

	conn, err := enclaveDial(ctx, "tcp", enclaveURL)
	if err != nil {
		log.Fatal(err)
	}

	defer conn.Close()

	if _, err := conn.Write([]byte("Hello, World!")); err != nil {
 	log.Fatal(err)
	}

func (*Client) EncryptBool added in v1.0.0 

func (c *Client) EncryptBool(value bool) (string, error)

EncryptBool encrypts the value passed to it using the Evervault Encryption Scheme. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptBool(true);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptBoolWithDataRole added in v1.0.0 

func (c *Client) EncryptBoolWithDataRole(value bool, role string) (string, error)

EncryptBool encrypts the value passed to it using the Evervault Encryption Scheme. The data role included is embedded in the encrypted string and can be used to control access to the data. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptBool(true);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptByteArray deprecated added in v1.0.0 

func (c *Client) EncryptByteArray(value []byte) (string, error)

EncryptByteArray encrypts the value passed to it using the Evervault Encryption Scheme. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptByteArray([]byte("Hello, world!"));

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For any other error ErrCryptoUnableToPerformEncryption is returned.

Deprecated: Use EncryptString for utf-8 encoded byte arrays.

func (*Client) EncryptByteArrayWithDataRole deprecated added in v1.0.0 

func (c *Client) EncryptByteArrayWithDataRole(value []byte, role string) (string, error)

EncryptByteArray encrypts the value passed to it using the Evervault Encryption Scheme. The data role included is embedded in the encrypted string and can be used to control access to the data. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptByteArray([]byte("Hello, world!"));

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For any other error ErrCryptoUnableToPerformEncryption is returned.

Deprecated: Use EncryptString for utf-8 encoded byte arrays.

func (*Client) EncryptFloat64 added in v1.0.0 

func (c *Client) EncryptFloat64(value float64) (string, error)

EncryptFloat64 encrypts the value passed to it using the Evervault Encryption Scheme. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptInt(100.1);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptFloat64WithDataRole added in v1.0.0 

func (c *Client) EncryptFloat64WithDataRole(value float64, role string) (string, error)

EncryptFloat64 encrypts the value passed to it using the Evervault Encryption Scheme. The data role included is embedded in the encrypted string and can be used to control access to the data. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptInt(100.1);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptInt added in v1.0.0 

func (c *Client) EncryptInt(value int) (string, error)

EncryptInt encrypts the value passed to it using the Evervault Encryption Scheme. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptInt(100);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptIntWithDataRole added in v1.0.0 

func (c *Client) EncryptIntWithDataRole(value int, role string) (string, error)

EncryptInt encrypts the value passed to it using the Evervault Encryption Scheme. The data role included is embedded in the encrypted string and can be used to control access to the data. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptInt(100);

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptString added in v1.0.0 

func (c *Client) EncryptString(value string) (string, error)

EncryptString encrypts the value passed to it using the Evervault Encryption Scheme. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptString("Hello, world!");

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) EncryptStringWithDataRole added in v1.0.0 

func (c *Client) EncryptStringWithDataRole(value, role string) (string, error)

EncryptString encrypts the value passed to it using the Evervault Encryption Scheme. The data role included is embedded in the encrypted string and can be used to control access to the data. The encrypted value is returned as an Evervault formatted encrypted string. 

encrypted := evClient.EncryptString("Hello, world!");

If an error occurs then nil is returned. If the error is due a problem with Key creation then ErrCryptoKeyImportError is returned. For anyother error ErrCryptoUnableToPerformEncryption is returned.

func (*Client) OutboundRelayClient 

func (c *Client) OutboundRelayClient() (*http.Client, error)

Will return a http.Client that is configured to use the Evervault Relay as a proxy, enabling decryption of data before it reaches the requests destination. 

outboundRelayClient, err := evClient.OutboundRelayClient()

payload, err := json.Marshal(fmt.Sprintf(`{"encrypted": "%s"}`, encrypted))
if err != nil {
  log.Fatal(err)
}

resp, err := outboundRelayClient.Post("https://example.com/", "application/json", bytes.NewBuffer(payload))

func (*Client) RunFunction 

func (c *Client) RunFunction(functionName string, payload map[string]any) (FunctionRunResponse, error)

Passing the name of your Evervault Function along with the data to be sent to that function will invoke a function in your Evervault App. The response from the function will be returned as a FunctionRunResponse.

type Config 

type Config struct {
	EvervaultCaURL             string        // URL for the Evervault CA.
	EvervaultCagesCaURL        string        // URL for the Evervault Cages CA.
	RelayURL                   string        // URL for the Evervault Relay.
	EvAPIURL                   string        // URL for the Evervault API.
	CagesPollingInterval       time.Duration // Polling interval for obtaining fresh attestation doc in seconds
	AttestationPollingInterval time.Duration // Polling interval for obtaining fresh attestation doc in seconds
}

Config holds the configuration for the Evervault Client.

func MakeConfig 

func MakeConfig() Config

MakeConfig loads the Evervault client configuration from environment variables. It falls back to default values if the environment variables are not set.

type FunctionNotReadyError added in v1.0.0 

type FunctionNotReadyError struct {
	Message string
}

FunctionNotReadyError is returned when the Function is not ready to be invoked yet. This can occur when it hasn't been executed in a while. Retrying to run the Function after a short time should resolve this.

func (FunctionNotReadyError) Error added in v1.0.0 

func (e FunctionNotReadyError) Error() string

type FunctionRunResponse 

type FunctionRunResponse struct {
	Status string         `json:"status"`
	ID     string         `json:"id"`
	Result map[string]any `json:"result"`
}

Response containing the results of a Function run. - FunctionRunResponse.Status contains the status of the function invocation (success/failure). - FunctionRunResponse.ID contains the run ID of the function invocation. - FunctionRunResponse.Result contains the response from the function invocation.

type FunctionRuntimeError added in v1.0.0 

type FunctionRuntimeError struct {
	Status    string `json:"status"`
	ErrorBody struct {
		Message string `json:"message"`
		Stack   string `json:"stack"`
	} `json:"error"`
	ID string `json:"id"`
}

FunctionRuntimeError is returned when an error is thrown during the function invocation.

func (FunctionRuntimeError) Error added in v1.0.0 

func (e FunctionRuntimeError) Error() string

type FunctionTimeoutError added in v1.0.0 

type FunctionTimeoutError struct {
	Message string
}

FunctionTimeoutError is returned when a function invocation times out.

func (FunctionTimeoutError) Error added in v1.0.0 

func (e FunctionTimeoutError) Error() string

type KeysResponse 

type KeysResponse struct {
	TeamUUID                string `json:"teamUuid"`
	Key                     string `json:"key"`
	EcdhKey                 string `json:"ecdhKey"`
	EcdhP256Key             string `json:"ecdhP256Key"`
	EcdhP256KeyUncompressed string `json:"ecdhP256KeyUncompressed"`
}

type RunTokenResponse 

type RunTokenResponse struct {
	Token string `json:"token"`
}

Struct containing a token for Function invocation. RunTokenResponse.Token can be used to invoke a function run by the user.

type TokenResponse added in v0.4.0 

type TokenResponse struct {
	Token  string `json:"token"`
	Expiry int64  `json:"expiry"`
}

Source Files

View all Source files

Directories

Path Synopsis
internal
attestation
crypto
datatypes

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.