From 38fe53fcaceecf23352722d4971f628272e6e7c1 Mon Sep 17 00:00:00 2001 From: pfavre Date: Sun, 7 Apr 2019 22:22:39 +0200 Subject: [PATCH] Improve readme and add quickstart tests --- README.md | 49 +++++++++++-- modules/benchmark-jmh/pom.xml | 4 +- modules/id-mask/pom.xml | 2 +- .../at/favre/lib/idmask/QuickstartTests.java | 72 +++++++++++++++++++ pom.xml | 2 +- 5 files changed, 119 insertions(+), 10 deletions(-) create mode 100644 modules/id-mask/src/test/java/at/favre/lib/idmask/QuickstartTests.java diff --git a/README.md b/README.md index e1b1ffb..ba9e91d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,12 @@ # ID Mask - +Id mask is a library for masking public (database) ids to hide the actual value of the id. This should make it harder for an attacker to guess or understand provided ids. Additionally it is possible to generate non-deterministic ids for e.g. shareable links or single use tokens. This library has a similar goal as [HashIds](https://hashids.org/) but depends in contrast on cryptographically strong algorithms. [![Download](https://api.bintray.com/packages/patrickfav/maven/id-mask/images/download.svg)](https://bintray.com/patrickfav/maven/id-mask/_latestVersion) [![Build Status](https://travis-ci.org/patrickfav/id-mask.svg?branch=master)](https://travis-ci.org/patrickfav/id-mask) [![Javadocs](https://www.javadoc.io/badge/at.favre.lib/id-mask.svg)](https://www.javadoc.io/doc/at.favre.lib/id-mask) [![Coverage Status](https://coveralls.io/repos/github/patrickfav/id-mask/badge.svg?branch=master)](https://coveralls.io/github/patrickfav/id-mask?branch=master) [![Maintainability](https://api.codeclimate.com/v1/badges/fc50d911e4146a570d4e/maintainability)](https://codeclimate.com/github/patrickfav/id-mask/maintainability) - - ## Quickstart Add dependency to your `pom.xml` ([check latest release](https://github.com/patrickfav/id-mask/releases)): @@ -19,15 +17,54 @@ Add dependency to your `pom.xml` ([check latest release](https://github.com/patr {latest-version} -A very simple example: +A very simple example using 64 bit integers (long): ```java -tba. +byte[] key = Bytes.random(16).array(); +long id = ... + +IdMask idMask = IdMaskFactory.createForLongIds( + Config.builder().keyManager(KeyManager.Factory.with(key)).build()); + +String maskedId = idMask.mask(id); +long originalId = idMask.unmask(maskedId); +``` + +and using UUIDs + +```java +byte[] key = Bytes.random(16).array(); +UUID id = UUID.fromString("eb1c6999-5fc1-4d5f-b98a-792949c38c45"); + +IdMask idMask = IdMaskFactory.createForUuids( + Config.builder().keyManager(KeyManager.Factory.with(key)).build()); + +String maskedId = idMask.mask(id); +//example: rK0wpnG1lwvG0xiZn5swxOYmAvxhA4A7yg +UUID originalId = idMask.unmask(maskedId); ``` ### Full Example -tba. +```java +byte[] key = Bytes.random(16).array(); +byte[] id128bit = Bytes.random(16).array(); + +IdMask idMask = IdMaskFactory.createFor128bitNumbers( + Config.builder() + .keyManager(KeyManager.Factory.with(key)) + .randomizedIds(true) //non-deterministic output + .enableCache(true) + .cacheImpl(new Cache.SimpleLruMemCache(64)) + .encoding(new ByteToTextEncoding.Base32()) + .secureRandom(new SecureRandom()) + .securityProvider(Security.getProvider("BC")) + .build()); + +String maskedId = idMask.mask(id128bit); +//example: RAKESQ32V37ORV5JX7FAWCFVV2PITRN5KMOKYBJBLNS42WCEA3FI2FIBXLKJGMTSZY +byte[] originalId = idMask.unmask(maskedId); +``` ## Download diff --git a/modules/benchmark-jmh/pom.xml b/modules/benchmark-jmh/pom.xml index ff06c60..2fb71df 100644 --- a/modules/benchmark-jmh/pom.xml +++ b/modules/benchmark-jmh/pom.xml @@ -7,7 +7,7 @@ id-mask-parent at.favre.lib - 1.0.0 + 0.1.0 ../../ @@ -78,7 +78,7 @@ at.favre.lib id-mask - 1.0.0 + 0.1.0 org.hashids diff --git a/modules/id-mask/pom.xml b/modules/id-mask/pom.xml index ab862cd..667f655 100644 --- a/modules/id-mask/pom.xml +++ b/modules/id-mask/pom.xml @@ -7,7 +7,7 @@ id-mask-parent at.favre.lib - 1.0.0 + 0.1.0 ../../ diff --git a/modules/id-mask/src/test/java/at/favre/lib/idmask/QuickstartTests.java b/modules/id-mask/src/test/java/at/favre/lib/idmask/QuickstartTests.java new file mode 100644 index 0000000..583cbeb --- /dev/null +++ b/modules/id-mask/src/test/java/at/favre/lib/idmask/QuickstartTests.java @@ -0,0 +1,72 @@ +package at.favre.lib.idmask; + +import at.favre.lib.bytes.Bytes; +import org.junit.Test; + +import java.security.SecureRandom; +import java.security.Security; +import java.util.Random; +import java.util.UUID; + +import static org.junit.Assert.assertArrayEquals; +import static org.junit.Assert.assertEquals; + +public class QuickstartTests { + + @Test + public void quickstartLong() { + byte[] key = Bytes.random(16).array(); + long id = new Random().nextLong(); + + IdMask idMask = IdMaskFactory.createForLongIds( + Config.builder().keyManager(KeyManager.Factory.with(key)).build()); + + String maskedId = idMask.mask(id); + //example: wMDHT8QN6Ljyko3ma5QLEIE + long originalId = idMask.unmask(maskedId); + + assertEquals(id, originalId); + System.out.println(maskedId); + } + + @Test + public void quickstartUUID() { + byte[] key = Bytes.random(16).array(); + UUID id = UUID.fromString("eb1c6999-5fc1-4d5f-b98a-792949c38c45"); + + IdMask idMask = IdMaskFactory.createForUuids( + Config.builder().keyManager(KeyManager.Factory.with(key)).build()); + + String maskedId = idMask.mask(id); + //example: rK0wpnG1lwvG0xiZn5swxOYmAvxhA4A7yg + UUID originalId = idMask.unmask(maskedId); + + assertEquals(id, originalId); + System.out.println(maskedId); + } + + @Test + public void fullExample() { + byte[] key = Bytes.random(16).array(); + byte[] id128bit = Bytes.random(16).array(); + + IdMask idMask = IdMaskFactory.createFor128bitNumbers( + Config.builder() + .keyManager(KeyManager.Factory.with(key)) + .randomizedIds(true) //non-deterministic output + .enableCache(true) + .cacheImpl(new Cache.SimpleLruMemCache(64)) + .encoding(new ByteToTextEncoding.Base32()) + .secureRandom(new SecureRandom()) + .securityProvider(Security.getProvider("BC")) + .build()); + + String maskedId = idMask.mask(id128bit); + //example: RAKESQ32V37ORV5JX7FAWCFVV2PITRN5KMOKYBJBLNS42WCEA3FI2FIBXLKJGMTSZY + byte[] originalId = idMask.unmask(maskedId); + + assertArrayEquals(id128bit, originalId); + System.out.println(maskedId); + System.out.println(Bytes.wrap(originalId).encodeHex()); + } +} diff --git a/pom.xml b/pom.xml index 474ca50..aa66a1b 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ at.favre.lib id-mask-parent - 1.0.0 + 0.1.0 pom ID Masking Library Parent