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
- Variables
- func ExtractAPIError(resp []byte) error
- type APIError
- type Client
- func (c *Client) CagesClient(cageHostname string, pcrs []attestation.PCRs) (*http.Client, error)deprecated
- func (c *Client) CagesClientWithProvider(cageHostname string, pcrsProvider func() ([]attestation.PCRs, error)) (*http.Client, error)deprecated
- func (c *Client) CreateClientSideDecryptToken(payload any, expiry ...time.Time) (TokenResponse, error)
- func (c *Client) CreateFunctionRunToken(functionName string, payload any) (RunTokenResponse, error)
- func (c *Client) DecryptBool(encryptedData string) (bool, error)
- func (c *Client) DecryptByteArray(encryptedData string) ([]byte, error)deprecated
- func (c *Client) DecryptFloat64(encryptedData string) (float64, error)
- func (c *Client) DecryptInt(encryptedData string) (int, error)
- func (c *Client) DecryptString(encryptedData string) (string, error)
- func (c *Client) EnclaveClient(enclaveHostname string, pcrs []attestation.PCRs) (*http.Client, error)
- func (c *Client) EnclaveClientWithProvider(enclaveHostname string, pcrsProvider func() ([]attestation.PCRs, error)) (*http.Client, error)
- func (c *Client) EnclaveTCPConnectionWithProvider(enclaveHostname string, pcrsProvider func() ([]attestation.PCRs, error)) (func(ctx context.Context, network, addr string) (net.Conn, error), error)
- func (c *Client) EncryptBool(value bool) (string, error)
- func (c *Client) EncryptBoolWithDataRole(value bool, role string) (string, error)
- func (c *Client) EncryptByteArray(value []byte) (string, error)deprecated
- func (c *Client) EncryptByteArrayWithDataRole(value []byte, role string) (string, error)deprecated
- func (c *Client) EncryptFloat64(value float64) (string, error)
- func (c *Client) EncryptFloat64WithDataRole(value float64, role string) (string, error)
- func (c *Client) EncryptInt(value int) (string, error)
- func (c *Client) EncryptIntWithDataRole(value int, role string) (string, error)
- func (c *Client) EncryptString(value string) (string, error)
- func (c *Client) EncryptStringWithDataRole(value, role string) (string, error)
- func (c *Client) OutboundRelayClient() (*http.Client, error)
- func (c *Client) RunFunction(functionName string, payload map[string]any) (FunctionRunResponse, error)
- type Config
- type FunctionNotReadyError
- type FunctionRunResponse
- type FunctionRuntimeError
- type FunctionTimeoutError
- type KeysResponse
- type RunTokenResponse
- type TokenResponse
Constants ¶
const ClientVersion = "1.2.0"
Current version of the evervault SDK.
Variables ¶
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.
var ErrAttestionFailure = errors.New("attestation failed")
ErrAttestionFailure is retuned when a connection to a cage cannot be attested.
var ErrClientNotInitilization = errors.New("evervault client unable to initialize")
ErrClientNotInitilization is returned when Evervault client has not been initialized.
var ErrCryptoKeyImportError = errors.New("unable to import crypto key")
ErrCryptoKeyImportError is returned when the client is unable to the import Keys for crypto.
var ErrCryptoUnableToPerformEncryption = errors.New("unable to perform encryption")
ErrCryptoUnableToPerformEncryption is reutrned when the encryption function is unable to encrypt data.
var ErrInvalidDataType = errors.New("Error: Invalid datatype")
ErrInvalidDataType is returned when an unsupported data type was specified for encryption.
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.
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.
var ErrUnVerifiedSignature = errors.New("unable to verify certificate signature")
ErrUnVerifiedSignature is returned when a attestation docs signature cant be verified.
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
Types ¶
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
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
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
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
DecryptBool decrypts data previously encrypted with Encrypt or through Relay
decrypted := evClient.DecryptBool(encrypted);
func (*Client) DecryptByteArray
deprecated
added in
v1.0.0
func (*Client) DecryptFloat64 ¶ added in v1.0.0
DecryptFloat64 decrypts data previously encrypted with Encrypt or through Relay
decrypted := evClient.DecryptInt(encrypted);
func (*Client) DecryptInt ¶ added in v1.0.0
DecryptInt decrypts data previously encrypted with Encrypt or through Relay
decrypted := evClient.DecryptInt(encrypted);
func (*Client) DecryptString ¶ added in v1.0.0
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
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
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
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
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
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
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
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
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
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
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 ¶
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 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.