crypto: add missing documentation to all pub functions (#8251)
parent
38880b23eb
commit
bce6a35e8f
|
@ -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')
|
||||||
|
|
|
@ -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')
|
||||||
|
|
|
@ -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)
|
||||||
}
|
}
|
||||||
|
|
|
@ -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 {
|
||||||
|
|
|
@ -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()
|
||||||
}
|
}
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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 {
|
||||||
|
|
|
@ -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 {
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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()
|
||||||
}
|
}
|
||||||
|
|
|
@ -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()
|
||||||
}
|
}
|
||||||
|
|
|
@ -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()
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue