Using encryption and decryption APIs

Space and Time enables transparent In-DB encryption of your data through our Encryption APIs. This guide covers all information needed to understand and use SxT encryption.

Runtime considerations

Interacting with an encrypted table is quite simple - simply alter the API endpoints you'd use to interact with a non-encrypted table. Whereas a normal query would be executed via POST <BASE_URL>/v1/sql/dql, to execute a query against an encrypted table you should use POST <BASE_URL>/v1/encryption/sql/dql. DML is much the same - just add the encryption prefix and no other change is necessary. The request input is exactly the same between the encrypted and non-encrypted APIs.

If you use JDBC to interact with SxT, no worries - as long as you're using the most recent JDBC driver, it will automatically pick the correct endpoint for you.

From an authorization perspective, there is also no difference in a non-encrypted table. If you can authorize the query request, you are authorized to decrypt all columns in the table. Authorizing column-level decryption via biscuits is in the roadmap - check back later for more details!

🚧
Data NOT inserted through the encryption API endpoints will NOT be encrypted. For this reason, if you accidentally insert data that is not encrypted, you also won't be able to access that data via the encrypted DQL API. It can however still be read from the normal DQL API.

Configuration considerations

Configuring encryption on your table(s) is also a straightforward process, but there are a few precursors to be aware of, including:

The table(s) must already exist (i.e., you must create the table in one request and encrypt it in another request)
Applying encryption will ALTER the table, so you must be authorized with ALTER permission on the table you're configuring
You cannot encrypt an already-encrypted table
You cannot change encryption configuration, so make sure you double check the request before you send it
Any pre-existing data will not automatically be encrypted - make sure to configure encryption before adding any sensitive data to your table

Join operations on encrypted tables currently have a few limitations, which will be removed over time. Currently:

Both tables must be in the same schema
Both tables must encrypted at the same time (i.e., in the same Configure API request)
The column(s) on which you want to join must have the same encryption type and encryption option

Encryption types and when to use them

Deterministic encryption (DET)

Deterministic encryption ensures that a given input value will always produce the same encrypted output value. However, this makes it more susceptible to frequency analysis attacks. This method is useful when you want to have identical encrypted outputs for identical inputs, for example when comparing encrypted values without having to decrypt them. However, because it is susceptible to frequency analysis, it's less suitable for very sensitive data.

Encryption types:

NONE

Encryption is performed without any additional formatting.

Applicability: Both strings and numbers, can include special characters
Suggested data type: String

LIKE

Encrypted data is searchable using SQL LIKE operators.

Applicability: Both strings and numbers, can include special characters
Suggested data type: String

Format-preserving encryption (FPE)

FPE maintains the format of the input data after encryption. It is useful for encrypting data that needs to conform to specific formats or patterns. It is suggested to use "FPE UNICODE" over "FPE ASCII" because it supports a larger set of characters. FPE is primarily used in situations where the format of the data is important and needs to be retained after encryption. This can be particularly useful when credit card numbers, social security numbers, or account numbers need to retain their formats.

Encryption types:

ASCII

Only encrypts characters in the ASCII character set.

Applicability: Both strings and numbers, does not include special characters
Suggested data type: String

EASCII

Encrypted data is in extended ASCII format.

Applicability: Both strings and numbers, does not include special characters
Suggested data type: String
Extended range of characters: 'â' ,'ä' ,'à' ,'á' ,'ã' ,'å' ,'ç' ,'ñ' ,'¢' ,'é' ,'ê' ,'ë' ,'è' ,'í' ,'î' ,'ï' ,'ì' ,'ß' ,'¬' ,'Â' ,'Ä' ,'À' ,'Á' ,'Ã' ,'Å' ,'Ç' ,'Ñ' ,'¦' ,'ø' ,'É' ,'Ê' ,'Ë' ,'È' ,'Í' ,'Î' ,'Ï' ,'Ì','Ø' ,'a' ,'b' ,'c' ,'d' ,'e' ,'f' ,'g' ,'h' ,'i' ,'«' ,'»' ,'ð' ,'ý' ,'þ' ,'±' ,'°' ,'j' ,'k' ,'l' ,'m' ,'n' ,'o' ,'p' ,'q' ,'r' ,'a' ,'o' ,'æ' , '̧' ,'Æ' ,'μ' ,'s' ,'t' ,'u' ,'v' ,'w' ,'x' ,'y' ,'z' ,'¡' ,'¿' ,'Ð' ,'Ý' ,'Þ' ,'®' ,'·' ,'©' ,'§' ,'¶' ,'1⁄4' ,'1⁄2' ,'3⁄4' ,' ̄' ,' ̈' ,' ́' ,'×' ,'A' ,'B' ,'C' ,'D' ,'E' ,'F' ,'G' ,'H' ,'I' ,'ô' ,'ö' ,'ò' ,'ó' ,'õ' ,'J' ,'K' ,'L' ,'M' ,'N' ,'O' ,'P' ,'Q' ,'R' ,'1' ,'û' ,'ü' ,'ù' ,'ú' ,'ÿ' ,'÷' ,'S' ,'T' ,'U' ,'V' ,'W' ,'X' ,'Y' ,'Z' ,'2' ,'Ô' ,'Ö' ,'Ò' ,'Ó' ,'Õ' ,'0' ,'1' ,'2' ,'3' ,'4' ,'5' ,'6' ,'7' ,'8' ,'9' ,'3' ,'Û' ,'Ü' ,'Ù' ,'Ú'.

