About Encryption
Understand encryption types and trade-offs to pick the best option for your use case.
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 withALTER
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
Updated about 1 year ago