Aes
Cryptographic functions. Not intended to be used by consumers of the SDK.
Table of Contents
- createHeaderProto() : V3DocumentHeader
- Make a V3DocumentHeader with a SaaSShieldHeader and a generated signature.
- 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.
- verifySignature() : bool
- Verifies a document header's signature.
- 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.
Methods
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
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
Tags
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
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
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
Tags
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
Tags
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
Tags
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
Tags
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
Tags
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
Tags
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