sdk

package module
v0.3.4 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2024 License: BSD-3-Clause-Clear Imports: 47 Imported by: 9

README

OpenTDF Data Security SDK

A Go implementation of the OpenTDF protocol, and access library for services included in the Data Security Platform.

Note: if you are consuming the SDK as a submodule you may need to add replace directives as follows:

replace (
  github.com/opentdf/platform/service => ./opentdf/service
	github.com/opentdf/platform/lib/fixtures => ./opentdf/lib/fixtures
	github.com/opentdf/platform/protocol/go => ./opentdf/protocol/go
	github.com/opentdf/platform/lib/ocrypto => ./opentdf/lib/ocrypto
	github.com/opentdf/platform/sdk => ./opentdf/sdk
	github.com/opentdf/platform/service => ./opentdf/service
)

Quick Start of the Go SDK

package main

import "fmt"
import "bytes"
import "io"
import "os"
import "strings"
import "github.com/opentdf/platform/sdk"


func main() {
  s, _ := sdk.New(
    sdk.WithAuth(mtls.NewGRPCAuthorizer(creds) /* or OIDC or whatever */),
    sdk.WithDataSecurityConfig(/* attribute schemas, kas multi-attribute mapping */),
  )

  plaintext := strings.NewReader("Hello, world!")
  var ciphertext bytes.Buffer
  _, err := s.CreateTDF(
    ciphertext,
    plaintext,
    sdk.WithDataAttributes("https://example.com/attr/Classification/value/Open"),
  )
  if err != nil {
    panic(err)
  }

  fmt.Printf("Ciphertext is %s bytes long", ciphertext.Len())

  ct2 := make([]byte, ciphertext.Len())
  copy(ct2, ciphertext.Bytes())
  r, err := s.NewTDFReader(bytes.NewReader(ct2))
  f, err := os.Create("output.txt")
  if err != nil {
    panic(err)
  }
  io.Copy(f, r)
}

Development

To test, run

go test ./... -short -race -cover

Documentation

Index

Constants

View Source 
const (
	// Failure while connecting to a service.
	// Check your configuration and/or retry.
	ErrGrpcDialFailed            = Error("failed to dial grpc endpoint")
	ErrShutdownFailed            = Error("failed to shutdown sdk")
	ErrPlatformConfigFailed      = Error("failed to retrieve platform configuration")
	ErrPlatformEndpointMalformed = Error("platform endpoint is malformed")
)
View Source 
const (
	JSONFormat = iota
	XMLFormat
)
View Source 
const (
	HS256 = iota
	GMAC
)
View Source 
const (
	ErrNanoTDFHeaderRead = Error("nanoTDF read error")
)

Variables

This section is empty.

Functions

func NewCertExchangeTokenSource added in v0.2.1 

func NewCertExchangeTokenSource(info oauth.CertExchangeInfo, credentials oauth.ClientCredentials, idpTokenEndpoint string, dpop *ocrypto.RsaKeyPair) (auth.AccessTokenSource, error)

func SanitizePlatformEndpoint added in v0.2.7 

func SanitizePlatformEndpoint(e string) (string, error)

func SizeOfAuthTagForCipher added in v0.2.4 

func SizeOfAuthTagForCipher(cipherType CipherMode) (int, error)

SizeOfAuthTagForCipher - Return the size in bytes of auth tag to be used for aes gcm encryption

Types

type Assertion 

type Assertion struct {
}

type CertExchangeTokenSource added in v0.2.1 

type CertExchangeTokenSource struct {
	auth.AccessTokenSource
	IdpEndpoint string
	// contains filtered or unexported fields
}

func (*CertExchangeTokenSource) AccessToken added in v0.2.1 

func (c *CertExchangeTokenSource) AccessToken(ctx context.Context, _ *http.Client) (auth.AccessToken, error)

func (*CertExchangeTokenSource) MakeToken added in v0.2.1 

func (c *CertExchangeTokenSource) MakeToken(tokenMaker func(jwk.Key) ([]byte, error)) ([]byte, error)

type CipherMode added in v0.2.4 

type CipherMode int

type EncryptedMetadata 

type EncryptedMetadata struct {
	Cipher string `json:"ciphertext"`
	Iv     string `json:"iv"`
}

type EncryptionInformation 

