The Basics
About
The Absio SDK provides basic cryptographic operations: key generation, key exchange, encyption/decryption, HMAC, signing, hashing and elliptic curve cryptography (ECC). A custom Integrated Encryption Scheme (IES) for confidentiality and source verification is included as part of the ECC features.
Users
In the SDK a user is a person or system. Users are represented as a GUID and only have context when using Absio IES to encrypt and decrypt. Users will have a set of keys. See Keys for more information on the types of keys supported.
Keys
There are two types of keys related to Users: Signing and Derivation. Signing keys are used to source verification (who encrypted the data). Derivation keys are used as part of the key generation process (key exchange for encrypt/decrpyt operations).
Quick Start
Getting Started
This Quick start guide is intended to help you begin playing around with the Absio SDKs right away.
Need more info on the technology and tools? Check out [The Basics](#the basics) section.
Want to dig deeper into the Absio SDKs? See our complete API documentation.
Java
This SDK was written with the Java 7 language level, but was tested exclusively against Java 8. This may not work for Java versions greater than 8.
JCE
Java uses the JCE to perform all cryptographic operations. The SDK requires one modification to the JDK/JRE being used (for the JCE) as well as one initialization to ensure the JCE Absio depends on is used.
Java Cryptography Extension (JCE) Unlimited Strength
In order to use the SDK to perform any cryptography, the JDK/JRE must be updated for the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files(this is for JDK 1.8).
Absio's Required JCE
The SDK depends on the OpenSSLProvider from Conscrypt as the JCE. It is set by simply calling
Security.insertProviderAt(new OpenSSLProvider(), 1);
before any SDK operations are performed.
Install
Through maven you can include the SDK dependency.
<dependency>
<groupId>com.absio</groupId>
<artifactId>absio-sdk</artifactId>
<version>SDK_VERSION_NUMBER</version>
</dependency>
For 1.5.3 it would be
<dependency>
<groupId>com.absio</groupId>
<artifactId>absio-sdk</artifactId>
<version>1.5.3</version>
</dependency>
This will only work if you also reference the Absio Nexus.
<repository>
<id>absio-nexus</id>
<url>https://nexus.absio.com/repository/maven-releases/</url>
</repository>
Initialize
See the Java section above to ensure that the JDK/JRE are updated to the unlimited strength and the JCE is initialized by calling
Security.insertProviderAt(new OpenSSLProvider(), 1);
before the SDK is used.
Symmetric Features
The SDK will perform symmetric key generation, encryption and decryption. By default the SDK will use AES 256.
Symmetric Key Generation
CipherHelper helper = new CipherHelper();
byte[] aes256Key = helper.generateKey();
Symmetric Encryption
CipherHelper helper = new CipherHelper();
byte[] ciphertextBytes = helper.encrypt(keyBytes, ivBytes, plaintextBytes);
Symmetric Decryption
CipherHelper helper = new CipherHelper();
byte[] plaintextBytes = helper.decrypt(keyBytes, ivBytes, ciphertextBytes);
Hashing
By default the SDK will use SHA384 for hashing operations.
MessageDigestHelper helper = new MessageDigestHelper();
byte[] hashBytes = helper.digest(dataBytes);
Absio Integrated Encryption Scheme
Included in the ECC module is a special Integrated Encryption Scheme. In this scheme ECDH is computed using the recipient user's public derivation key. The resultant key is used to encrypt the data. That data is then signed with the sending user's signing key. By default this will use AES 256 CTR NoPadding along with ECDH and ECDSA both using curve P384. There is also a simple command line utility to perform the encrypt and decrypt operations.
Absio IES Encrypt
AbsioIESHelper helper = new AbsioIESHelper();
byte[] iesDataBytes = helper.encrypt(plaintextBytes, signingPrivateKey, derivationPublicKey, senderId, objectId
Absio IES Decrypt
AbsioIESHelper helper = new AbsioIESHelper();
byte[] plaintextBytes = helper.decrypt(iesData, signingPublicKey, derivationPrivateKey);
Key Derivation Function
The SDK can be used to derive keys using KDF2 as well. By default it will generate keys using a SHA384 Message Digest.
KDF2Helper helper = new KDF2Helper();
byte[] keyBytes = helper.deriveKey(secretBytes, keySizeInBytes);
Password Based Key Derivation Function
The SDK can be used to derive keys using PBKDF2 as well. By default it will use HMACSHA384, AES256 in CTR mode with no padding and UTF-8 encoding.
Key Generation
PBKDF2Helper helper = new PBKDF2Helper();
byte[] keyBytes = helper.generateDerivedKey(password, salt, iterationCount);
Encrypt
PBKDF2Helper helper = new PBKDF2Helper();
byte[] formattedCiphertextBytes = helper.encryptToFormat(plaintextBytes, saltBytes, "password", 100000);
Decrypt
PBKDF2Helper helper = new PBKDF2Helper();
byte[] plaintextBytes = helper.decryptFromFormat(formattedCiphertextBytes, "password", 100000);
Asymmetric Features
The SDK can generate key pairs and perform encryption and decryption with Absio IES. By default this will create Elliptic Curve keys.
Asymmetric Key Generation
KeyPairHelper helper = new KeyPairHelper();
KeyPair p384KeyPair = helper.generateKeyPair(EllipticCurve.P384);
Diffie-Hellman Key Exchange
The SDK can compute the shared secret for a Diffie-Hellman key exchange. By default it will do ECDH.
KeyAgreementHelper helper = new KeyAgreementHelper();
byte[] sharedSecretBytes = helper.generateSharedSecret(privateKey, publicKey);
HMAC
The SDK will perform HMAC operations to ensure data integrity. By default it will perform HMAC-SHA384.
Key Generation
MacHelper helper = new MacHelper();
SecretKey key = helper.generateKey();
Digest
MacHelper helper = new MacHelper();
byte[] digestBytes = helper.digest(secretKey, dataBytes);
Digest Verify
MacHelper helper = new MacHelper();
boolean verified = helper.verify(secretKey, dataBytes, digestBytes);
Signature
The SDK can perform signing operations: sign and verify. By default it will perform ECDSA signing with SHA384.
Signing
SignatureHelper helper = new SignatureHelper();
byte[] signatureBytes = helper.sign(privateKey, dataBytes);
Signature Verification
SignatureHelper helper = new SignatureHelper();
byte[] signatureBytes = helper.verify(publicKey, dataBytes, signatureBytes);
Elliptic Curve Cryptograpy Operations
The SDK has a helper class (ECCHelper) to perform all the basic ECC operations. This allows you to use a single helper to perform all ECC operations. See below for its usage. By default this will use curve P384 and AES256 for the IES encryption.
Generate Key
ECCHelper helper = new ECCHelper();
KeyPair keyPair = helper.generateKey();
ECDH Generate Shared Key
ECCHelper helper = new ECCHelper();
byte[] keyBytes = helper.generateDHSharedKey(privateKey, publicKey);
ECDH Generate Shared Secret
ECCHelper helper = new ECCHelper();
byte[] secretBytes = helper.generateDHSharedSecret(privateKey, publicKey);
Absio IES Encrypt
ECCHelper helper = new ECCHelper();
byte[] iesDataBytes = helper.absioIESEncrypt(plaintextBytes, signingPrivateKey, derivationPublicKey, senderId, objectId);
IES Decrypt
ECCHelper helper = new ECCHelper();
byte[] plaintextBytes = helper.absioIESDecrypt(iesData, signingPublicKey, derivationPrivateKey);
Sign
ECCHelper helper = new ECCHelper();
byte[] signatureBytes = helper.sign(privateKey, dataBytes);
Verify Signature
ECCHelper helper = new ECCHelper();
byte[] signatureBytes = helper.verifySignature(publicKey, dataBytes, signatureBytes);
SDK Resources
API Documentation
You can find the Java SDK API documentation on GitHub.
Library
You can find the platform independent Java SDK on the Absio Nexus. If you would like a combined jar (with all dependencies) that is platfrom dependent) you can also pull those down from the Absio Nexus.
32 bit combined Java SDK
64 bit combined Java SDK
Support
Support and Bug Reporting
General Support and Feedback
Please contact us at support@absio.com if you experience any issues using this site, want to submit feedback, or have general questions about the technology.
Bug Reporting
Please use the relevant GitHub Issue Tracker to report any bugs.
Licenses
Visit the Absio documentation website to read the Software License Agreement. Visit the Java SDK repository for relevant third-party license information.