private

Documentation

Overview

Package private enables the secure processing of PII data within substrate. It provides helpers to encrypt and decrypt data that is sent to substrate for subsequent processing, as well as purging data belonging to an individual.

Index

• Constants
• Variables
• func Decode(ctx context.Context, client shiroclient.ShiroClient, encoded *EncodedResponse, ...) error
• func Export(ctx context.Context, client shiroclient.ShiroClient, dsid DSID, ...) (map[string]interface{}, error)
• func Purge(ctx context.Context, client shiroclient.ShiroClient, dsid DSID, ...) error
• func WithSeed() (shiroclient.Config, error)
• func WithSkipEncodeTx() shiroclient.Config
• func WithTransientMXF(req *EncodeRequest) ([]shiroclient.Config, error)
• type CallFunc
  • func WrapCall(client shiroclient.ShiroClient, method string, encTransforms ...*Transform) CallFunc
• type CallResult
• type Compressor
• type DSID
  • func ProfileToDSID(ctx context.Context, client shiroclient.ShiroClient, profile interface{}, ...) (DSID, error)
• type EncodeRequest
• type EncodedMessage
• type EncodedResponse
  • func Encode(ctx context.Context, client shiroclient.ShiroClient, message interface{}, ...) (*EncodedResponse, error)
  • func (r *EncodedResponse) MarshalJSON() ([]byte, error)
  • func (r *EncodedResponse) UnmarshalJSON(b []byte) error
• type Encryptor
• type Transform
• type TransformBody
• type TransformHeader

Constants

const (
	// ShiroEndpointDecode is used to decode private data.
	ShiroEndpointDecode = "private_decode"
	// ShiroEndpointEncode is used to encode private data.
	ShiroEndpointEncode = "private_encode"
	// ShiroEndpointPurge is used to purge private data from the blockchain for
	// a data subject.
	ShiroEndpointPurge = "private_purge"
	// ShiroEndpointExport is used to export a data subject's private data.
	ShiroEndpointExport = "private_export"
	// ShiroEndpointProfileToDSID is used to get a DSID given a profile.
	ShiroEndpointProfileToDSID = "private_get_dsid"
)

Variables

var SeedGen = func() ([]byte, error) {
	key := make([]byte, hkdfSeedSize)
	_, err := rand.Read(key)
	if err != nil {
		return nil, err
	}
	return key, nil
}

SeedGen generates random secret keys. This is a hook that can be overridden at run time.

Functions

func Decode

func Decode(ctx context.Context, client shiroclient.ShiroClient, encoded *EncodedResponse, decoded interface{}, configs ...shiroclient.Config) error

Decode decodes a message that was encoded with transforms. If there are no transforms, then decode unmarshals the raw message bytes into "decoded".

func Export

func Export(ctx context.Context, client shiroclient.ShiroClient, dsid DSID, configs ...shiroclient.Config) (map[string]interface{}, error)

Export exports all sensitive data on the blockchain pertaining to a data subject with data subject ID "dsid".

func Purge

func Purge(ctx context.Context, client shiroclient.ShiroClient, dsid DSID, configs ...shiroclient.Config) error

Purge removes all sensitive data on the blockchain pertaining to a data subject with data subject ID "dsid".

func WithSeed

func WithSeed() (shiroclient.Config, error)

WithSeed returns a shiroclient config that includes a CSPRNG seed.

func WithSkipEncodeTx

func WithSkipEncodeTx() shiroclient.Config

WithSkipEncodeTx skips the encode transaction and instead encodes the private data in the same transaction as the wrapped Call transaction. This is an optimization to reduce the number of transactions.

func WithTransientMXF

func WithTransientMXF(req *EncodeRequest) ([]shiroclient.Config, error)

WithTransientMXF adds transient data used by MXF to encode and encrypt data. This config is not compatible with `WithTransientIVs`.

Types

type CallFunc

type CallFunc func(
	ctx context.Context,
	message interface{},
	output interface{},
	configs ...shiroclient.Config) (*CallResult, error)

CallFunc is the function signature returned for wrapped calls

func WrapCall

func WrapCall(client shiroclient.ShiroClient, method string, encTransforms ...*Transform) CallFunc

