add doc (#43)

.gitignore

@@ -8,5 +8,3 @@ Cargo.lock
 
 # These are backup files generated by rustfmt
 **/*.rs.bk
-
-.vscode/settings.json

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "spellright.language": ["en"],
+  "spellright.documentTypes": ["markdown", "latex", "plaintext", "rust"]
+}

.vscode/spellright.dict

@@ -0,0 +1,10 @@
+ecies
+eciespy
+secp256k1
+keypair
+helloworld
+sk
+hkdf
+Codacy
+eciesrs
+rng

Cargo.toml

@@ -1,30 +1,32 @@
 [package]
 name = "ecies"
-description = "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Rust"
 version = "0.1.5"
-license = "MIT"
+# docs
 authors = ["Weiliang Li <[email protected]>"]
+description = "Elliptic Curve Integrated Encryption Scheme for secp256k1 in Rust"
 edition = "2018"
-repository = "https://github.com/ecies/rs"
-documentation = "https://github.com/ecies/rs"
-homepage = "https://github.com/ecies/rs"
+license = "MIT"
 readme = "README.md"
+# links
+documentation = "https://docs.rs/ecies/latest/ecies/"
+homepage = "https://ecies.org/rs/"
+repository = "https://github.com/ecies/rs"
 
 [dependencies]
-rand = "0.7.3"
-libsecp256k1 = "0.3.5"
-hex ="0.4.2"
-openssl ="0.10"
+hex = "0.4.2"
 hkdf = "0.10.0"
+libsecp256k1 = "0.3.5"
+openssl = "0.10"
+rand = "0.7.3"
 sha2 = "0.9.1"
 
 [dev-dependencies]
-tokio = "0.2.22"
-reqwest = "0.10.8"
 criterion = "0.3.3"
 futures-util = "0.3.6"
+reqwest = "0.10.8"
+tokio = "0.2.22"
 
 [[bench]]
+harness = false
 name = "simple"
 path = "bench/simple.rs"
-harness = false

README.md

@@ -4,6 +4,7 @@
 [![License](https://img.shields.io/github/license/ecies/rs.svg)](https://github.com/ecies/rs)
 [![Circle CI](https://img.shields.io/circleci/project/ecies/rs/master.svg)](https://circleci.com/gh/ecies/rs)
 [![Crates](https://img.shields.io/crates/v/ecies)](https://crates.io/crates/ecies)
+[![Doc](https://docs.rs/ecies/badge.svg)](https://docs.rs/ecies/latest/ecies/)
 
 Elliptic Curve Integrated Encryption Scheme for secp256k1 in Rust, based on [pure Rust implementation](https://github.com/paritytech/libsecp256k1) of secp256k1.
 
@@ -35,7 +36,7 @@ assert_eq!(
 
 ## Release Notes
 
-### 0.1.1 ~ 0.1.4
+### 0.1.1 ~ 0.1.5
 
 - Bump dependencies
 - Update documentation

src/lib.rs

@@ -1,9 +1,36 @@
-use secp256k1::{util::FULL_PUBLIC_KEY_SIZE, Error as SecpError, PublicKey, SecretKey};
-
+//! Elliptic Curve Integrated Encryption Scheme for secp256k1 in Rust, based on [pure Rust implementation](https://github.com/paritytech/libsecp256k1) of secp256k1.
+//!
+//! This is the Rust version of [eciespy](https://github.com/ecies/py).
+//!
+//! # Usage
+//!
+//! ```rust
+//! use ecies::{decrypt, encrypt, utils::generate_keypair};
+//!
+//! const MSG: &str = "helloworld";
+//! let (sk, pk) = generate_keypair();
+//! let (sk, pk) = (&sk.serialize(), &pk.serialize());
+//!
+//! let msg = MSG.as_bytes();
+//! assert_eq!(
+//!     msg,
+//!     decrypt(sk, &encrypt(pk, msg).unwrap()).unwrap().as_slice()
+//! );
+//! ```
+
+pub use secp256k1::{util::FULL_PUBLIC_KEY_SIZE, Error as SecpError, PublicKey, SecretKey};
+
+/// Utility functions for ecies
 pub mod utils;
 
 use utils::{aes_decrypt, aes_encrypt, decapsulate, encapsulate, generate_keypair};
 
+/// Encrypt a message by a public key
+///
+/// # Arguments
+///
+/// * `receiver_pub` - The u8 array reference of a receiver's public key
+/// * `msg` - The u8 array reference of the message to encrypt
 pub fn encrypt(receiver_pub: &[u8], msg: &[u8]) -> Result<Vec<u8>, SecpError> {
     let receiver_pk = PublicKey::parse_slice(receiver_pub, None)?;
     let (ephemeral_sk, ephemeral_pk) = generate_keypair();
@@ -18,6 +45,12 @@ pub fn encrypt(receiver_pub: &[u8], msg: &[u8]) -> Result<Vec<u8>, SecpError> {
     Ok(cipher_text)
 }
 
+/// Decrypt a message by a secret key
+///
+/// # Arguments
+///
+/// * `receiver_sec` - The u8 array reference of a receiver's secret key
+/// * `msg` - The u8 array reference of the encrypted message
 pub fn decrypt(receiver_sec: &[u8], msg: &[u8]) -> Result<Vec<u8>, SecpError> {
     let receiver_sk = SecretKey::parse_slice(receiver_sec)?;
 

src/utils.rs

@@ -10,24 +10,29 @@ const AES_TAG_LENGTH: usize = 16;
 const AES_IV_PLUS_TAG_LENGTH: usize = AES_IV_LENGTH + AES_TAG_LENGTH;
 const EMPTY_BYTES: [u8; 0] = [];
 
+/// Type alias for `[u8; 32]`, which is a 256-bit key
 pub type AesKey = [u8; 32];
 
+/// Generate a `(SecretKey, PublicKey)` pair
 pub fn generate_keypair() -> (SecretKey, PublicKey) {
     let sk = SecretKey::random(&mut thread_rng());
     (sk.clone(), PublicKey::from_secret_key(&sk))
 }
 
+/// Remove 0x prefix of a hex string
 pub fn remove0x(hex: &str) -> &str {
     if hex.starts_with("0x") || hex.starts_with("0X") {
         return &hex[2..];
     }
     hex
 }
 
+/// Convert hex string to u8 vector
 pub fn decode_hex(hex: &str) -> Vec<u8> {
     decode(remove0x(hex)).unwrap()
 }
 
+/// Calculate a shared AES key of our secret key and peer's public key by hkdf
 pub fn encapsulate(sk: &SecretKey, peer_pk: &PublicKey) -> AesKey {
     let mut shared_point = peer_pk.clone();
     shared_point.tweak_mul_assign(&sk).unwrap();
@@ -39,6 +44,7 @@ pub fn encapsulate(sk: &SecretKey, peer_pk: &PublicKey) -> AesKey {
     hkdf_sha256(master.as_slice())
 }
 
+/// Calculate a shared AES key of our public key and peer's secret key by hkdf
 pub fn decapsulate(pk: &PublicKey, peer_sk: &SecretKey) -> AesKey {
     let mut shared_point = pk.clone();
     shared_point.tweak_mul_assign(&peer_sk).unwrap();
@@ -50,6 +56,7 @@ pub fn decapsulate(pk: &PublicKey, peer_sk: &SecretKey) -> AesKey {
     hkdf_sha256(master.as_slice())
 }
 
+/// AES-256-GCM encryption wrapper
 pub fn aes_encrypt(key: &[u8], msg: &[u8]) -> Option<Vec<u8>> {
     let cipher = Cipher::aes_256_gcm();
 
@@ -70,6 +77,7 @@ pub fn aes_encrypt(key: &[u8], msg: &[u8]) -> Option<Vec<u8>> {
     }
 }
 
+/// AES-256-GCM decryption wrapper
 pub fn aes_decrypt(key: &[u8], encrypted_msg: &[u8]) -> Option<Vec<u8>> {
     if encrypted_msg.len() < AES_IV_PLUS_TAG_LENGTH {
         return None;