type EncryptionInformation struct {
	KeyAccessType        string      `json:"type"`
	Policy               string      `json:"policy"`
	KeyAccessObjs        []KeyAccess `json:"keyAccess"`
	Method               Method      `json:"method"`
	IntegrityInformation `json:"integrityInformation"`
}

type Error 

type Error string

func (Error) Error 

func (c Error) Error() string

type IDPAccessTokenSource 

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

IDPAccessTokenSource credentials that allow us to connect to an IDP and obtain an access token that is bound to a DPoP key

func NewIDPAccessTokenSource 

func NewIDPAccessTokenSource(
	credentials oauth.ClientCredentials, idpTokenEndpoint string, scopes []string, key *ocrypto.RsaKeyPair) (*IDPAccessTokenSource, error)

func (*IDPAccessTokenSource) AccessToken 

func (t *IDPAccessTokenSource) AccessToken(ctx context.Context, client *http.Client) (auth.AccessToken, error)

AccessToken use a pointer receiver so that the token state is shared

func (*IDPAccessTokenSource) MakeToken 

func (t *IDPAccessTokenSource) MakeToken(tokenMaker func(jwk.Key) ([]byte, error)) ([]byte, error)

type IDPTokenExchangeTokenSource 

type IDPTokenExchangeTokenSource struct {
	IDPAccessTokenSource
	oauth.TokenExchangeInfo
}

func NewIDPTokenExchangeTokenSource 

func NewIDPTokenExchangeTokenSource(exchangeInfo oauth.TokenExchangeInfo, credentials oauth.ClientCredentials, idpTokenEndpoint string, scopes []string, key *ocrypto.RsaKeyPair) (*IDPTokenExchangeTokenSource, error)

func (*IDPTokenExchangeTokenSource) AccessToken 

func (i *IDPTokenExchangeTokenSource) AccessToken(ctx context.Context, client *http.Client) (auth.AccessToken, error)

func (*IDPTokenExchangeTokenSource) MakeToken 

func (i *IDPTokenExchangeTokenSource) MakeToken(keyMaker func(jwk.Key) ([]byte, error)) ([]byte, error)

type IntegrityAlgorithm 

type IntegrityAlgorithm = int

type IntegrityInformation 

type IntegrityInformation struct {
	RootSignature           `json:"rootSignature"`
	SegmentHashAlgorithm    string    `json:"segmentHashAlg"`
	DefaultSegmentSize      int64     `json:"segmentSizeDefault"`
	DefaultEncryptedSegSize int64     `json:"encryptedSegmentSizeDefault"`
	Segments                []Segment `json:"segments"`
}

type KASClient 

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

type KASInfo 

type KASInfo struct {
	// URL of the KAS server
	URL string
	// Public key can be empty.
	// If it is empty, the public key will be fetched from the KAS server.
	PublicKey string
	// Key identifier associated with the given key, if present.
	KID string
	// The algorithm associated with this key
	Algorithm string
	// If this KAS should be used as the default for 'encrypt' calls
	Default bool
}

KASInfo contains Key Access Server information.

type KeyAccess 

type KeyAccess struct {
	KeyType           string      `json:"type"`
	KasURL            string      `json:"url"`
	Protocol          string      `json:"protocol"`
	WrappedKey        string      `json:"wrappedKey"`
	PolicyBinding     interface{} `json:"policyBinding"`
	EncryptedMetadata string      `json:"encryptedMetadata,omitempty"`
	KID               string      `json:"kid,omitempty"`
	SplitID           string      `json:"sid,omitempty"`
}

type Manifest 

type Manifest struct {
	EncryptionInformation `json:"encryptionInformation"`
	Payload               `json:"payload"`
}

type Method 

type Method struct {
	Algorithm    string `json:"algorithm"`
	IV           string `json:"iv"`
	IsStreamable bool   `json:"isStreamable"`
}

type NanoKASInfo added in v0.2.4 

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

type NanoTDFConfig added in v0.2.4 

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

func (*NanoTDFConfig) EnableECDSAPolicyBinding added in v0.2.5 

func (config *NanoTDFConfig) EnableECDSAPolicyBinding()

EnableECDSAPolicyBinding enable ecdsa policy binding

func (*NanoTDFConfig) SetAttributes added in v0.2.4 

func (config *NanoTDFConfig) SetAttributes(attributes []string) error

SetAttributes - set the attributes to be used for this nanoTDF

func (*NanoTDFConfig) SetKasURL added in v0.2.4 

