tsc

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

Go CI Go Reference

Tenant Security Client Go Library

A Go client for implementing CMK within a vendor's infrastructure. Makes requests through an IronCore Tenant Security Proxy to tenants' KMS/logging infrastructures.

Getting started

A good place to start is the TenantSecurityClient class, which is what the consumer should always interact with. You can also go check out the examples.

If you're looking for more examples the usage is very similar to that shown in our Java Examples.

Copyright (c) 2022 IronCore Labs, Inc. All rights reserved.

Documentation

Overview

tsc is the REST client for the IronCore Tenant Security Proxy. This client uses the TSP to perform encryption, decryption, and security logging.

Index

Constants

View Source 
const Version = "v0.4.0"

Variables

View Source 
var (
	ErrKindUnknown       = &Error{Kind: errorKindUnknown}
	ErrKindTSPService    = &Error{Kind: errorKindTSPService}
	ErrKindSecurityEvent = &Error{Kind: errorKindSecurityEvent}
	ErrKindKMS           = &Error{Kind: errorKindKMS}
	ErrKindCrypto        = &Error{Kind: errorKindCrypto}
	ErrKindNetwork       = &Error{Kind: errorKindNetwork}
	ErrKindLocal         = &Error{Kind: errorKindLocal}
)

*

  • These are kinds of errors. Use errors.Is to see if a specific error is of this kind.
View Source 
var (
	ErrUnknownError                             = &Error{Kind: errorKindTSPService, Code: 100}
	ErrUnauthorizedRequest                      = &Error{Kind: errorKindTSPService, Code: 101}
	ErrInvalidRequestBody                       = &Error{Kind: errorKindTSPService, Code: 102}
	ErrNoPrimaryKMSConfiguration                = &Error{Kind: errorKindKMS, Code: 200}
	ErrUnknownTenantOrNoActiveKMSConfigurations = &Error{Kind: errorKindKMS, Code: 201}
	ErrKmsConfigurationDisabled                 = &Error{Kind: errorKindKMS, Code: 202}
	ErrInvalidProvidedEDEK                      = &Error{Kind: errorKindKMS, Code: 203}
	ErrKmsWrapFailed                            = &Error{Kind: errorKindKMS, Code: 204}
	ErrKmsUnwrapFailed                          = &Error{Kind: errorKindKMS, Code: 205}
	ErrKmsAuthorizationFailed                   = &Error{Kind: errorKindKMS, Code: 206}
	ErrKmsConfigurationInvalid                  = &Error{Kind: errorKindKMS, Code: 207}
	ErrKmsUnreachable                           = &Error{Kind: errorKindKMS, Code: 208}
	ErrKmsThrottled                             = &Error{Kind: errorKindKMS, Code: 209}
	ErrKmsAccountIssue                          = &Error{Kind: errorKindKMS, Code: 210}
	ErrSecurityEventRejected                    = &Error{Kind: errorKindSecurityEvent, Code: 301}
)

*

  • These are specific coded errors that can be received from the TSP. Use errors.Is to compare
  • against them.

Functions

This section is empty.

Types

type Base64Bytes 

type Base64Bytes struct {
	Bytes []byte
}

Base64Bytes represents the base64-encoded bytes sent to/from the Tenant Security Proxy.

func (Base64Bytes) MarshalJSON 

func (b Base64Bytes) MarshalJSON() ([]byte, error)

func (*Base64Bytes) UnmarshalJSON 

func (b *Base64Bytes) UnmarshalJSON(data []byte) error

type BatchDecryptedDocuments 

type BatchDecryptedDocuments struct {
	Documents map[string]DecryptedDocument
	Failures  map[string]error
}

BatchDecryptedDocuments contains a map from document ID to successfully decrypted document and a separate map from document ID to an error.

type BatchEncryptedDocuments 

type BatchEncryptedDocuments struct {
	Documents map[string]EncryptedDocument
	Failures  map[string]error
}

BatchEncryptedDocuments contains a map from document ID to successfully encrypted document and a separate map from document ID to an error.

type DecryptedDocument 

type DecryptedDocument struct {
	DecryptedFields map[string][]byte
	Edek            Edek
}

DecryptedDocument is a document that has been decrypted by the TenantSecurityClient. It contains a map from field name/ID to the decrypted bytes, and the encrypted document encryption key (EDEK) used for decryption.

type Dek 

type Dek = Base64Bytes

Dek is the Document Encryption Key generated by the Tenant Security Proxy.

type Edek 

type Edek = Base64Bytes

Edek is the Encrypted Document Encryption Key generated by the Tenant Security Proxy.

type EncryptedDocument 

type EncryptedDocument struct {
	EncryptedFields map[string][]byte `json:"encryptedFields"`
	Edek            Edek              `json:"edek"`
}

EncryptedDocument is a document that has been encrypted by the TenantSecurityClient. It contains a map from field name/ID to the encrypted bytes, and the encrypted document encryption key (EDEK) necessary for decryption.

type Error 

