Hiss

Hiss is an encryption and hashing library which aims to make encrypting domain objects easier while support key rotation and even algorithm change.

Key Features:

Key rotation and algorithm change by storing key ID and algorithm name alongside encrypted content.
Supporting multiple algorithms.
Supports encrypted and plain data during decryption.
Spring Boot and Spring Data Mongo integration support.

Quick Start

1. Add Hiss dependency

Apache Maven:

<dependency>
    <groupId>io.github.tap30</groupId>
    <artifactId>hiss</artifactId>
    <version>0.11.1</version>
</dependency>

Gradle (Groovy):

implementation 'io.github.tap30:hiss:0.11.1'

Gradle (Kotlin):

implementation("io.github.tap30:hiss:0.11.1")

2. Create Hiss instance via `HissFactory`

var hiss = HissFactory.createHiss(() -> HissProperties.fromBase64EncodedKeys(
    Map.of("default_key", "AAAAAAAAAAAAAAAAAAAAAA=="),
    "default_key",
    "aes-128-gcm",
    "default_key",
    "hmac-sha256"
));

3. Annotate your class with `@Encrypted`

import io.github.tap30.hiss.Encrypted;
import io.github.tap30.hiss.EncryptedInside;

public class User {
    @Encrypted
    private String phoneNumber;
    private String hashedPhoneNumber;
    @EncryptedInside
    private List<Address> addresses;

    // getters and setters
}

public class Address {
    private String name;
    private String street;
    private String city;
    private String state;
    @Encrypted(hashingEnabled = false)
    private String postalCode;

    // getters and setters
}

Note: Getters and setters must exist as Hiss use them to get/set values.

4. Call `hiss.encryptObject(user)` to encrypt the object and `hiss.decryptObject(user)` to decrypt it.

By calling those method, all annotated fields will be encrypted/decrypted; also, during encryption, the hash of the content will be calculated and stored in hashedX (in this case hashedPhoneNumber).

Hiss and Spring Boot

Hiss integration with Spring Boot is available; see this.

Hiss Instantiation

For creating a Hiss instance, HissFactory$createHiss(HissPropertiesProvider) can be used; HissPropertiesProvider is an interface which its implementations will create a HissProperties instance.

HissProperties

HissProperties has all the configuration Hiss needs.

HissProperties contains:

keys: the map of key ID to key bytes; Hiss uses this map to encrypt and decrypt contents.
defaultEncryptionKeyId: the key ID which Hiss uses to encrypt contents.
defaultEncryptionAlgorithm: the algorithm which Hiss uses to encrypt contents.
defaultHashingKeyId: the key ID which Hiss uses to create hash of contents.
defaultHashingAlgorithm: the algorithm which Hiss uses to create hash of contents.

HissPropertiesFromEnvProvider

HissPropertiesProvider should be implemented by the client of Hiss, but there is a HissPropertiesFromEnvProvider class which, as the name suggest, creates HissProperties from environment variables:

HISS_KEYS_(Key ID): mapped to keys; all environment variables which start with HISS_KEYS_ expected to be base64 encoded keys; for example HISS_KEYS_KEY_1=AAAAAAAAAAAAAAAAAAAAAA== will be a key with ID key_1 and value of 16 zero bytes.

HISS_DEFAULT_ENCRYPTION_KEY_ID: mapped to defaultEncryptionKeyId

HISS_DEFAULT_ENCRYPTION_ALGORITHM: mapped to defaultEncryptionAlgorithm

HISS_DEFAULT_HASHING_KEY_ID: mapped to defaultHashingKeyId

HISS_DEFAULT_HASHING_ALGORITHM: mapped to defaultHashingAlgorithm

Encryption

By using @Encrypted annotation and calling Hiss$encryptObject(Object), Hiss will know which fields are needed to be encrypted; also, there are Hiss$encrypt(String) and Hiss$encrypt(String, String) methods, which just encrypt provided string and return encrypted content.

Hiss is smart enough to know if a field requires encryption/decryption; in another word Hiss won't re-encrypt encrypted content and decrypt plain text.

Supported algorithms are:

aes-128-gcm: which translates to AES/GCM/NoPadding having 16 bytes for tag and 16 bytes for IV.
aes-128-cbc: which translates to AES/CBC/PKCS5Padding having 16 bytes for IV.

Encrypted data has the following format: #$$#{algorithm:key_id}{encypted_content}#$$#; which key_id is the ID of the key that the content was encrypted with, algorithm is the algorithm name mentioned above and encypted_content is base64 encoding of iv bytes + encrypted content bytes.

Hiss will use getters and setters to read/change value of a field.

Partial Encryption

With Hiss it is possible to encrypt only some parts of an string.

As an example having:

import io.github.tap30.hiss.Encrypted;

public class Message {

    @Encrypted(pattern = "\\d+")
    private String content = "Your code is 123456";
    private String hashedContent;

    // getters and setter
}

after encryption content will be Your code is #$$#{aes-128-gcm:default_key}{RCnPlJc5H/yeygBEm0wBpgZBrtlOlvWetHpUaBO3oqQSrQXARSw=}#$$# and hashedContent will be #$$#{hmac-sha256:default_key}{29l4zNu+i23nf2s3td+bW2Kn6JKlAcO1PqoWsIOL1e0=}#$$#.

`@Encrypted` Annotation

@Encrypted annotation can be applied on class fields by which Hiss will know which fields should be encrypted/decrypted.

Only String fields can be annotated with @Encrypted; for other (non-primitive) types use @EncryptedInside.

@Encrypted parameters are:

pattern: the pattern which only matched content will be encrypted; empty or null values mean all content should be encrypted.
hashingEnabled: should Hiss calculate and store hash of content.
hashFieldName: name of the field in which hashed content will be put; empty or null values mean the name will be guessed. The guessing algorithm is by concatenating "hashed" and first-letter-capitalized field name. e.g. if the name of the encrypted field is phoneNumber, guessed hashed field name is hashedPhoneNumber.

`@EncryptedInside` Annotation

@EncryptedInside tells Hiss to scan fields inside object.

Having T as a non-primitive type, T, subtypes of Iterable<T> (e.g. Set<T>, List<T>, ...) and, subtypes of Map<?, T> can be annotated with @EncryptedInside.

Examples below are valid:

public class ValidEncryptedInsideUsage {
    @EncryptedInside
    private Address address;
    
    @EncryptedInside
    private List<Address> addressList;
    
    @EncryptedInside
    private Map<String, Address> addressMap;
    
    // getters and setters ...
}

Hashing

As we may want to search on encrypted content and as Hiss adds a random IV to each encrypted content, no-salt hashing is required.

Hiss supports keyed hash functionality; currently hmac-sha256 is only supported.

Hashed content format is like encrypted content.

Tap30/hiss