func (config *NanoTDFConfig) SetKasURL(url string) error

SetKasURL - set the URL of the KAS endpoint to be used for this nanoTDF

type NanoTDFHeader added in v0.2.4 

type NanoTDFHeader struct {
	EphemeralKey        []byte
	EncryptedPolicyBody []byte
	// contains filtered or unexported fields
}

func NewNanoTDFHeaderFromReader added in v0.2.4 

func NewNanoTDFHeaderFromReader(reader io.Reader) (NanoTDFHeader, uint32, error)

func (*NanoTDFHeader) ECCurve added in v0.2.5 

func (header *NanoTDFHeader) ECCurve() (elliptic.Curve, error)

func (*NanoTDFHeader) GetCipher added in v0.2.4 

func (header *NanoTDFHeader) GetCipher() CipherMode

GetCipher -- get the cipher from the nano tdf header

func (*NanoTDFHeader) IsEcdsaBindingEnabled added in v0.2.5 

func (header *NanoTDFHeader) IsEcdsaBindingEnabled() bool

func (*NanoTDFHeader) VerifyPolicyBinding added in v0.2.5 

func (header *NanoTDFHeader) VerifyPolicyBinding() (bool, error)

type NanoTDFOption added in v0.2.4 

type NanoTDFOption func(*NanoTDFConfig) error

func WithECDSAPolicyBinding added in v0.2.5 

func WithECDSAPolicyBinding() NanoTDFOption

WithECDSAPolicyBinding enable ecdsa policy binding

func WithNanoDataAttributes added in v0.2.4 

func WithNanoDataAttributes(attributes ...string) NanoTDFOption

WithNanoDataAttributes appends the given data attributes to the bound policy

func WithNanoKasInformation added in v0.2.4 

func WithNanoKasInformation(kasInfoList ...NanoKASInfo) NanoTDFOption

WithNanoKasInformation adds the first kas url and its corresponding public key that is required to create and read the nanotdf. Note that only the first entry is used, as multi-kas is not supported for nanotdf

type Option 

type Option func(*config)

func WithClientCredentials 

func WithClientCredentials(clientID, clientSecret string, scopes []string) Option

WithClientCredentials returns an Option that sets up authentication with client credentials.

func WithCustomAuthorizationConnection 

func WithCustomAuthorizationConnection(conn *grpc.ClientConn) Option

func WithCustomEntityResolutionConnection added in v0.2.3 

func WithCustomEntityResolutionConnection(conn *grpc.ClientConn) Option

func WithCustomPolicyConnection 

func WithCustomPolicyConnection(conn *grpc.ClientConn) Option

func WithCustomWellknownConnection added in v0.2.5 

func WithCustomWellknownConnection(conn *grpc.ClientConn) Option

func WithExtraDialOptions 

func WithExtraDialOptions(dialOptions ...grpc.DialOption) Option

func WithIPC added in v0.2.7 

func WithIPC() Option

WithIPC returns an Option that indicates the SDK should use IPC for communication this will allow the platform endpoint to be an empty string

func WithInsecurePlaintextConn added in v0.2.1 

func WithInsecurePlaintextConn() Option

WithInsecurePlaintextConn returns an Option that sets up HTTP connection sent in the clear.

func WithInsecureSkipVerifyConn added in v0.2.1 

func WithInsecureSkipVerifyConn() Option

WithInsecureSkipVerifyConn returns an Option that sets up HTTPS connection without verification.

func WithNoKIDInKAO added in v0.2.8 

func WithNoKIDInKAO() Option

WithNoKIDInKAO disables storing the KID in the KAO. This allows generating TDF files that are compatible with legacy file formats (no KID).

func WithPlatformConfiguration added in v0.2.5 

func WithPlatformConfiguration(platformConfiguration PlatformConfiguration) Option

WithPlatformConfiguration allows you to override the remote platform configuration Use this option with caution, as it may lead to unexpected behavior

func WithSessionEncryptionRSA added in v0.2.4 

func WithSessionEncryptionRSA(key *rsa.PrivateKey) Option

The session key pair is used to encrypt responses from KAS for a given session and can be reused across an entire session. Please use with caution.

func WithSessionSignerRSA added in v0.2.4 

func WithSessionSignerRSA(key *rsa.PrivateKey) Option