type Error struct {
	Kind    ErrorKind
	Code    ErrorCode
	Message string
	// contains filtered or unexported fields
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(target error) bool

func (*Error) UnmarshalJSON 

func (e *Error) UnmarshalJSON(data []byte) error

UnmarshalJSON will unmarshal the Code and Message, then set the error's Kind.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorCode 

type ErrorCode int

type ErrorKind 

type ErrorKind int

type EventMetadata 

type EventMetadata struct {
	// Time when the event occurred.
	TimestampMillis time.Time `json:"timestampMillis"`
	RequestMetadata
}

EventMetadata is metadata associated with the LogSecurityEvent function. It is the same as RequestMetadata with the addition of the time at which the event occurred.

type IclFields 

type IclFields struct {
	// RequestingID (required) is the unique ID of user/service that is processing data.
	RequestingID string `json:"requestingId"`
	// DataLabel (optional) is the classification of data being processed.
	DataLabel string `json:"dataLabel,omitempty"`
	// SourceIP (optional) is the IP address of the initiator of this document request.
	SourceIP string `json:"sourceIp,omitempty"`
	// ObjectID (optional) is the ID of the object/document being acted on in the host system.
	ObjectID string `json:"objectId,omitempty"`
	// RequestID (optional) is the unique ID that ties the application request ID to Tenant Security Proxy logs.
	RequestID string `json:"requestId,omitempty"`
}

IclFields holds metadata to pass to the Tenant Security Proxy for logging purposes.

type PlaintextDocument 

type PlaintextDocument = map[string][]byte

PlaintextDocument is a map from field name/ID to the field's bytes.

type RequestMetadata 

type RequestMetadata struct {
	// TenantID is the unique ID of the tenant the action is being performed for.
	TenantID string `json:"tenantId"`
	// IclFields is metadata about the request for the Tenant Security Proxy to log.
	IclFields IclFields `json:"iclFields"`
	// CustomFields is optional additional information for the Tenant Security Proxy to log.
	CustomFields map[string]string `json:"customFields"`
}

RequestMetadata holds metadata fields as part of a request. Each request has metadata associated with it that will be sent to the Tenant Security Proxy for logging and other purposes. Some examples include the tenant ID associated with the request, the service that is accessing the data, and a unique ID for the request.

type SecurityEvent 

type SecurityEvent = string
const (
	AdminAddEvent               SecurityEvent = "ADMIN_ADD"
	AdminRemoveEvent            SecurityEvent = "ADMIN_REMOVE"
	AdminChangePermissionsEvent SecurityEvent = "ADMIN_CHANGE_PERMISSIONS"
	AdminChangeSSettingEvent    SecurityEvent = "ADMIN_CHANGE_SETTING"
)
const (
	DataImportEvent            SecurityEvent = "DATA_IMPORT"
	DataExportEvent            SecurityEvent = "DATA_EXPORT"
	DataEncryptEvent           SecurityEvent = "DATA_ENCRYPT"
	DataDecryptEvent           SecurityEvent = "DATA_DECRYPT"
	DataCreateEvent            SecurityEvent = "DATA_CREATE"
	DataDeleteEvent            SecurityEvent = "DATA_DELETE"
	DataDenyAccessEvent        SecurityEvent = "DATA_DENY_ACCESS"
	DataChangePermissionsEvent SecurityEvent = "DATA_CHANGE_PERMISSIONS"
)
const (
	PeriodicEnforceRetentionPolicyEvent SecurityEvent = "ENFORCE_RETENTION_POLICY"
	PeriodicCreateBackupEvent           SecurityEvent = "CREATE_BACKUP"
)
const (
	UserAddEvent               SecurityEvent = "USER_ADD"
	UserSuspendEvent           SecurityEvent = "USER_SUSPEND"
	UserRemoveEvent            SecurityEvent = "USER_REMOVE"
	UserLoginEvent             SecurityEvent = "USER_LOGIN"
	UserTimeoutSessionEvent    SecurityEvent = "USER_TIMEOUT_SESSION"
	UserLockoutEvent           SecurityEvent = "USER_LOCKOUT"
	UserLogoutEvent            SecurityEvent = "USER_LOGOUT"
	UserChangePermissionsEvent SecurityEvent = "USER_CHANGE_PERMISSIONS"
	UserExpirePasswordEvent    SecurityEvent = "USER_EXPIRE_PASSWORD"
	//nolint: gosec
	UserResetPasswordEvent            SecurityEvent = "USER_RESET_PASSWORD"
	UserChangePasswordEvent           SecurityEvent = "USER_CHANGE_PASSWORD"
	UserRejectLoginEvent              SecurityEvent = "USER_REJECT_LOGIN"
	UserEnableTwoFactorEvent          SecurityEvent = "USER_ENABLE_TWO_FACTOR"
	UserDisableTwoFactorEvent         SecurityEvent = "USER_DISABLE_TWO_FACTOR"
	UserChangeEmailEvent              SecurityEvent = "USER_CHANGE_EMAIL"
	UserRequestEmailVerificationEvent SecurityEvent = "USER_REQUEST_EMAIL_VERIFICATION"
	UserVerifyEmailEvent              SecurityEvent = "USER_VERIFY_EMAIL"
)

type TenantSecurityClient 

type TenantSecurityClient struct {
	// contains filtered or unexported fields
}

TenantSecurityClient is used to encrypt and decrypt documents, log security events, and more. It is the primary class that consumers of the library will need to utilize, and a single instance of the class can be re-used for requests across different tenants. This API is safe for concurrent use.

func NewTenantSecurityClient 

func NewTenantSecurityClient(apiKey string, tspAddress *url.URL, parallelism int) *TenantSecurityClient

NewTenantSecurityClient creates the TenantSecurityClient required for all encryption, decryption, and logging operations. It requires the API key used when starting the Tenant Security Proxy (TSP) as well as the URL of the TSP. Parallelism sets the number of CPU-bound workers which can simultaneously be running to encrypt and/or decrypt fields; if this is less than one, the TSC will use runtime.GOMAXPROCS(0) + 1.

func (*TenantSecurityClient) BatchDecrypt 

func (r *TenantSecurityClient) BatchDecrypt(ctx context.Context,
	documents map[string]EncryptedDocument,
	metadata *RequestMetadata) (*BatchDecryptedDocuments, error)

BatchDecrypt decrypts a map of documents from the ID of the document to its encrypted content. Makes a call out to the Tenant Security Proxy to decrypt all of the EDEKs in each document. This function supports partial failure so it returns two maps, one of document ID to successfully decrypted document and one of document ID to an Error.

func (*TenantSecurityClient) BatchEncrypt 

func (r *TenantSecurityClient) BatchEncrypt(ctx context.Context,
	documents map[string]PlaintextDocument,
	metadata *RequestMetadata) (*BatchEncryptedDocuments, error)

BatchEncrypt encrypts a map of documents from the ID of the document to the map of fields to encrypt. Each document will be encrypted to the same tenant ID. Makes a call out to the Tenant Security Proxy to generate a collection of new DEK/EDEK pairs for each document ID provided. This function supports partial failure so it returns two maps, one of document ID to successfully encrypted document and one of document ID to an Error.

func (*TenantSecurityClient) Decrypt 

func (r *TenantSecurityClient) Decrypt(ctx context.Context,
	document *EncryptedDocument,
	metadata *RequestMetadata) (*DecryptedDocument, error)

Decrypt decrypts the provided EncryptedDocument. Uses the Tenant Security Proxy to decrypt the document's encrypted document key (EDEK) and uses it to decrypt and return the document bytes. The DEK is then discarded.

func (*TenantSecurityClient) Encrypt 

func (r *TenantSecurityClient) Encrypt(ctx context.Context,
	document PlaintextDocument,
	metadata *RequestMetadata) (*EncryptedDocument, error)

Encrypt encrypts the provided document. Documents are provided as a map of field ID/name (string) to their bytes. Uses the Tenant Security Proxy to generate a new document encryption key (DEK), encrypts that key (EDEK), then uses the DEK to encrypt all of the provided document fields. Returns an EncryptedDocument which contains a map from each field's ID/name to encrypted bytes as well as the EDEK and discards the DEK.

func (*TenantSecurityClient) EncryptWithExistingKey added in v0.1.12 

func (r *TenantSecurityClient) EncryptWithExistingKey(ctx context.Context,
	document *DecryptedDocument,
	metadata *RequestMetadata) (
	*EncryptedDocument, error)

EncryptWithExistingKey encrypts the provided document reusing an existing encrypted document encryption key (EDEK). Makes a call out to the Tenant Security Proxy to decrypt the EDEK and then uses the resulting key (DEK) to encrypt the document. This allows callers to update/re-encrypt data that has already been encrypted with an existing key. For example, if multiple columns in a DB row are all encrypted to the same key and one of those columns needs to be updated, this method allows the caller to update a single column without having to re-encrypt every field in the row with a new key.

func (*TenantSecurityClient) LogSecurityEvent 

func (r *TenantSecurityClient) LogSecurityEvent(ctx context.Context,
	event SecurityEvent,
	metadata *EventMetadata) error

Send the provided security event to the TSP to be logged and analyzed. Note that logging a security event is an asynchronous operation at the TSP, so successful receipt of a security event does not mean that the event is deliverable or has been delivered to the tenant's logging system; it simply means that the event has been received and will be processed.

func (*TenantSecurityClient) RekeyEdek 

func (r *TenantSecurityClient) RekeyEdek(ctx context.Context,
	edek *Edek,
	newTenantID string,
	metadata *RequestMetadata) (*Edek, error)

RekeyEdek re-keys a document's encrypted document key (EDEK) to a new tenant. Decrypts the EDEK then re-encrypts it to the new tenant. The DEK is then discarded. The old tenant and new tenant can be the same in order to re-key the document to the tenant's latest primary config.

Source Files

View all Source files

Directories

Path Synopsis
examples
batch-example
nolint: forbidigo
 nolint: forbidigo
logging-example
nolint: forbidigo
 nolint: forbidigo
rekey-example
nolint: forbidigo
 nolint: forbidigo
simple-example
nolint: forbidigo
 nolint: forbidigo

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.