Documentation

TenantSecurityClient extends TenantSecurityRequest
in package

Application

Uses Aes

Client used to encrypt and decrypt documents. This 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.

BATCH_UNWRAP_ENDPOINT = "document/batch-unwrap"
BATCH_WRAP_ENDPOINT = "document/batch-wrap"
REKEY_ENDPOINT = "document/rekey"
SECURITY_EVENT_ENDPOINT = "event/security-event"
TENANT_KEY_DERIVE_ENDPOINT = "key/derive"
TSP_API_PREFIX = "/api/1/"
UNWRAP_ENDPOINT = "document/unwrap"
WRAP_ENDPOINT = "document/wrap"
$apiKey : string
$ch : CurlHandle
$request : TenantSecurityRequest
$tspAddress : string
__construct() : mixed
batchDecrypt() : BatchPlaintextDocuments: 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 a TenantSecurityException.
batchEncrypt() : BatchEncryptedDocuments: Encrypts an array of documents from the ID of the document to the list of fields to encrypt.
createHeaderProto() : V3DocumentHeader: Make a V3DocumentHeader with a SaaSShieldHeader and a generated signature.
decrypt() : PlaintextDocument: Decrypts the provided EncryptedDocument. Decrypts the document's encrypted document key (EDEK) using the Tenant Security Proxy and uses it to decrypt and return the document bytes. The DEK is then discarded.
encrypt() : EncryptedDocument: Encrypts the provided document. Documents are provided as a map of fields from the document id/name (string) to bytes (string). Uses the Tenant Security Proxy to generate a new document encryption key (DEK), encrypt that key (EDEK), then use 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.
encryptWithExistingKey() : EncryptedDocument
generateHeader() : Bytes: Generates a header to mark the encrypted document as ours.
generateSignature() : V3HeaderSignature: Generates a signature over the header using the provided document encryption key and IV.
logSecurityEvent() : void: 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.
rekeyEdek() : Bytes: Re-key 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.
verifySignature() : bool: Verifies a document header's signature.
batchUnwrapKeys() : BatchUnwrapKeyResponse: Requests the TSP to unwrap multiple EDEKs.
batchWrapKeys() : BatchWrapKeyResponse: Requests the TSP to generate multiple DEK/EDEK pairs.
makeJsonRequest() : string: Makes a POST request to a Tenant Security Proxy endpoint with the provided JSON payload.
rekey() : RekeyResponse: Requests the TSP to re-key an EDEK.
unwrapKey() : UnwrapKeyResponse: Requests the TSP to unwrap an EDEK.
wrapKey() : WrapKeyResponse: Requests the TSP to generate a DEK and an EDEK.
containsIroncoreMagic() : bool: Verifies that bytes 2-5 are the IronCore magic string.
decryptDocument() : Bytes: Decrypts an encrypted document.
decryptInternal() : Bytes: Takes a string of arbitrary bytes and decrypts it using a given key.
encryptDocument() : Bytes: Encrypts a document.
encryptInternal() : Bytes: Encrypts given plaintext with the provided key.
encryptWithIv() : Bytes: Encrypts given plaintext with the provided key and IV.
getCurrentDocumentHeaderVersion() : Bytes: Gets the current IronCore document header version as a single byte.
getDocumentMagic() : Bytes: Gets IronCore document magic bytes that are included in every document's preamble
getHeaderSize() : int: Converts bytes 6 and 7 of the fixed preamble to an integer that represents the length of the header.
splitDocument() : DocumentParts: Splits an IronCore encrypted document into its component pieces.
verifyPreamble() : bool: Verifies that the preamble is the correct length and version, contains the string "IRON", and indicates a valid header length.

BATCH_UNWRAP_ENDPOINT


    private
    mixed
    BATCH_UNWRAP_ENDPOINT
    = "document/batch-unwrap"

BATCH_WRAP_ENDPOINT


    private
    mixed
    BATCH_WRAP_ENDPOINT
    = "document/batch-wrap"

REKEY_ENDPOINT


    private
    mixed
    REKEY_ENDPOINT
    = "document/rekey"

SECURITY_EVENT_ENDPOINT


    private
    mixed
    SECURITY_EVENT_ENDPOINT
    = "event/security-event"

TENANT_KEY_DERIVE_ENDPOINT


    private
    mixed
    TENANT_KEY_DERIVE_ENDPOINT
    = "key/derive"