The DPoP key pair is used to implement sender constrained tokens from the identity provider, and should be associated with the lifetime of a session for a given identity. Please use with caution.

func WithTLSCredentials added in v0.2.1 

func WithTLSCredentials(tls *tls.Config, audience []string) Option

func WithTokenEndpoint 

func WithTokenEndpoint(tokenEndpoint string) Option

WithTokenEndpoint When we implement service discovery using a .well-known endpoint this option may become deprecated Deprecated: SDK will discover the token endpoint from the platform configuration

func WithTokenExchange 

func WithTokenExchange(subjectToken string, audience []string) Option

WithTokenExchange specifies that the SDK should obtain its access token by exchanging the given token for a new one

type Payload 

type Payload struct {
	Type        string `json:"type"`
	URL         string `json:"url"`
	Protocol    string `json:"protocol"`
	MimeType    string `json:"mimeType"`
	IsEncrypted bool   `json:"isEncrypted"`
}

type PlatformConfiguration added in v0.2.5 

type PlatformConfiguration map[string]interface{}

type PolicyBinding added in v0.3.3 

type PolicyBinding struct {
	Alg  string `json:"alg"`
	Hash string `json:"hash"`
}

type PolicyBody 

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

type PolicyObject 

type PolicyObject struct {
	UUID string `json:"uuid"`
	Body struct {
		DataAttributes []attributeObject `json:"dataAttributes"`
		Dissem         []string          `json:"dissem"`
	} `json:"body"`
}

type Reader 

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

Loads and reads ZTDF files

func (*Reader) DataAttributes 

func (r *Reader) DataAttributes() ([]string, error)

DataAttributes return the data attributes present in tdf.

func (*Reader) Init added in v0.2.11 

func (r *Reader) Init(ctx context.Context) error

Do any network based operations required. This allows making the requests cancellable

func (*Reader) Manifest 

func (r *Reader) Manifest() Manifest

func (*Reader) Policy 

func (r *Reader) Policy() (PolicyObject, error)

Policy returns a copy of the policy object in manifest, if it is valid. Otherwise, returns an error.

func (*Reader) Read 

func (r *Reader) Read(p []byte) (int, error)

Read reads up to len(p) bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. It returns an io.EOF error when the stream ends.

func (*Reader) ReadAt 

func (r *Reader) ReadAt(buf []byte, offset int64) (int, error)

ReadAt reads len(p) bytes into p starting at offset off in the underlying input source. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. It returns an io.EOF error when the stream ends. NOTE: For larger tdf sizes use sdk.GetTDFPayload for better performance

func (*Reader) UnencryptedMetadata 

func (r *Reader) UnencryptedMetadata() ([]byte, error)

UnencryptedMetadata return decrypted metadata in manifest.

func (*Reader) WriteTo 

func (r *Reader) WriteTo(writer io.Writer) (int64, error)

WriteTo writes data to writer until there's no more data to write or when an error occurs. This implements the io.WriterTo interface.

type RequestBody 

type RequestBody struct {
	KeyAccess       `json:"keyAccess"`
	ClientPublicKey string `json:"clientPublicKey"`
	Policy          string `json:"policy"`
}

type ResourceLocator added in v0.2.4 

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

ResourceLocator - structure to contain a protocol + body comprising an URL

func NewResourceLocator added in v0.2.4 

func NewResourceLocator(url string) (*ResourceLocator, error)

func NewResourceLocatorFromReader added in v0.2.4 

func NewResourceLocatorFromReader(reader io.Reader) (*ResourceLocator, error)

type RootSignature 

type RootSignature struct {
	Algorithm string `json:"alg"`
	Signature string `json:"sig"`
}

type SDK 

type SDK struct {
	Namespaces              namespaces.NamespaceServiceClient
	Attributes              attributes.AttributesServiceClient
	ResourceMapping         resourcemapping.ResourceMappingServiceClient
	SubjectMapping          subjectmapping.SubjectMappingServiceClient
	KeyAccessServerRegistry kasregistry.KeyAccessServerRegistryServiceClient
	Unsafe                  unsafe.UnsafeServiceClient
	Authorization           authorization.AuthorizationServiceClient
	EntityResoution         entityresolution.EntityResolutionServiceClient
	// contains filtered or unexported fields
}

func New 

func New(platformEndpoint string, opts ...Option) (*SDK, error)

func (SDK) Close 

func (s SDK) Close() error

