diff --git a/README.md b/README.md index 47f71de..8b7a49f 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,67 @@ # xycrypto -## Usage +## Ciphers -```python ->>> from xycrypto.hashes import SHA256 +The `xycrypto` provides simple and elegant interfaces for ciphers. -# Hash byte string using classmethod SHA256.hash. ->>> SHA256.hash(b'Hello, world!') -b'1_[\xdbv\xd0x\xc4;\x8a\xc0\x06NJ\x01da+\x1f\xcew\xc8i4[\xfc\x94\xc7X\x94\xed\xd3' +The cryptography components for ciphers we support: +- Available *stream cipher*: `ARC4`, `ChaCha20`. +- Available *block cipher*: `AES`, `TripleDES`. +- Available *mode*: `ECB`, `CBC`, `OFB`, `CFB`, `CTR`. +- Available *padding*: `PKCS7`, `ANSIX923`, `ISO10126`. -# If you want hex-string. ->>> SHA256.hash(b'Hello, world!').hex() -'315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3' +### Usage -# Hash unicode string, encoded as UTF-8. ->>> SHA256.hash('Hello, world!').hex() -'315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3' +**Firstly**, you should import the cipher class from the package `xycrypto.ciphers`. The cipher class follows the following naming conventions: +- For *stream cipher*, ``. +- For *block cipher*, `_`. -# Hash file using classmethod SHA256.hash_file. ->>> SHA256.hash_file('path/to/file').hex() -'e69bd8e7e0dfadcda3f9785668c3918c469ebbe30fa42fb1158b638afdb9f7f7' +```python +>>> from xycrypto.ciphers import AES_CBC +``` -# Hash directory using classmethod SHA256.hash_dir. ->>> SHA256.hash_dir('path/to/dir').hex() -'746a5c6a0aac95507c96a192071ccdd762b5c69372d0cc66973a1e1dfcc73927' +**Secondly**, you should create the instance of the cipher class. In this case, you should provide some arguments: +- *key* for all ciphers. +- *iv* for *block cipher* in `ECB`, `CBC`, `OFB`, `CFB` mode. +- *nonce* for *block cipher* in `CTR` mode. +- *padding* for *block cipher* in `ECB`, `CBC` mode. -# Context Interface. ->>> ctx = SHA256() ->>> ctx.update(b'Hello, world!') ->>> ctx.finalize().hex() -'315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3' +```python +# The len(key) is 16 bytes for AES-128, you can use 32 bytes key for AES-256. +>>> key = b'0123456789abcdef' +# Note len(iv) should be equal to AES_CBC.block_size. +>>> iv = b'0123456789abcdef' +# We use PKCS7 padding. +>>> cipher = AES_CBC(key, iv=iv, padding='PKCS7') ``` -Support `MD5`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, `SHA3_224`, `SHA3_256`, `SHA3_384`, `SHA3_512`, `SHAKE128`, `SHAKE256`, `BLAKE2b`, `BLAKE2s`. +**Finally**, call `encrypt` or `decrypt` method to encrypt or decrypt data respectively. + +```python +>>> plaintext = b'Welcome to xycrypto!' +>>> ciphertext = cipher.encrypt(plaintext) +>>> ciphertext +b'3\x0f\xad\xa6\x17\xc4}\xb9\t\x17\xf8\xae\xbb\xa2t\xb9o\xf2\xf6\x16\t\x0803\xaci\x0c\x19q\x9d\xa3O' +>>> cipher.decrypt(ciphertext) +b'Welcome to xycrypto!' +``` + +### Example + +```python +>>> from xycrypto.ciphers import AES_CBC + +# The len(key) is 16 bytes for AES-128, you can use 32 bytes key for AES-256. +>>> key = b'0123456789abcdef' +# Note len(iv) should be equal to AES_CBC.block_size. +>>> iv = b'0123456789abcdef' +# We use PKCS7 padding. +>>> cipher = AES_CBC(key, iv=iv, padding='PKCS7') + +>>> plaintext = b'Welcome to xycrypto!' +>>> ciphertext = cipher.encrypt(plaintext) +>>> ciphertext +b'3\x0f\xad\xa6\x17\xc4}\xb9\t\x17\xf8\xae\xbb\xa2t\xb9o\xf2\xf6\x16\t\x0803\xaci\x0c\x19q\x9d\xa3O' +>>> cipher.decrypt(ciphertext) +b'Welcome to xycrypto!' +```