# RustCrypto: `crypto_secretstream`

[![crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
![Apache2/MIT licensed][license-image]
![Rust Version][rustc-image]
[![Project Chat][chat-image]][chat-link]
[![Build Status][build-image]][build-link]

Pure Rust implementation of [libsodium]'s [`crypto_secretstream`] primitive,
providing an [AEAD] using [ChaCha20] and [Poly1305].

It is tested against [sodiumoxide], a Rust [libsodium] bindings.

[Documentation][docs-link]

## About

Imagine Alice wants to open a safe channel of communication with Bob,
one that can't be read or modified by anyone else.

One way she can do this is by first agreeing with Bob on a shared secret
key (such as one generated via a key exchange protocol), then she opens a
normal/unsafe channel of communication and sends her messages, encrypted
under this shared key. Then, when Bob receives these messages, he can
decrypt each one and the mere knowledge of this shared key ensures that it
was indeed sent by Alice.

Under the hood, the first message is postfixed with a random number, called
a nonce, generated by Alice, which is taken into account during encryption
and decryption. It is then incremented for each new message.

It also allows for additional data to be sent with each message.
This data is not encrypted but used in the encryption process thus it is
needed to be known in advance by the receiver.
It can be useful for adding another layer of security, and is not of a
fixed size as the key is.

## License

Licensed under either of:

- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT license](http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

### Caveats

- auto-rekeying on counter overflow is not tested
- `Tag::Final` doesn't actually do anything, as [libsodium] does but not [sodiumoxide]
- `Key` and `Nonce` aren't zeroize, maybe it should
- MAC check in `PullStream` is not constant time

[//]: # "badges"
[crate-image]: https://img.shields.io/crates/v/crypto_secretstream.svg
[crate-link]: https://crates.io/crates/crypto_secretstream
[docs-image]: https://docs.rs/crypto_secretstream/badge.svg
[docs-link]: https://docs.rs/crypto_secretstream/
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
[rustc-image]: https://img.shields.io/badge/rustc-1.60+-blue.svg
[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260038-AEADs
[build-image]: https://github.com/RustCrypto/nacl-compat/actions/workflows/crypto_secretstream.yml/badge.svg
[build-link]: https://github.com/RustCrypto/nacl-compat/actions/workflows/crypto_secretstream.yml

[//]: # "general links"
[libsodium]: https://doc.libsodium.org/
[`crypto_secretstream`]: https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream
[aead]: https://en.wikipedia.org/wiki/Authenticated_encryption
[chacha20]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20
[poly1305]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305
[sodiumoxide]: https://github.com/sodiumoxide/sodiumoxide