package core:crypto/hash

⌘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 ¶

    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 ¶

    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 ¶

    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 ¶

    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 ¶

    ALGORITHM_NAMES: [Algorithm]string = …
     

    ALGORITHM_NAMES is the Algorithm to algorithm name string.

    BLOCK_SIZES ¶

    BLOCK_SIZES: [Algorithm]int = …
     

    BLOCK_SIZES is the Algoritm to block size in bytes.

    DIGEST_SIZES ¶

    DIGEST_SIZES: [Algorithm]int = …
     

    DIGEST_SIZES is the Algorithm to digest size in bytes.

    Procedures

    algorithm ¶

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

    algorithm returns the Algorithm used by a Context instance.

    block_size ¶

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

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

    clone ¶

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

    clone clones the Context other into ctx.

    digest_size ¶

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

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

    final ¶

    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 ¶

    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 ¶

    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 ¶

    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 ¶

    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 ¶

    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 ¶

    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 ¶

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

    init initializes a Context with a specific hash Algorithm.

    reset ¶

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

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

    update ¶

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

    update adds more data to the Context.

    Procedure Groups

    Source Files

    Generation Information

    Generated with odin version dev-2024-12 (vendor "odin") Windows_amd64 @ 2024-12-06 21:12:12.395896600 +0000 UTC