WrapCall wraps a shiro call. If the transaction logic encrypts new data then IVs must be specified, via the `WithTransientIVs` function. The configs passed to this are passed to the wrapped call, and not the encode and decode operations. This is to prevent the caller from accidently overwriting the transient data fields. If the caller passes "WithParam" explicitly then this will be ignored in favor of the `message`. IMPORTANT: The wrapper assumes the wrapped endpoint only takes a single argument!

type CallResult

type CallResult struct {
	TransactionID string
}

CallResult is returned from wrapped calls and contains additional data relating to the response.

type Compressor

type Compressor string

Compressor selects message transform compression algortihms.

const CompressorNone Compressor = "none"

CompressorNone indicates that no compression should be applied.

const CompressorZlib Compressor = "zlib"

CompressorZlib indicates that zlib compression should be applied.

type DSID

type DSID string

DSID is an identifier that represents a Data Subject.

func ProfileToDSID

func ProfileToDSID(ctx context.Context, client shiroclient.ShiroClient, profile interface{}, configs ...shiroclient.Config) (DSID, error)

ProfileToDSID returns a DSID for a data subject profile.

type EncodeRequest

type EncodeRequest struct {
	// Message is the message to be encoded.
	Message interface{} `json:"message"`
	// Transforms are the transformations to apply.
	Transforms []*Transform `json:"transforms"`
}

EncodeRequest is a request to encode a message. This is exported for json serialization.

type EncodedMessage

type EncodedMessage struct {
	// MXF is a sentinel to indicate the message was encoded using libmxf.
	MXF string `json:"mxf"`
	// Message is the plaintext part of an encoded message.
	Message interface{} `json:"message"`
	// Transforms are the applied transforms.
	Transforms []*Transform `json:"transforms"`
}

EncodedMessage is a message that has undergone encoding. This is exported for json serialization.

type EncodedResponse

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

EncodedResponse is a result of encoding a message, and can subsequently be decoded.

func Encode

func Encode(ctx context.Context, client shiroclient.ShiroClient, message interface{}, transforms []*Transform, configs ...shiroclient.Config) (*EncodedResponse, error)

Encode encodes a sensitive "message" using "transforms". If there no transforms, then encode simply returns a thin wrapper over the encoded message bytes.

func (*EncodedResponse) MarshalJSON

func (r *EncodedResponse) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*EncodedResponse) UnmarshalJSON

func (r *EncodedResponse) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Encryptor

type Encryptor string

Encryptor selects message transform encryption algorithms.

const EncryptorAES256 Encryptor = "AES-256"

EncryptorAES256 indicates that AES-256 encryption should be applied.

const EncryptorNone Encryptor = "none"

EncryptorNone indicates that no encryption should be applied.

type Transform

type Transform struct {
	// ContextPath represents an elpspath within the message where the
	// transformation will be applied. All transformation paths are relative
	// to this context.
	ContextPath string `json:"context_path"`
	// Header represents a transformation header. It is a description of
	// the transformation used for encoding and decoding.
	Header *TransformHeader `json:"header"`
	// Body includes an encoded message, where the encoding used the settings
	// defined in the Header.
	Body *TransformBody `json:"body"`
}

Transform is a message transformation. It encapsulates both transformed messages (body), as well as settings to perform a transformation (header).

type TransformBody

type TransformBody struct {
	// DSID is the data subject ID for the encoded transformation.
	DSID DSID `json:"dsid"`
	// EncryptedBase64 is the encrypted bytes belonging to the data subject.
	EncryptedBase64 string `json:"encrypted_base64"`
}

TransformBody is the body portion of a transformation. This is populated on encoded messages. This is exported for json serialization.

type TransformHeader

type TransformHeader struct {
	// ProfilePaths are elpspaths that compose a data subject profile.
	ProfilePaths []string `json:"profile_paths"`
	// PrivatePaths are elpspaths that select private data.
	PrivatePaths []string `json:"private_paths"`
	// Encryptor selects the encryption algorithm.
	Encryptor Encryptor `json:"encryptor"`
	// Compressor selects the compression algorithm.
	Compressor Compressor `json:"compressor"`
}

TransformHeader is a header for a message transformation. This is exported for json serialization.