Close closes the underlying grpc.ClientConn.

func (SDK) Conn 

func (s SDK) Conn() *grpc.ClientConn

Conn returns the underlying grpc.ClientConn.

func (SDK) CreateNanoTDF added in v0.2.4 

func (s SDK) CreateNanoTDF(writer io.Writer, reader io.Reader, config NanoTDFConfig) (uint32, error)

CreateNanoTDF - reads plain text from the given reader and saves it to the writer, subject to the given options

func (SDK) CreateTDF 

func (s SDK) CreateTDF(writer io.Writer, reader io.ReadSeeker, opts ...TDFOption) (*TDFObject, error)

CreateTDF reads plain text from the given reader and saves it to the writer, subject to the given options

func (SDK) CreateTDFContext added in v0.3.0 

func (s SDK) CreateTDFContext(ctx context.Context, writer io.Writer, reader io.ReadSeeker, opts ...TDFOption) (*TDFObject, error)

CreateTDF reads plain text from the given reader and saves it to the writer, subject to the given options

func (SDK) LoadTDF 

func (s SDK) LoadTDF(reader io.ReadSeeker) (*Reader, error)

LoadTDF loads the tdf and prepare for reading the payload from TDF

func (SDK) NewNanoTDFConfig added in v0.2.4 

func (s SDK) NewNanoTDFConfig() (*NanoTDFConfig, error)

NewNanoTDFConfig - Create a new instance of a nanoTDF config

func (SDK) PlatformIssuer added in v0.2.5 

func (s SDK) PlatformIssuer() string

func (SDK) ReadNanoTDF added in v0.2.4 

func (s SDK) ReadNanoTDF(writer io.Writer, reader io.ReadSeeker) (uint32, error)

ReadNanoTDF - read the nano tdf and return the decrypted data from it

func (SDK) ReadNanoTDFContext added in v0.2.11 

func (s SDK) ReadNanoTDFContext(ctx context.Context, writer io.Writer, reader io.ReadSeeker) (uint32, error)

ReadNanoTDFContext - allows cancelling the reader

type Segment 

type Segment struct {
	Hash          string `json:"hash"`
	Size          int64  `json:"segmentSize"`
	EncryptedSize int64  `json:"encryptedSegmentSize"`
}

type TDFConfig 

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

TDFConfig Internal config struct for building TDF options.

type TDFFormat 

type TDFFormat = int

type TDFObject 

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

func (*TDFObject) Manifest 

func (t *TDFObject) Manifest() Manifest

func (TDFObject) Size added in v0.2.11 

func (t TDFObject) Size() int64

type TDFOption 

type TDFOption func(*TDFConfig) error

func WithAutoconfigure added in v0.3.0 

func WithAutoconfigure(enable bool) TDFOption

WithAutoconfigure toggles inferring KAS info for encrypt from data attributes. This will use the Attributes service to look up key access grants. These are KAS URLs associated with attributes. Defaults to enabled.

func WithDataAttributeValues added in v0.3.0 

func WithDataAttributeValues(attributes ...*policy.Value) TDFOption

WithDataAttributeValues appends the given data attributes to the bound policy. Unlike `WithDataAttributes`, this will not trigger an attribute definition lookup during autoconfigure. That is, to use autoconfigure in an 'offline' context, you must first store the relevant attribute information locally and load it to the `CreateTDF` method with this option.

func WithDataAttributes 

func WithDataAttributes(attributes ...string) TDFOption

WithDataAttributes appends the given data attributes to the bound policy

func WithKasInformation 

func WithKasInformation(kasInfoList ...KASInfo) TDFOption

WithKasInformation adds all the kas urls and their corresponding public keys that is required to create and read the tdf. For writing TDFs, this is optional, but adding it can bypass key lookup.

During creation, if the public key is set, the kas will not be contacted for the latest key. Please make sure to set the KID if the PublicKey is set to include a KID in any key wrappers.

func WithMetaData 

func WithMetaData(metaData string) TDFOption

WithMetaData returns an Option that add metadata to TDF.

func WithMimeType added in v0.2.3 

func WithMimeType(mimeType string) TDFOption

func WithSegmentSize 

func WithSegmentSize(size int64) TDFOption

WithSegmentSize returns an Option that set the default segment size to TDF.

Source Files

View all Source files

Directories

Path Synopsis
internal
archive
autoconfigure
oauth

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.