package core:crypto/hash
Source

⌘K
Ctrl+K
or
/

    Overview

    package hash provides a generic interface to the supported hash algorithms.

    A high-level convenience procedure group hash is provided to easily accomplish common tasks. hash_string - Hash a given string and return the digest. hash_bytes - Hash a given byte slice and return the digest. hash_string_to_buffer - Hash a given string and put the digest in the third parameter. It requires that the destination buffer is at least as big as the digest size. hash_bytes_to_buffer - Hash a given string and put the computed digest in the third parameter. It requires that the destination buffer is at least as big as the digest size. hash_stream - Incrementally fully consume a io.Stream, and return the computed digest. hash_file - Takes a file handle and returns the computed digest. A third optional boolean parameter controls if the file is streamed (default), or or read at once.

    Example: 
    package hash_example

import "core:crypto/hash"

main :: proc() {
	input := "Feed the fire."

	// Compute the digest, using the high level API.
	returned_digest := hash.hash(hash.Algorithm.SHA512_256, input)
	defer delete(returned_digest)

	// Variant that takes a destination buffer, instead of returning
	// the digest.
	digest := make([]byte, hash.DIGEST_SIZES[hash.Algorithm.BLAKE2B]) // @note: Destination buffer has to be at least as big as the digest size of the hash.
	defer delete(digest)
	hash.hash(hash.Algorithm.BLAKE2B, input, digest)
}

    A generic low level API is provided supporting the init/update/final interface that is typical with cryptographic hash function implementations.

    Example: 
    package hash_example

import "core:crypto/hash"

main :: proc() {
	input := "Let the cinders burn."

	// Compute the digest, using the low level API.
	ctx: hash.Context
	digest := make([]byte, hash.DIGEST_SIZES[hash.Algorithm.SHA3_512])
	defer delete(digest)

	hash.init(&ctx, hash.Algorithm.SHA3_512)
	hash.update(&ctx, transmute([]byte)input)
	hash.final(&ctx, digest)
}

    Types

    Algorithm ¶
    Source

    Algorithm :: enum int {
	Invalid, 
	BLAKE2B, 
	BLAKE2S, 
	SHA224, 
	SHA256, 
	SHA384, 
	SHA512, 
	SHA512_256, 
	SHA3_224, 
	SHA3_256, 
	SHA3_384, 
	SHA3_512, 
	SM3, 
	Legacy_KECCAK_224, 
	Legacy_KECCAK_256, 
	Legacy_KECCAK_384, 
	Legacy_KECCAK_512, 
	Insecure_MD5, 
	Insecure_SHA1, 
}
     

    Algorithm is the algorithm identifier associated with a given Context.

    Related Procedures With Parameters
    Related Procedures With Returns

    Context ¶
    Source

    Context :: struct {
	_algo: Algorithm,
	_impl: union {
		_blake2.Blake2b_Context, 
		_blake2.Blake2s_Context, 
		sha2.Context_256, 
		sha2.Context_512, 
		sha3.Context, 
		sm3.Context, 
		keccak.Context, 
		md5.Context, 
		sha1.Context, 
	},
}
     

    Context is a concrete instantiation of a specific hash algorithm.

    Related Procedures With Parameters

    Constants

    MAX_BLOCK_SIZE ¶
    Source

    MAX_BLOCK_SIZE :: sha3.BLOCK_SIZE_224
     

    MAX_BLOCK_SIZE is the maximum block size used by any of Algorithms supported by this package.

    MAX_DIGEST_SIZE ¶
    Source

    MAX_DIGEST_SIZE :: 64
     

    MAX_DIGEST_SIZE is the maximum size digest that can be returned by any of the Algorithms supported via this package.

    Variables

    ALGORITHM_NAMES ¶
    Source

    ALGORITHM_NAMES: [Algorithm]string = …
     

    ALGORITHM_NAMES is the Algorithm to algorithm name string.

    BLOCK_SIZES ¶
    Source

    BLOCK_SIZES: [Algorithm]int = …
     

    BLOCK_SIZES is the Algoritm to block size in bytes.

    DIGEST_SIZES ¶
    Source

    DIGEST_SIZES: [Algorithm]int = …
     

    DIGEST_SIZES is the Algorithm to digest size in bytes.

    Procedures

    algorithm ¶
    Source

    algorithm :: proc(ctx: ^Context) -> Algorithm {…}
     

    algorithm returns the Algorithm used by a Context instance.

    block_size ¶
    Source

    block_size :: proc(ctx: ^Context) -> int {…}
     

    block_size returns the block size of a Context instance in bytes.

    clone ¶
    Source

    clone :: proc(ctx, other: ^Context) {…}
     

    clone clones the Context other into ctx.

    digest_size ¶
    Source

    digest_size :: proc(ctx: ^Context) -> int {…}
     

    digest_size returns the digest size of a Context instance in bytes.

    final ¶
    Source

    final :: proc(ctx: ^Context, hash: []u8, finalize_clone: bool = false) {…}
     

    final finalizes the Context, writes the digest to hash, and calls reset on the Context.

    Iff finalize_clone is set, final will work on a copy of the Context, which is useful for for calculating rolling digests.

    hash_bytes ¶
    Source

    hash_bytes :: proc(algorithm: Algorithm, data: []u8, allocator := context.allocator) -> []u8 {…}
     

    hash_bytes will hash the given input and return the computed digest in a newly allocated slice.

    hash_bytes_to_buffer ¶
    Source

    hash_bytes_to_buffer :: proc(algorithm: Algorithm, data, hash: []u8) -> []u8 {…}
     

    hash_bytes_to_buffer will hash the given input and write the computed digest into the third parameter. It requires that the destination buffer is at least as big as the digest size. The provided destination buffer is returned to match the behavior of hash_bytes.

    hash_file ¶
    Source

    hash_file :: proc(algorithm: Algorithm, hd: os.Handle, load_at_once: bool = false, allocator := context.allocator) -> ([]u8, io.Error) {…}
     

    hash_file will read the file provided by the given handle and return the computed digest in a newly allocated slice.

    hash_stream ¶
    Source

    hash_stream :: proc(algorithm: Algorithm, s: io.Stream, allocator := context.allocator) -> ([]u8, io.Error) {…}
     

    hash_stream will incrementally fully consume a stream, and return the computed digest in a newly allocated slice.

    hash_string ¶
    Source

    hash_string :: proc(algorithm: Algorithm, data: string, allocator := context.allocator) -> []u8 {…}
     

    hash_bytes will hash the given input and return the computed digest in a newly allocated slice.

    hash_string_to_buffer ¶
    Source

    hash_string_to_buffer :: proc(algorithm: Algorithm, data: string, hash: []u8) -> []u8 {…}
     

    hash_string_to_buffer will hash the given input and assign the computed digest to the third parameter. It requires that the destination buffer is at least as big as the digest size. The provided destination buffer is returned to match the behavior of hash_string.

    init ¶
    Source

    init :: proc(ctx: ^Context, algorithm: Algorithm) {…}
     

    init initializes a Context with a specific hash Algorithm.

    reset ¶
    Source

    reset :: proc(ctx: ^Context) {…}
     

    reset sanitizes the Context. The Context must be re-initialized to be used again.

    update ¶
    Source

    update :: proc(ctx: ^Context, data: []u8) {…}
     

    update adds more data to the Context.

    Procedure Groups

    hash ¶
    Source

    Source Files

    Generation Information

    Generated with odin version dev-2024-12 (vendor "odin") Windows_amd64 @ 2024-12-17 21:11:00.938366200 +0000 UTC