crypto: add missing documentation to all pub functions (#8251)

pull/8298/head
Larpon 2021-01-23 13:33:49 +01:00 committed by GitHub
parent 38880b23eb
commit bce6a35e8f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 58 additions and 16 deletions

View File

@ -12,14 +12,14 @@ pub const (
block_size = 16 block_size = 16
) )
// A cipher is an instance of AES encryption using a particular key. // AesCipher represents an AES encryption using a particular key.
struct AesCipher { struct AesCipher {
mut: mut:
enc []u32 enc []u32
dec []u32 dec []u32
} }
// new_cipher creates and returns a new cipher.Block. // new_cipher creates and returns a new `AesCipher`.
// The key argument should be the AES key, // The key argument should be the AES key,
// either 16, 24, or 32 bytes to select // either 16, 24, or 32 bytes to select
// AES-128, AES-192, or AES-256. // AES-128, AES-192, or AES-256.
@ -38,10 +38,13 @@ pub fn new_cipher(key []byte) AesCipher {
return new_cipher_generic(key) return new_cipher_generic(key)
} }
// block_size returns the block size of the checksum in bytes.
pub fn (c &AesCipher) block_size() int { pub fn (c &AesCipher) block_size() int {
return block_size return block_size
} }
// encrypt encrypts the blocks in `src` to `dst`.
// Please note: `dst` and `src` are both mutable for performance reasons.
pub fn (c &AesCipher) encrypt(mut dst []byte, mut src []byte) { pub fn (c &AesCipher) encrypt(mut dst []byte, mut src []byte) {
if src.len < block_size { if src.len < block_size {
panic('crypto.aes: input not full block') panic('crypto.aes: input not full block')
@ -57,6 +60,8 @@ pub fn (c &AesCipher) encrypt(mut dst []byte, mut src []byte) {
encrypt_block_generic(c.enc, mut dst, src) encrypt_block_generic(c.enc, mut dst, src)
} }
// decrypt decrypts the blocks in `src` to `dst`.
// Please note: `dst` and `src` are both mutable for performance reasons.
pub fn (c &AesCipher) decrypt(mut dst []byte, mut src []byte) { pub fn (c &AesCipher) decrypt(mut dst []byte, mut src []byte) {
if src.len < block_size { if src.len < block_size {
panic('crypto.aes: input not full block') panic('crypto.aes: input not full block')

View File

@ -29,7 +29,7 @@ fn new_aes_cbc(b AesCipher, iv []byte) AesCbc {
} }
} }
// new_cbc_encrypter returns a BlockMode which encrypts in cipher block chaining // new_cbc returns a `AesCbc` which encrypts in cipher block chaining
// mode, using the given Block. The length of iv must be the same as the // mode, using the given Block. The length of iv must be the same as the
// Block's block size. // Block's block size.
pub fn new_cbc(b AesCipher, iv []byte) AesCbc { pub fn new_cbc(b AesCipher, iv []byte) AesCbc {
@ -39,10 +39,13 @@ pub fn new_cbc(b AesCipher, iv []byte) AesCbc {
return new_aes_cbc(b, iv) return new_aes_cbc(b, iv)
} }
// block_size returns the block size of the checksum in bytes.
pub fn (x &AesCbc) block_size() int { pub fn (x &AesCbc) block_size() int {
return x.block_size return x.block_size
} }
// encrypt_blocks encrypts the blocks in `src_` to `dst_`.
// Please note: `dst_` is mutable for performance reasons.
pub fn (x &AesCbc) encrypt_blocks(mut dst_ []byte, src_ []byte) { pub fn (x &AesCbc) encrypt_blocks(mut dst_ []byte, src_ []byte) {
unsafe { unsafe {
mut dst := *dst_ mut dst := *dst_
@ -75,6 +78,8 @@ pub fn (x &AesCbc) encrypt_blocks(mut dst_ []byte, src_ []byte) {
} }
} }
// decrypt_blocks decrypts the blocks in `src` to `dst`.
// Please note: `dst` is mutable for performance reasons.
pub fn (mut x AesCbc) decrypt_blocks(mut dst []byte, src []byte) { pub fn (mut x AesCbc) decrypt_blocks(mut dst []byte, src []byte) {
if src.len % x.block_size != 0 { if src.len % x.block_size != 0 {
panic('crypto.cipher: input not full blocks') panic('crypto.cipher: input not full blocks')

View File

@ -18,15 +18,16 @@ pub fn xor_bytes(mut dst []byte, a []byte, b []byte) int {
return n return n
} }
// n needs to be smaller or equal than the length of a and b. // safe_xor_bytes XORs the bytes in `a` and `b` into `dst` it does so `n` times.
// Please note: `n` needs to be smaller or equal than the length of `a` and `b`.
pub fn safe_xor_bytes(mut dst []byte, a []byte, b []byte, n int) { pub fn safe_xor_bytes(mut dst []byte, a []byte, b []byte, n int) {
for i in 0 .. n { for i in 0 .. n {
dst[i] = a[i] ^ b[i] dst[i] = a[i] ^ b[i]
} }
} }
// fast_xor_words XORs multiples of 4 or 8 bytes (depending on architecture.) // xor_words XORs multiples of 4 or 8 bytes (depending on architecture.)
// The slice arguments a and b are assumed to be of equal length. // The slice arguments `a` and `b` are assumed to be of equal length.
pub fn xor_words(mut dst []byte, a []byte, b []byte) { pub fn xor_words(mut dst []byte, a []byte, b []byte) {
safe_xor_bytes(mut dst, a, b, b.len) safe_xor_bytes(mut dst, a, b, b.len)
} }

View File

@ -10,7 +10,7 @@ const (
npad = []byte{len: 256, init: 0} npad = []byte{len: 256, init: 0}
) )
// Returns an HMAC byte array, depending on the hash algorithm used // new returns a HMAC byte array, depending on the hash algorithm used.
pub fn new(key []byte, data []byte, hash_func fn (bytes []byte) []byte, blocksize int) []byte { pub fn new(key []byte, data []byte, hash_func fn (bytes []byte) []byte, blocksize int) []byte {
mut b_key := []byte{} mut b_key := []byte{}
if key.len <= blocksize { if key.len <= blocksize {
@ -36,7 +36,7 @@ pub fn new(key []byte, data []byte, hash_func fn (bytes []byte) []byte, blocksiz
return digest return digest
} }
// equal compares 2 MACs for equality, without leaking timing info // equal compares 2 MACs for equality, without leaking timing info.
// NB: if the lengths of the 2 MACs are different, probably a completely different // NB: if the lengths of the 2 MACs are different, probably a completely different
// hash function was used to generate them => no useful timing information. // hash function was used to generate them => no useful timing information.
pub fn equal(mac1 []byte, mac2 []byte) bool { pub fn equal(mac1 []byte, mac2 []byte) bool {

View File

@ -51,7 +51,8 @@ pub fn new() &Digest {
return d return d
} }
fn (mut d Digest) write(p_ []byte) int { // write writes the contents of `p_` to the internal hash representation.
pub fn (mut d Digest) write(p_ []byte) int {
unsafe { unsafe {
mut p := p_ mut p := p_
nn := p.len nn := p.len
@ -85,7 +86,8 @@ fn (mut d Digest) write(p_ []byte) int {
} }
} }
fn (d &Digest) sum(b_in []byte) []byte { // sum returns the md5 sum of the bytes in `b_in`.
pub fn (d &Digest) sum(b_in []byte) []byte {
// Make a copy of d so that caller can keep writing and summing. // Make a copy of d so that caller can keep writing and summing.
mut d0 := *d mut d0 := *d
hash := d0.checksum() hash := d0.checksum()
@ -96,6 +98,7 @@ fn (d &Digest) sum(b_in []byte) []byte {
return b_out return b_out
} }
// checksum returns the byte checksum of the `Digest`.
pub fn (mut d Digest) checksum() []byte { pub fn (mut d Digest) checksum() []byte {
// Append 0x80 to the end of the message and then append zeros // Append 0x80 to the end of the message and then append zeros
// until the length is a multiple of 56 bytes. Finally append // until the length is a multiple of 56 bytes. Finally append
@ -134,14 +137,18 @@ fn block(mut dig Digest, p []byte) {
block_generic(mut dig, p) block_generic(mut dig, p)
} }
// size returns the size of the checksum in bytes.
pub fn (d &Digest) size() int { pub fn (d &Digest) size() int {
return size return size
} }
// block_size returns the block size of the checksum in bytes.
pub fn (d &Digest) block_size() int { pub fn (d &Digest) block_size() int {
return block_size return block_size
} }
// hexhash returns a hexadecimal MD5 hash sum `string` of `s`.
// Example: assert md5.hexhash('V') == '5206560a306a2e085a437fd258eb57ce'
pub fn hexhash(s string) string { pub fn hexhash(s string) string {
return sum(s.bytes()).hex() return sum(s.bytes()).hex()
} }

View File

@ -10,6 +10,7 @@ module rand
fn C.SecRandomCopyBytes() int fn C.SecRandomCopyBytes() int
// read returns an array of `bytes_needed` random bytes read from the OS.
pub fn read(bytes_needed int) ?[]byte { pub fn read(bytes_needed int) ?[]byte {
mut buffer := malloc(bytes_needed) mut buffer := malloc(bytes_needed)
status := C.SecRandomCopyBytes(0, bytes_needed, buffer) status := C.SecRandomCopyBytes(0, bytes_needed, buffer)

View File

@ -8,6 +8,7 @@ const (
read_batch_size = 256 read_batch_size = 256
) )
// read returns an array of `bytes_needed` random bytes read from the OS.
pub fn read(bytes_needed int) ?[]byte { pub fn read(bytes_needed int) ?[]byte {
mut buffer := &byte(0) mut buffer := &byte(0)
unsafe { unsafe {

View File

@ -12,6 +12,7 @@ const (
read_batch_size = 256 read_batch_size = 256
) )
// read returns an array of `bytes_needed` random bytes read from the OS.
pub fn read(bytes_needed int) ?[]byte { pub fn read(bytes_needed int) ?[]byte {
mut buffer := &byte(0) mut buffer := &byte(0)
unsafe { unsafe {

View File

@ -13,6 +13,7 @@ const (
bcrypt_use_system_preferred_rng = 0x00000002 bcrypt_use_system_preferred_rng = 0x00000002
) )
// read returns an array of `bytes_needed` random bytes read from the OS.
pub fn read(bytes_needed int) ?[]byte { pub fn read(bytes_needed int) ?[]byte {
mut buffer := malloc(bytes_needed) mut buffer := malloc(bytes_needed)
// use bcrypt_use_system_preferred_rng because we passed null as algo // use bcrypt_use_system_preferred_rng because we passed null as algo

View File

@ -54,8 +54,9 @@ pub fn new() &Digest {
return d return d
} }
// write writes the contents of `p_` to the internal hash representation.
[manualfree] [manualfree]
fn (mut d Digest) write(p_ []byte) int { pub fn (mut d Digest) write(p_ []byte) int {
nn := p_.len nn := p_.len
unsafe { unsafe {
mut p := p_ mut p := p_
@ -89,7 +90,8 @@ fn (mut d Digest) write(p_ []byte) int {
return nn return nn
} }
fn (d &Digest) sum(b_in []byte) []byte { // sum returns a copy of the generated sum of the bytes in `b_in`.
pub fn (d &Digest) sum(b_in []byte) []byte {
// Make a copy of d so that caller can keep writing and summing. // Make a copy of d so that caller can keep writing and summing.
mut d0 := *d mut d0 := *d
hash := d0.checksum() hash := d0.checksum()
@ -100,6 +102,7 @@ fn (d &Digest) sum(b_in []byte) []byte {
return b_out return b_out
} }
// checksum returns the byte checksum of the `Digest`.
fn (mut d Digest) checksum() []byte { fn (mut d Digest) checksum() []byte {
mut len := d.len mut len := d.len
// Padding. Add a 1 bit and 0 bits until 56 bytes mod 64. // Padding. Add a 1 bit and 0 bits until 56 bytes mod 64.
@ -123,7 +126,7 @@ fn (mut d Digest) checksum() []byte {
return digest return digest
} }
// Sum returns the SHA-1 checksum of the data. // sum returns the SHA-1 checksum of the bytes passed in `data`.
pub fn sum(data []byte) []byte { pub fn sum(data []byte) []byte {
mut d := new() mut d := new()
d.write(data) d.write(data)
@ -136,14 +139,17 @@ fn block(mut dig Digest, p []byte) {
block_generic(mut dig, p) block_generic(mut dig, p)
} }
// size returns the size of the checksum in bytes.
pub fn (d &Digest) size() int { pub fn (d &Digest) size() int {
return size return size
} }
// block_size returns the block size of the checksum in bytes.
pub fn (d &Digest) block_size() int { pub fn (d &Digest) block_size() int {
return block_size return block_size
} }
// hexhash returns a hexadecimal SHA1 hash sum `string` of `s`.
pub fn hexhash(s string) string { pub fn hexhash(s string) string {
return sum(s.bytes()).hex() return sum(s.bytes()).hex()
} }

View File

@ -89,6 +89,7 @@ pub fn new224() &Digest {
return d return d
} }
// write writes the contents of `p_` to the internal hash representation.
fn (mut d Digest) write(p_ []byte) int { fn (mut d Digest) write(p_ []byte) int {
unsafe { unsafe {
mut p := p_ mut p := p_
@ -171,7 +172,8 @@ fn (mut d Digest) checksum() []byte {
return digest return digest
} }
// sum256 returns the SHA256 checksum of the data. // sum returns the SHA256 checksum of the bytes in `data`.
// Example: assert sha256.sum('V'.bytes()).len > 0 == true
pub fn sum(data []byte) []byte { pub fn sum(data []byte) []byte {
return sum256(data) return sum256(data)
} }
@ -199,6 +201,7 @@ fn block(mut dig Digest, p []byte) {
block_generic(mut dig, p) block_generic(mut dig, p)
} }
// size returns the size of the checksum in bytes.
pub fn (d &Digest) size() int { pub fn (d &Digest) size() int {
if !d.is224 { if !d.is224 {
return size return size
@ -206,14 +209,18 @@ pub fn (d &Digest) size() int {
return size224 return size224
} }
// block_size returns the block size of the checksum in bytes.
pub fn (d &Digest) block_size() int { pub fn (d &Digest) block_size() int {
return block_size return block_size
} }
// hexhash returns a hexadecimal SHA256 hash sum `string` of `s`.
// Example: assert sha256.hexhash('V') == 'de5a6f78116eca62d7fc5ce159d23ae6b889b365a1739ad2cf36f925a140d0cc'
pub fn hexhash(s string) string { pub fn hexhash(s string) string {
return sum256(s.bytes()).hex() return sum256(s.bytes()).hex()
} }
// hexhash_224 returns a hexadecimal SHA224 hash sum `string` of `s`.
pub fn hexhash_224(s string) string { pub fn hexhash_224(s string) string {
return sum224(s.bytes()).hex() return sum224(s.bytes()).hex()
} }

View File

@ -60,7 +60,7 @@ const (
init7_384 = u64(0x47b5481dbefa4fa4) init7_384 = u64(0x47b5481dbefa4fa4)
) )
// digest represents the partial evaluation of a checksum. // Digest represents the partial evaluation of a checksum.
struct Digest { struct Digest {
mut: mut:
h []u64 h []u64
@ -148,6 +148,7 @@ fn new384() &Digest {
return new_digest(.sha384) return new_digest(.sha384)
} }
// write writes the contents of `p_` to the internal hash representation.
fn (mut d Digest) write(p_ []byte) int { fn (mut d Digest) write(p_ []byte) int {
unsafe { unsafe {
mut p := p_ mut p := p_
@ -271,7 +272,7 @@ pub fn sum512_224(data []byte) []byte {
return sum224 return sum224
} }
// Sum512_256 returns the Sum512/256 checksum of the data. // sum512_256 returns the Sum512/256 checksum of the data.
pub fn sum512_256(data []byte) []byte { pub fn sum512_256(data []byte) []byte {
mut d := new_digest(.sha512_256) mut d := new_digest(.sha512_256)
d.write(data) d.write(data)
@ -287,6 +288,7 @@ fn block(mut dig Digest, p []byte) {
block_generic(mut dig, p) block_generic(mut dig, p)
} }
// size returns the size of the checksum in bytes.
pub fn (d &Digest) size() int { pub fn (d &Digest) size() int {
match d.function { match d.function {
.sha512_224 { return size224 } .sha512_224 { return size224 }
@ -296,22 +298,27 @@ pub fn (d &Digest) size() int {
} }
} }
// block_size returns the block size of the checksum in bytes.
pub fn (d &Digest) block_size() int { pub fn (d &Digest) block_size() int {
return block_size return block_size
} }
// hexhash returns a hexadecimal SHA512 hash sum `string` of `s`.
pub fn hexhash(s string) string { pub fn hexhash(s string) string {
return sum512(s.bytes()).hex() return sum512(s.bytes()).hex()
} }
// hexhash_384 returns a hexadecimal SHA384 hash sum `string` of `s`.
pub fn hexhash_384(s string) string { pub fn hexhash_384(s string) string {
return sum384(s.bytes()).hex() return sum384(s.bytes()).hex()
} }
// hexhash_512_224 returns a hexadecimal SHA512/224 hash sum `string` of `s`.
pub fn hexhash_512_224(s string) string { pub fn hexhash_512_224(s string) string {
return sum512_224(s.bytes()).hex() return sum512_224(s.bytes()).hex()
} }
// hexhash_512_256 returns a hexadecimal 512/256 hash sum `string` of `s`.
pub fn hexhash_512_256(s string) string { pub fn hexhash_512_256(s string) string {
return sum512_256(s.bytes()).hex() return sum512_256(s.bytes()).hex()
} }