Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use README as crate docs #537

Merged
merged 4 commits into from
Jan 10, 2024
+823 −1,117
Merged

Use README as crate docs #537

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
feedc95
Use README as crate docs
newpavlov Jan 10, 2024
2947190
Remove some #[rustfmt::skip]
newpavlov Jan 10, 2024
da2ee9e
Remove dangling references
newpavlov Jan 10, 2024
743d95f
Update licensing information
newpavlov Jan 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ The SHA-1 implementation was previously published as `sha-1`, but migrated to `s

MSRV bumps are considered breaking changes and will be performed only with minor version bump.

## Usage
## Examples

Let us demonstrate how to use crates in this repository using SHA-2 as an example.

Expand Down Expand Up @@ -215,10 +215,10 @@ let hash2_1 = use_hasher(&mut *hasher2, b"foo");

## License

All crates licensed under either of
All crates in this repository are licensed under either of

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

at your option.

Expand Down
1 change: 1 addition & 0 deletions ascon-hash/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ ascon = { version = "0.4", default-features = false }
[dev-dependencies]
spectral = { version = "0.6", default-features = false }
hex = "0.4"
hex-literal = "0.4"

[features]
default = ["std"]
Expand Down
2 changes: 1 addition & 1 deletion ascon-hash/LICENSE-MIT
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Copyright (c) 2023-2024 The RustCrypto Project Developers
Copyright (c) 2022-2023 Sebastian Ramacher <[email protected]>
Copyright (c) 2023 The RustCrypto Project Developers

Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
Expand Down
37 changes: 32 additions & 5 deletions ascon-hash/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,40 @@ Pure Rust implementation of the lightweight cryptographic hash functions
[AsconHash and AsconAHash][1] and the extendable output functions (XOF) AsconXOF
and AsconAXOF.

[Documentation][docs-link]

## Security Notes

No security audits of this crate have ever been performed.

USE AT YOUR OWN RISK!

## Examples
Fixed output size hashing:
```rust
use ascon_hash::{AsconHash, Digest};
use hex_literal::hex;

let mut hasher = AsconHash::new();
hasher.update(b"some bytes");
let hash = hasher.finalize();

assert_eq!(hash, hex!("b742ca75e57038757059cccc6874714f9dbd7fc5924a7df4e316594fd1426ca8"));
```

XOF hashing:
```rust
use ascon_hash::{AsconXof, ExtendableOutput, Update, XofReader};
use hex_literal::hex;

let mut xof = AsconXof::default();
xof.update(b"some bytes");
let mut reader = xof.finalize_xof();
let mut dst = [0u8; 5];
reader.read(&mut dst);
assert_eq!(dst, hex!("c21972fde9"));
```

Also, see the [examples section] in the RustCrypto/hashes readme.

## Minimum Supported Rust Version

This crate requires **Rust 1.71** at a minimum.
Expand All @@ -28,10 +54,10 @@ version bump.

## License

Licensed under either of:
The crate is licensed under either of:

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

at your option.

Expand All @@ -57,3 +83,4 @@ dual licensed as above, without any additional terms or conditions.
[//]: # (general links)

[1]: https://ascon.iaik.tugraz.at
[examples section]: https://github.com/RustCrypto/hashes#Examples
27 changes: 0 additions & 27 deletions ascon-hash/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
// Copyright 2022-2023 Sebastian Ramacher
// SPDX-License-Identifier: Apache-2.0 OR MIT

#![no_std]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![doc = include_str!("../README.md")]
Expand All @@ -10,30 +7,6 @@
)]
#![warn(missing_docs)]

//! ## Usage (Hashing)
//!
//! ```
//! use ascon_hash::{AsconHash, Digest}; // Or `AsconAHash`
//!
//! let mut hasher = AsconHash::new();
//! hasher.update(b"some bytes");
//! let digest = hasher.finalize();
//! assert_eq!(&digest[..], b"\xb7\x42\xca\x75\xe5\x70\x38\x75\x70\x59\xcc\xcc\x68\x74\x71\x4f\x9d\xbd\x7f\xc5\x92\x4a\x7d\xf4\xe3\x16\x59\x4f\xd1\x42\x6c\xa8");
//! ```
//!
//! ## Usage (XOF)
//!
//! ```
//! use ascon_hash::{AsconXof, ExtendableOutput, Update, XofReader};
//!
//! let mut xof = AsconXof::default();
//! xof.update(b"some bytes");
//! let mut reader = xof.finalize_xof();
//! let mut dst = [0u8; 5];
//! reader.read(&mut dst);
//! assert_eq!(&dst, b"\xc2\x19\x72\xfd\xe9");
//! ```

use core::marker::PhantomData;

use ascon::{pad, State};
Expand Down
21 changes: 17 additions & 4 deletions belt-hash/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,19 @@

Pure Rust implementation of the [BelT] hash function specified in [STB 34.101.31-2020].

[Documentation][docs-link]
## Examples
```rust
use belt_hash::{BeltHash, Digest};
use hex_literal::hex;

let mut hasher = BeltHash::new();
hasher.update(b"hello world");
let hash = hasher.finalize();

assert_eq!(hash, hex!("afb175816416fbadad4629ecbd78e1887789881f2d2e5b80c22a746b7ac7ba88"));
```

Also, see the [examples section] in the RustCrypto/hashes readme.

## Minimum Supported Rust Version

Expand All @@ -25,10 +37,10 @@ done with a minor version bump.

## License

Licensed under either of:
The crate is licensed under either of:

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

at your option.

Expand All @@ -55,3 +67,4 @@ dual licensed as above, without any additional terms or conditions.