TSP_API_PREFIX


    private
    mixed
    TSP_API_PREFIX
    = "/api/1/"

UNWRAP_ENDPOINT


    private
    mixed
    UNWRAP_ENDPOINT
    = "document/unwrap"

WRAP_ENDPOINT


    private
    mixed
    WRAP_ENDPOINT
    = "document/wrap"

$apiKey


    private
        string
    $apiKey

Secret key used to communicate with the Tenant Security Proxy

$ch


    private
        CurlHandle
    $ch

Curl handle used to make requests

$request


    private
        TenantSecurityRequest
    $request

$tspAddress


    private
        string
    $tspAddress

URL of the Tenant Security Proxy

__construct()


    public
                __construct(string $tspAddress, string $apiKey) : mixed

Parameters

$tspAddress : string: URL of the Tenant Security Proxy
$apiKey : string: Secret key needed to communicate with the Tenant Security Proxy

Return values

mixed —

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 a TenantSecurityException.


    public
                batchDecrypt(array<string|int, EncryptedDocument> $documents, RequestMetadata $metadata) : BatchPlaintextDocuments

Parameters

$documents : array<string|int, EncryptedDocument>: Encrypted documents to decrypt. Each entry in the array is [documentId => EncryptedDocument].
$metadata : RequestMetadata

Return values

BatchPlaintextDocuments —

Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original documents map.

batchEncrypt()

Encrypts an array of documents from the ID of the document to the list of fields to encrypt.


    public
                batchEncrypt(array<string|int, array<string|int, Bytes>> $documents, RequestMetadata $metadata) : BatchEncryptedDocuments

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 a TenantSecurityException.

Parameters

$documents : array<string|int, array<string|int, Bytes>>: Documents to encrypt. Each entry in the array is [documentId => Bytes[]].
$metadata : RequestMetadata: Metadata about the documents being encrypted

Return values

BatchEncryptedDocuments —

Collection of successes and failures that occurred during operation. The keys of each map returned will be the same keys provided in the original documents map.

createHeaderProto()

Make a V3DocumentHeader with a SaaSShieldHeader and a generated signature.


    public
            static    createHeaderProto(Bytes $dek, string $tenantId, Rng $rng[, Bytes $iv = null ]) : V3DocumentHeader

Parameters

$dek : Bytes: Document encryption key to use for signing
$tenantId : string: Tenant making the request
$rng : Rng
$iv : Bytes = null: Option IV to use when signing. If not present, a random IV is generated.

Return values

V3DocumentHeader —

Signed document header

decrypt()

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


    public
                decrypt(EncryptedDocument $document, RequestMetadata $metadata) : PlaintextDocument

Parameters

$document : EncryptedDocument: Encrypted document to decrypt
$metadata : RequestMetadata: Metadata about the document being decrypted

Return values

PlaintextDocument —

Decrypted document and encrypted document key (EDEK)

encrypt()

Encrypts the provided document. Documents are provided as a map of fields from the document id/name (string) to bytes (string). Uses the Tenant Security Proxy to generate a new document encryption key (DEK), encrypt that key (EDEK), then use 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.


    public
                encrypt(array<string|int, Bytes> $document, RequestMetadata $metadata) : EncryptedDocument

Parameters

$document : array<string|int, Bytes>: Document to encrypt. Each field in the provided document will be encrypted with the same key.
$metadata : RequestMetadata: Metadata about the document being encrypted

Return values

EncryptedDocument —

Encrypted document and encrypted document key (EDEK)

encryptWithExistingKey()


    public
                encryptWithExistingKey(PlaintextDocument $document, RequestMetadata $metadata) : EncryptedDocument

Parameters

$document : PlaintextDocument
$metadata : RequestMetadata

Return values

EncryptedDocument —

generateHeader()

Generates a header to mark the encrypted document as ours.


    public
            static    generateHeader(Bytes $dek, string $tenantId, Rng $rng) : Bytes

Current version is as follows: VERSION_NUMBER (1 bytes, fixed at 3), IRONCORE_MAGIC (4 bytes, "IRON" in ASCII), HEADER_LENGTH (2 bytes Uint16), PROTOBUF_HEADER_DATA (variable bytes)

Parameters

$dek : Bytes: Document encryption key to use for signing
$tenantId : string: Tenant making the request
$rng : Rng

Return values

Bytes —

Bytes of header

generateSignature()

Generates a signature over the header using the provided document encryption key and IV.


    public
            static    generateSignature(Bytes $dek, Bytes $iv, SaaSShieldHeader $header) : V3HeaderSignature

