git add files

1 files changed, 73 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..8b3336e
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,73 @@
+# rabaead
+rabbit128 poly1305 aead cipher package for golang, this package implement aead (authenticated encryption with associated data) cipher
+with associated io chunk and io stream interfaces.
+
+### aead methods:
+- **seal**: seals a plaintext into the rabbit aead ciphertext. **panic** occurs if nonce len is not equal to IVXLen (8byte) or zero
+- **open**: opens a rabbit aead ciphertext. **panic** occurs if nonce len is not equal to IVXLen (8byte) or zero
+
+<p align="center">
+   <img src="seal.png" alt="seal"/>
+</p>
+
+
+
+### io interfaces:  
+- **chunkReader**: read and open() data in chunks, there is 8byte + 16byte overhead per chunk. read data can be used safely. this reader has a chunk size in-memory buffer, large chunk size can make application to runs out of memory, thus this is most suitable for sliced data, like network data transmit and so..
+
+- **chunkReader**: seal() and write data in chunks, there is 8byte + 16byte overhead per chunk. this writer has a chunk size in-memory buffer, large chunk size can make application to runs out of memory, thus this is most suitable for sliced data, like network data transmit and so..
+<p align="center">
+   <img src="chunkio.png" alt="chunkio"/>
+</p>
+
+- **streamReader**: this reader open() and read aead ciphertext which have 16-byte poly1305 tag overhead. **read data is unreliable until underlying reader returns EOF**, after that Read return EOF or ErrAuthMsg if integrity of data has been compromised. in such a case, you need to unread data. a simple demonstration would be to delete or truncate the file if ErrAuthMsg is returned
+
+
+- **streamWriter**: this writer seal() and write aead plaintext which have 16-byte poly1305 tag overhead, running Close() is necessary in order to calculate and write tag at the end of the write.
+
+
+### how to use?
+rabaead lives on both [github](github.com/sina-ghaderi/rabaead) and [snix](git.snix.ir/rabaead) git services, you can simply import this package 
+by using either `import "snix.ir/rabaead"` or `import "github.com/sina-ghaderi/rabaead"`
+
+
+### examples
+check out [_example](_example) directory which contains real-world use cases of rabaead cipher, in addition you may want to look at test unit files.  
+
+```go
+// aead open() and seal() methods
+func rabbitPoly1305() {
+	key := []byte{
+		0x01, 0x01, 0x01, 0x01,
+		0x01, 0x01, 0x01, 0x01,
+		0x01, 0x01, 0x01, 0x01,
+		0x01, 0x01, 0x01, 0x01,
+	}
+	ivx := []byte{
+		0x01, 0x01, 0x01, 0x01,
+		0x01, 0x01, 0x01, 0x01,
+	}
+	buff := []byte("plain-text")
+	aead, err := rabaead.NewAEAD(key)
+	if err != nil {
+		panic(err)
+	}
+	ctxt := aead.Seal([]byte{}, ivx, buff, nil)
+	fmt.Printf("aead data: %x\n", ctxt)
+	ptxt, err := aead.Open([]byte{}, ivx, ctxt, nil)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("plaintext: %s\n", string(ptxt))
+}
+
+```
+
+### licence and contribute
+feel free to email me sina@snix.ir if you want to contribute to this project.
+GNU General Public [License](LICENSE) v3
+
+
+
+
+