EBCDIC

Encrypted data is in EBCDIC format, including the EBCDIC set of predefined special characters. Any EBCDIC characters not part of the defined alphabet will throw an invalid input error.

Applicability: Both strings and numbers, does not include special characters
Suggested data type: String
Extended range of characters: ¤!"#$%&'()*+,-./:;<=>?@[]^_ `{|}~£¥€\E{Space}

UNICODE

Encrypted data is in Unicode format.

Applicability: Both strings and numbers.
Suggested data type: String

NUMERIC

Encrypted data is numeric.

Applicability: Only numbers, does not include special characters
Suggested data type: Number

NUMERIC_NONSTRICT

Designed to encrypt strings that contain both numbers and non-numeric characters, such as phone numbers that may have hyphens or extensions. The encrypted data is numeric but not strictly enforced as a pure number.

Applicability: Strings with numbers and non-numeric characters, and may include special characters like hyphens or extensions
Suggested data type: Number with hyphens or extensions

NUMERICLP

Encrypted data is numeric and left-padded with zeros.

Applicability: Only numbers, and does not include special characters
Suggested data type: String with numbers or just numbers

FPE_DAY

Only encrypts the day value for the format YYYY/MM/DD, YYYY-MM-DD, or YYYYMMDD. This method is perfect for situations where only the day value in a date needs to be encrypted, keeping the month and year values visible.

Encryption types:

NONE

Encryption is performed without any additional formatting. This is the only valid type for FPE_DAY.

Applicability: Only strings with numeric data in the specified format, includes special characters like slashes and hyphens
Suggested data type: Date

FPE_TOKEN

FPE Token is a specific encryption method that uses Format-Preserving Encryption (FPE) to create encrypted tokens. These tokens retain the original format of the data, such as the length and character set, while providing strong security. This method is useful when you want to replace sensitive data with non-sensitive data (tokens) while maintaining the format of the original data.

Encryption types:

Valid encryption types are the exact same as FPE, please reference FPE type above.

MASK

Masking is a technique used to replace sensitive data with non-sensitive data, while maintaining the format of the original data. Must be in the format YYYY/MM/DD, YYYY-MM-DD, or YYYYMMDD. Data masking is typically used when certain portions of data need to be obscured. This ensures that sensitive data is not exposed while maintaining the usability of the dataset.

Encryption types:

MASK_DAY

Encrypted data is masked with a day value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_DAY_RANDOM

Encrypted data is masked with a random day value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_MONTH

Encrypted data is masked with a month value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_MONTH_DAY

Encrypted data is masked with a month and day value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_YEAR

Encrypted data is masked with a year value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_YEAR_MONTH

Encrypted data is masked with a year and month value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_YEAR_DAY

Encrypted data is masked with a year and day value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

MASK_FULL_DATE

Encrypted data is masked with a full date value.

Applicability: Only strings, includes special characters like slashes and hyphens
Suggested data type: Date

OPE (Order-Preserving Encryption)

OPE stands for Order Preserving Encryption which retains the order in which the encrypted values should be implemented. This only works with integers. OPE is useful when performing operations that require the order of the data to be preserved, such as range queries. This makes it particularly useful in databases where range queries are common.

Encryption types:

NONE

No additional options available.

Applicability: Only numbers, does not include special characters
Suggested data type: Number