Parameters

$dek : Bytes: Document encryption key to use for signing
$iv : Bytes: IV to use for signing
$header : SaaSShieldHeader: Header to sign over

Return values

V3HeaderSignature —

Header signature

logSecurityEvent()

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.


    public
                logSecurityEvent(SecurityEvent $event, EventMetadata $metadata) : void

Parameters

$event : SecurityEvent: Security event that represents the action that took place.
$metadata : EventMetadata: Metadata that provides additional context about the event.

Return values

void —

Failures come back as exceptions

rekeyEdek()

Re-key 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.


    public
                rekeyEdek(Bytes $edek, string $newTenantId, RequestMetadata $metadata) : Bytes

Parameters

$edek : Bytes: EDEK to re-key
$newTenantId : string: Tenant ID the document should be re-keyed to
$metadata : RequestMetadata: Metadata about the document being re-keyed.

Return values

Bytes —

Newly re-keyed EDEK

verifySignature()

Verifies a document header's signature.


    public
            static    verifySignature(Bytes $dek, V3DocumentHeader $header) : bool

Parameters

$dek : Bytes: Document encryption key used when generating the signature
$header : V3DocumentHeader: Header with signature to verify

Return values

bool —

true if the header's signature was successfully verified

batchUnwrapKeys()

Requests the TSP to unwrap multiple EDEKs.


    protected
                batchUnwrapKeys(array<string|int, Bytes> $edeks, RequestMetadata $metadata) : BatchUnwrapKeyResponse

Parameters

$edeks : array<string|int, Bytes>: Map from document IDs to EDEKs to unwrap
$metadata : RequestMetadata: Metadata about the requesting user/service

Return values

BatchUnwrapKeyResponse —

The unwrapped DEKs, as well as any failures

batchWrapKeys()

Requests the TSP to generate multiple DEK/EDEK pairs.


    protected
                batchWrapKeys(array<string|int, string> $documentIds, RequestMetadata $metadata) : BatchWrapKeyResponse

Parameters

$documentIds : array<string|int, string>: Document IDs to generate DEK/EDEK for.
$metadata : RequestMetadata: Metadata about the requesting user/service

Return values

BatchWrapKeyResponse —

The generated DEKs and EDEKs, as well as any failures

makeJsonRequest()

Makes a POST request to a Tenant Security Proxy endpoint with the provided JSON payload.


    protected
                makeJsonRequest(string $endpoint, string $jsonEncodedData) : string

Parameters

$endpoint : string: Tenant Security Proxy endpoint to make a request to
$jsonEncodedData : string: Payload to send to the Tenant Security Proxy

Return values

string —

The response from the Tenant Security Proxy

rekey()

Requests the TSP to re-key an EDEK.


    protected
                rekey(Bytes $edek, string $newTenantId, RequestMetadata $metadata) : RekeyResponse

Parameters

$edek : Bytes: The encrypted document key to re-key
$newTenantId : string: Tenant ID to re-key to
$metadata : RequestMetadata: Metadata about the requesting user/service

Return values

RekeyResponse —

The new DEK and EDEK

unwrapKey()

Requests the TSP to unwrap an EDEK.


    protected
                unwrapKey(Bytes $edek, RequestMetadata $metadata) : UnwrapKeyResponse

Parameters

$edek : Bytes: The encrypted document key to unwrap
$metadata : RequestMetadata: Metadata about the requesting user/service

Return values

UnwrapKeyResponse —

The unwrapped DEK

wrapKey()

Requests the TSP to generate a DEK and an EDEK.


    protected
                wrapKey(RequestMetadata $metadata) : WrapKeyResponse

Parameters

$metadata : RequestMetadata: Metadata about the requesting user/service

Return values

WrapKeyResponse —

The generated DEK and EDEK

containsIroncoreMagic()

Verifies that bytes 2-5 are the IronCore magic string.


    private
            static    containsIroncoreMagic(Bytes $bytes) : bool

Parameters

$bytes : Bytes: Bytes to check

Return values

bool —

true if the bytes are the correct form.

decryptDocument()

Decrypts an encrypted document.


    private
            static    decryptDocument(Bytes $document, Bytes $dek) : Bytes

Parameters

$document : Bytes: Encrypted bytes to decrypt
$dek : Bytes: Document encryption key used to encrypt the document

Return values

Bytes —

Decrypted document

decryptInternal()

