# 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="https://git.snix.ir/rabaead/plain/seal.png" alt="seal"/>
</p>



### io interfaces:  
- **chunkReader**: read and open() data in chunks, there is 2byte + 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 2byte + 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="https://git.snix.ir/rabaead/plain/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 or package [documentation](https://pkg.go.dev/snix.ir/rabaead) at pkg.go.dev    

```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