# armadillo

**Repository Path**: archermind-ti/armadillo

## Basic Information

- **Project Name**: armadillo
- **Description**: A preference implementation for secret data providing confidentiality, integrity and authenticity. Per default uses AES-GCM, BCrypt and HKDF as cryptographic primitives.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-04-12
- **Last Updated**: 2021-08-30

## Categories & Tags

**Categories**: security-dev

**Tags**: None

## README

## Armadillo

### Overview

A preference implementation for secret data providing confidentiality, integrity and authenticity. Per default uses AES-GCM, BCrypt and HKDF as cryptographic primitives.

### Features

* **No-Nonse State-of-the-Art Crypto**: Authenticated Encryption with [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)-[GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode), key derivation functions [Bcrypt](https://en.wikipedia.org/wiki/Bcrypt) and [HKDF](https://en.wikipedia.org/wiki/HKDF)
* **Flexible**: Tons of nobs and switches while having sane defaults
* **Modular**: use your own implementation of symmetric cipher, key stretching, data obfuscation, etc.
* **Lightweight**: No massive dependencies required like [BouncyCastle](https://www.bouncycastle.org/) or [Facebook Conceal](https://github.com/facebook/conceal)

#### Security Summary

- Using it **with a user provided password** (and strong password hash, like the default BCrypt): **your data is strongly encrypted**
- Using it without a user provided password: **your data is obfuscated and cannot be easily altered or read by an attacker with access to the device**
- By using fingerprinting, it is **not easily possible to just copy data over to another device** and use it there
- Encryption is **non-deterministic**, which means even if you encrypt the same data it **appears to be different**
- All encrypted data is **protected against modification by an outside attacker**, so long as the encryption itself is not circumvented

### Quick Start

1. Add mavenCentral repository

   ```groovy
   allprojects {
       repositories {
           ...
           mavenCentral()
       }
   }
   ```

2. Add the following to your dependencies 

   ```groovy
   implementation 'com.gitee.archermind-ti:armadillo:1.0.0'
   ```

### How to use

```java
Armadillo.Builder builder = Armadillo.create(this, "your preferences file name")
        .encryptionFingerprint(this, "replace your secret(custom)");
ArmadilloSharedPreferences encryptedPreferences=encryptedPreferences = builder.build();

encryptedPreferences.putString("key","value").flush();
String value = encryptedPreferences.getString("key", null);
```



The following example shows some of the configurations available to the developer:

```java
String userId = ...
String openHarmonyId=...
    
ArmadilloSharedPreferences preferences = Armadillo.create(context, "myCustomPreferences")
        .password("mySuperSecretPassword".toCharArray()) //use user provided password
        .securityProvider(Security.getProvider("BC")) //use bouncy-castle security provider
        .keyStretchingFunction(new PBKDF2KeyStretcher()) //use PBKDF2 as user password kdf
        .contentKeyDigest(Bytes.from(openHarmonyId).array()) //use custom content key digest salt
        .secureRandom(new SecureRandom()) //provide your own secure random for salt/iv generation
        .encryptionFingerprint(context, userId.getBytes(StandardCharsets.UTF_8)) //add the user id to fingerprint
        .supportVerifyPassword(true) //enables optional password validation support `.isValidPassword()`
        .enableDerivedPasswordCache(true) //enable caching for derived password making consecutive getters faster
        .build();
```



### Compile 

- Git clone the project to the local
- Use DevEco Studio to open Armadillo, and then wait for the Gradle build to complete
- Click `Run` to run (the real machine may need to configure the signature)

### License

```
Copyright 2017 Patrick Favre-Bulle

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
```