[BelT]: https://ru.wikipedia.org/wiki/BelT
[STB 34.101.31-2020]: http://apmi.bsu.by/assets/files/std/belt-spec371.pdf
[examples section]: https://github.com/RustCrypto/hashes#Examples
40 changes: 6 additions & 34 deletions belt-hash/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,6 @@
//! Pure Rust implementation of the [BelT] hash function specified in
//! [STB 34.101.31-2020].
//!
//! # Usage
//!
//! ```rust
//! use belt_hash::{BeltHash, Digest};
//! use hex_literal::hex;
//!
//! // create a BelT hasher instance
//! let mut hasher = BeltHash::new();
//!
//! // process input message
//! hasher.update(b"hello world");
//!
//! // acquire hash digest in the form of Array,
//! // which in this case is equivalent to [u8; 32]
//! let result = hasher.finalize();
//! let expected = hex!(
//! "afb175816416fbadad4629ecbd78e1887789881f2d2e5b80c22a746b7ac7ba88"
//! );
//! assert_eq!(result[..], expected[..]);
//! ```
//!
//! Also see [examples] in the RustCrypto/hashes readme.
//!
//! [BelT]: https://ru.wikipedia.org/wiki/BelT
//! [STB 34.101.31-2020]: http://apmi.bsu.by/assets/files/std/belt-spec371.pdf
//! [examples]: https://github.com/RustCrypto/hashes#usage
#![no_std]
#![doc = include_str!("../README.md")]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
Expand All @@ -52,6 +25,9 @@ use digest::{
};

const U32_MASK: u128 = (1 << 32) - 1;
const H0: [u32; 8] = [
0xC8BA94B1, 0x3BF5080A, 0x8E006D36, 0xE45D4A58, 0x9DFA0485, 0xACC7B61B, 0xC2722E25, 0x0DCEFD02,
];

/// Core BelT hasher state.
#[derive(Clone)]
Expand Down Expand Up @@ -128,11 +104,7 @@ impl Default for BeltHashCore {
Self {
r: 0,
s: [0; 4],
#[rustfmt::skip]
h: [
0xC8BA94B1, 0x3BF5080A, 0x8E006D36, 0xE45D4A58,
0x9DFA0485, 0xACC7B61B, 0xC2722E25, 0x0DCEFD02,
],
h: H0,
}
}
}
Expand Down
7 changes: 2 additions & 5 deletions belt-hash/tests/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,7 @@ fn belt_rand() {
let mut h = BeltHash::new();
feed_rand_16mib(&mut h);
assert_eq!(
h.finalize()[..],
hex!(
"a45053f80827d530008198c8185aa507"
"403b4a21f591579f07c34358e5991754"
)[..]
h.finalize(),
hex!("a45053f80827d530008198c8185aa507403b4a21f591579f07c34358e5991754")
);
}
6 changes: 3 additions & 3 deletions blake2/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ hex-literal = "0.4"
default = ["std"]
std = ["digest/std"]
reset = [] # Enable reset functionality
simd = []
simd_opt = ["simd"]
simd_asm = ["simd_opt"]
#simd = []
#simd_opt = ["simd"]
#simd_asm = ["simd_opt"]
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably should finish #228 before publishing blake2 v0.11.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, definitely been meaning to do it. Would be great to get it over the finish line.

size_opt = [] # Optimize for code size. Removes some `inline(always)`
71 changes: 65 additions & 6 deletions blake2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,67 @@
![Rust Version][rustc-image]
[![Project Chat][chat-image]][chat-link]

Pure Rust implementation of the [BLAKE2 hash function][1] family.
Pure Rust implementation of the [BLAKE2] hash function family.

[Documentation][docs-link]
## Examples

### Fixed output size

```rust
use blake2::{Blake2b512, Blake2s256, Digest};
use hex_literal::hex;

// create a Blake2b512 object
let mut hasher = Blake2b512::new();

// write input message
hasher.update(b"hello world");

// read hash digest and consume hasher
let res = hasher.finalize();
assert_eq!(res, hex!(
"021ced8799296ceca557832ab941a50b4a11f83478cf141f51f933f653ab9fbc"
"c05a037cddbed06e309bf334942c4e58cdf1a46e237911ccd7fcf9787cbc7fd0"
));

// same example for Blake2s256:
let mut hasher = Blake2s256::new();
hasher.update(b"hello world");
let res = hasher.finalize();
assert_eq!(res, hex!("9aec6806794561107e594b1f6a8a6b0c92a0cba9acf5e5e93cca06f781813b0b"));
```

Also, see the [examples section] in the RustCrypto/hashes readme.

### Variable output size

This implementation supports run and compile time variable sizes.

Output size set at run time:
```rust
use blake2::Blake2bVar;
use blake2::digest::{Update, VariableOutput};
use hex_literal::hex;

let mut hasher = Blake2bVar::new(10).unwrap();
hasher.update(b"my_input");
let mut buf = [0u8; 10];
hasher.finalize_variable(&mut buf).unwrap();
assert_eq!(buf, hex!("2cc55c84e416924e6400"));
```

Output size set at compile time:
```rust
use blake2::{Blake2b, Digest, digest::consts::U10};
use hex_literal::hex;

type Blake2b80 = Blake2b<U10>;

let mut hasher = Blake2b80::new();
hasher.update(b"my_input");
let res = hasher.finalize();
assert_eq!(res, hex!("2cc55c84e416924e6400"));
```

## Minimum Supported Rust Version

Expand All @@ -25,10 +83,10 @@ done with a minor version bump.

## License

Licensed under either of:
The crate is licensed under either of:

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

at your option.

Expand All @@ -53,4 +111,5 @@ dual licensed as above, without any additional terms or conditions.

[//]: # (general links)

[1]: https://blake2.net/
[BLAKE2]: https://blake2.net/
[examples section]: https://github.com/RustCrypto/hashes#Examples
Loading
Loading