Skip to content

README_EN.md

Latest commit

 

History

History
167 lines (131 loc) · 8.4 KB

README_EN.md

File metadata and controls

167 lines (131 loc) · 8.4 KB

secureQR-module

한국어 README
SecureQR is a QR code library that can prevent forgery and tampering available in Java.

Get Started

You can use SecureQR by adding the JAR file as an external library to your Java project.

Download

Download JAR file from the github release tab

How to SecureQR Works?

howtowork

  1. Scan the QR code (generated by secureQR-module) through secureQR reader.
  2. Data and other information are sent to the server by secureQR-module-android.
  3. The server decrypts the data and certifies that it is valid.
  4. If decryption and authentication are successful, the original data is sent back to the mobile app

secureQR example

Usage

crypto

Interface SecureQrCrypto
By implementing the SecureQrCrypto interface, you can use custom cryptographic objects with secureQR.

Type Method Description
String getInstanceType() Returns the type of the current instance as a string. If it is a cryptographic object, it returns "CRYPTO".
String getMethodType() Returns the encryption method as a string.
String encrypt(String message) Returns a string encrypted message.
String decrypt(String message) Returns a string that decrypts the message.

Interface SecureQrHash
By implementing the SecureQrHash interface, you can use custom hash functions with secureQR.

Type Method Description
String getInstanceType() Returns the type of the current instance as a string. If it is a hash object, it returns "HASH".
String getMethodType() Returns the hash function method as a string.
String hashing(String message) Returns hashed message.

class SecureQrCryptoArray
Arrays to store SecureQrHash, SecureQrCrypto and data. Hash, encryption method is stored in crypto_arr via MethodPair and data is stored in data_arr.

Type Method Description
Constructor SecureQrCryptoArray() Initialize crypto_arr and data_arr to an empty ArrayList.
int crypto_size() Returns the size of crypto_arr.
int data_size() Returns the size of data_arr.
void add(SecureQrHash _h, SecureQrCrypto _c) Add hash, crypto pair to crypto_arr.
SecureQrHash getHash(int index) Get the hash method at the index location.
SecureQrCrypto getCrypto(int index) Get the encryption method at the index location.
int addData(String _data) Add data to data_arr and return the index where the data is located. This index is required for secureQR authentication.
String getData(int index) Get the data at index position.

qr_util

class MethodPair
A pair of hash objects and cryptographic objects.

Type Method Description
Constructor MethodPair(SecureQrHash _h, SecureQrCrypto _c) Initialize MethodPair with parameters.
SecureQrCrypto getCrypto() Returns the stored cryptographic object.
SecureQrHash getHash() Returnsthe stored hash object.

class RandomString
A class that generates a random string.

Type Method Description
String getString(int length) Returns a random string of arbitrary length.

qr

Interface Generatable
By implementing the Generatable interface, you can create secure QR code in two ways.

Return Type Method Params Description
byte[] createSecureQRcode() SecureQrCryptoArray arr : the array in which the data for encrypting is stored
String authUrl : Assigned authentication server URL
int c_index : index of Hasing method.
int d_index : index of Data stored in SecureQrCryptoArray
int width, int height : the size of QR image width and height		 Returns byte array of image format PNG.
boolean createSecureQRImage() byte[] qr_byte_arr : the data which is encrypted
int off : starting offset
String path : your desired file path		 Save secureQR on your local drive
then, Returns the boolean as a result

class Generator
Generates an encrypted secure QR image with hashing method, encryption method.

Type Method Description
byte[] createSecureQRCode(SecureQrCryptoArray arr, String authUrl, int c_index, int d_index, int width, int height) To pass it to the server to decrypt secure QR image, it creates serialized Json form first.
Then, get an access to SecureQrCryptoArray arr with c_index and d_index to specify which data needs to be Encrypted.
Finally, Create QR code image, formatted PNG.
Return its byte data to the caller
bool createSecureQRImage(byte[] qr_byte_arr, int off, String path) To save secureQR image on caller's disk,
it tries to save on specific file path as argument entered.
Returns its success or failure

TODO reading

class AuthQR
A class that authenticates secureQR.

Type Method Description
Constructor AuthQR(SecureQrCryptoArray arr) Initialize AuthQR by registering SecureQrCryptoArray to be used for secureQR authentication.
boolean isSecureQR(String read_data) Check whether the data is the same as the data format in secureQR.
String getOriginData(String encrypted, int c_index, int d_index) Decrypts the data using the encryption and hash method in c_index and checks whether the data is correct by comparing it with the data in d_index. If all checks have passed, return the original data.

Build

This project can be built with gradle.
If you run jar among gradle tasks, you can find the compiled jar file in /build/libs/secureQR-module-x.y.z.jar

dependency

  • zxing:core 3.4.1
  • zxing:javase 3.4.1
  • gson 2.8.8

Open Source Lisence

Copyright

Component Version Homepage License
Zxing 3.4.1 https://github.com/zxing/zxing Apache-2.0 License
Gson 2.8.8 https://github.com/google/gson Apache-2.0 License
Junit 4.13.2 https://junit.org/junit4 Eclipse Public License 1.0

Contribution

Reporting bugs

Bugs are tracked as GitHub issues.
Create an issue on this repository and if possible, please provide the following information.

  • Use a clear and descriptive title
  • Describe the exact steps which reproduce the problem
  • Include screenshots and animated GIFs

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.
Create an issue on this repository and if possible, please provide the following information.

  • Describe the current behavior and explain which behavior you expected to see instead and why
  • Include screenshots and animated GIFs
  • Explain why this enhancement would be useful

Open Pull Requests

A Pull Requests (PR) is the step where you submit patches to this repository.
(e.g. adding features, renaming a variable for clarity, translating into a new language)

If you're not familiar with pull requests, you can follow these steps.

  1. Fork this project and clone your fork
git clone https://github.com/<user-name>/secureQR-module.git
cd secureQR-module
  1. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix
git checkout -b <topic-branch-name>
git pull
  1. Developing a new feature
  2. Push the feature to your fork
git push origin <topic-branch-name>
  1. Open a Pull Requests with a description