Takes a string of arbitrary bytes and decrypts it using a given key.


    private
            static    decryptInternal(Bytes $ciphertext, Bytes $key) : Bytes

Parameters

$ciphertext : Bytes: The ciphertext to decrypt
$key : Bytes: The 32-byte secret key

Return values

Bytes —

The plaintext, which is arbitrary bytes.

encryptDocument()

Encrypts a document.


    private
            static    encryptDocument(Bytes $document, string $tenantId, Bytes $dek, Rng $rng) : Bytes

Parameters

$document : Bytes: Document bytes to encrypt
$tenantId : string: Tenant performing the encryption
$dek : Bytes: Document encryption key
$rng : Rng

Return values

Bytes —

Encrypted document bytes

encryptInternal()

Encrypts given plaintext with the provided key.


    private
            static    encryptInternal(Bytes $plaintext, Bytes $key, Rng $rng) : Bytes

Parameters

$plaintext : Bytes: Bytes to encrypt
$key : Bytes: 32-byte secret key that should be cryptographically random
$rng : Rng

Return values

Bytes —

Encrypted bytes with a 12-byte IV on the front and a 16-byte tag on the end

encryptWithIv()

Encrypts given plaintext with the provided key and IV.


    private
            static    encryptWithIv(Bytes $plaintext, Bytes $key, Bytes $iv) : Bytes

Parameters

$plaintext : Bytes: Bytes to encrypt
$key : Bytes: 32-byte secret key that should be cryptographically random
$iv : Bytes: IV to use for encryption

Return values

Bytes —

Encrypted bytes with a 12-byte IV on the front and a 16-byte tag on the end

getCurrentDocumentHeaderVersion()

Gets the current IronCore document header version as a single byte.


    private
            static    getCurrentDocumentHeaderVersion() : Bytes

Return values

Bytes —

Byte representation of IronCore document header version

getDocumentMagic()

Gets IronCore document magic bytes that are included in every document's preamble


    private
            static    getDocumentMagic() : Bytes

Return values

Bytes —

IronCore document magic bytes

getHeaderSize()

Converts bytes 6 and 7 of the fixed preamble to an integer that represents the length of the header.


    private
            static    getHeaderSize(Bytes $preamble) : int

Parameters

$preamble : Bytes: The first 7 bytes of an IronCore encrypted document

Return values

int —

The length of the IronCore header

splitDocument()

Splits an IronCore encrypted document into its component pieces.


    private
            static    splitDocument(Bytes $document) : DocumentParts

Parameters

$document : Bytes: IronCore encrypted document

Return values

DocumentParts —

Object containing the distinct parts of the document

verifyPreamble()

Verifies that the preamble is the correct length and version, contains the string "IRON", and indicates a valid header length.


    private
            static    verifyPreamble(Bytes $preamble) : bool

Parameters

$preamble : Bytes: The first 7 bytes of an IronCore encrypted document

Return values

bool —

true if the preamble is valid

TenantSecurityClient extends TenantSecurityRequest in package Application Uses Aes

Table of Contents

Constants

BATCH_UNWRAP_ENDPOINT

BATCH_WRAP_ENDPOINT

REKEY_ENDPOINT

SECURITY_EVENT_ENDPOINT

TENANT_KEY_DERIVE_ENDPOINT

TSP_API_PREFIX

UNWRAP_ENDPOINT

WRAP_ENDPOINT

Properties

$apiKey

$ch

$request

$tspAddress

Methods

__construct()

Parameters

Return values

batchDecrypt()

Parameters

Return values

batchEncrypt()

Parameters

Return values

createHeaderProto()

Parameters

Return values

decrypt()

Parameters

Return values

encrypt()

Parameters

Return values

encryptWithExistingKey()

Parameters

Return values

generateHeader()

Parameters

Tags

Return values

generateSignature()

Parameters

Return values

logSecurityEvent()

Parameters

Return values

rekeyEdek()

Parameters

Return values

verifySignature()

Parameters

Return values

batchUnwrapKeys()

Parameters

Tags

Return values

batchWrapKeys()

Parameters

Tags

Return values

makeJsonRequest()

Parameters

Tags

Return values

rekey()

Parameters

Tags

Return values

unwrapKey()

Parameters

Tags

Return values

wrapKey()

Parameters

Tags

Return values

containsIroncoreMagic()

Parameters

TenantSecurityClient extends TenantSecurityRequest
in package

Application

Uses Aes