Documentation
¶
Overview ¶
Package hash implements the hash functions identifiers (see Algorithm) and hash computation functions.
The result of a hash computation is returned in a form of an 'imprint' (see Imprint). An imprint represents a hash value and consists of a one-octet hash function identifier (see Algorithm) concatenated with the hash value itself.
In order to use a hash functions for cryptographic computation, the functions must be registered. Some functions are registered by default (see Registered()), others need to be registered prior to their use (see RegisterHash()).
Index ¶
- Constants
- func Equal(l, r Imprint) bool
- func RegisterHash(h Algorithm, f func() hash.Hash)
- type Algorithm
- func (a Algorithm) BlockSize() int
- func (a Algorithm) Defined() bool
- func (a Algorithm) DeprecatedFrom() (int64, error)
- func (a Algorithm) HashFunc() (hash.Hash, error)
- func (a Algorithm) New() (*DataHasher, error)
- func (a Algorithm) ObsoleteFrom() (int64, error)
- func (a Algorithm) Registered() bool
- func (a Algorithm) Size() int
- func (a Algorithm) StatusAt(at int64) FunctionStatus
- func (a Algorithm) String() string
- func (a Algorithm) Trusted() bool
- func (a Algorithm) ZeroImprint() Imprint
- type DataHasher
- type FunctionStatus
- type Imprint
Constants ¶
const ( // Unknown state. Unknown = FunctionStatus(iota) // Normal function can be used for all hashing purposes with no restrictions. Normal // Deprecated (since date) - the function has been deprecated since the given date due to the loss of collision resistance. Deprecated // Obsolete (since date) - the function is obsolete since the given date due to loss of 2nd pre-image resistance. Obsolete )
const Default = SHA2_256
Default is the recommended algorithm ID for hash computation.
Variables ¶
This section is empty.
Functions ¶
func Equal ¶
Equal returns true if, and only if, the two imprints are equal. The time taken is a function of the length of the slices and is independent of the contents.
func RegisterHash ¶
RegisterHash registers a function that returns a new instance of the given hash function. This is intended to be called from the init function in packages that implement hash functions.
Types ¶
type Algorithm ¶
type Algorithm int
Algorithm is the hash functions identifier.
const ( // SHA1 is SHA-1 algorithm. Deprecated as of 01.07.2016. SHA1 Algorithm = 0x00 // SHA2_256 is SHA-256 algorithm. SHA2_256 Algorithm = 0x01 // RIPEMD160 is RIPEMD-160 algorithm. // In order to use the algorithm for hash computation, "golang.org/x/crypto/ripemd160" needs to be imported indirectly. RIPEMD160 Algorithm = 0x02 // SHA2_384 is SHA-384 algorithm. SHA2_384 Algorithm = 0x04 // SHA2_512 is SHA-512 algorithm. SHA2_512 Algorithm = 0x05 // SHA3_224 is SHA3-244 algorithm. // In order to use SHA3 hash algorithm, the "golang.org/x/crypto/sha3" package needs to be imported indirectly and // the algorithm registered (see RegisterHash()). SHA3_224 Algorithm = 0x07 // SHA3_256 is SHA3-256 algorithm. // In order to use SHA3 hash algorithm, the "golang.org/x/crypto/sha3" package needs to be imported indirectly and // the algorithm registered (see RegisterHash()). SHA3_256 Algorithm = 0x08 // SHA3_384 is SHA3-384 algorithm. // In order to use SHA3 hash algorithm, the "golang.org/x/crypto/sha3" package needs to be imported indirectly and // the algorithm registered (see RegisterHash()). SHA3_384 Algorithm = 0x09 // SHA3_512 is SHA3-512 algorithm. // In order to use SHA3 hash algorithm, the "golang.org/x/crypto/sha3" package needs to be imported indirectly and // the algorithm registered (see RegisterHash()). SHA3_512 Algorithm = 0x0a // SM3 algorithm. // In order to use SM3 hash algorithm, the implementation needs to be registered (see RegisterHash()). SM3 Algorithm = 0x0b // SHA_NA defines an invalid algorithm. SHA_NA Algorithm = 0x100 )
func ByName ¶
ByName returns the hash function specified by the case insensitive string parameter name.
To verify the correctness of the returned value, (Algorithm).Defined() or (Algorithm).Trusted() function must be used. The valid inputs are:
- "default" for the configured default hash algorithm or one of the following:
- "sha-1", "sha1",
- "sha-256", "sha2-256", "sha-2", "sha2", "sha256",
- "ripemd-160", "ripemd160",
- "sha-384", "sha384", "sha2-384",
- "sha-512", "sha512", "sha2-512",
- "sha3-224", "sha3-256", "sha3-384", "sha3-512",
- "sm-3", "sm3".
The SHA-2 family names do not require the infix "2" as opposed to the SHA-3 family where the infix "3" is mandatory. This means "sha-256" is unambiguously the 256-bit version of SHA-2.
Returns hash function, or KsiUnknownHashAlgorithm error in case of unrecognized name.
func ListDefined ¶
func ListDefined() []Algorithm
ListDefined returns a slice of available hash functions.
func ListSupported ¶
func ListSupported() []Algorithm
ListSupported returns a slice of supported hash functions.
func (Algorithm) BlockSize ¶
BlockSize returns the size of the data block the underlying hash algorithm operates upon in bytes. In case of an error, a negative value is returned.
func (Algorithm) Defined ¶
Defined reports whether the given hash function is defined by the library.
func (Algorithm) DeprecatedFrom ¶
DeprecatedFrom reports time the hash function has been marked as deprecated. Returns hash algorithm deprecate time as a Unix time, the number of seconds elapsed since January 1, 1970 UTC (1970-01-01T00:00:00Z), or 0 if not set. Returns an error if unknown.
func (Algorithm) New ¶
func (a Algorithm) New() (*DataHasher, error)
New returns new hasher for the given hash algo. Returns error if the hash function is not linked into the binary.
func (Algorithm) ObsoleteFrom ¶
ObsoleteFrom reports time the hash function has been marked as obsolete. Returns hash algorithm obsolete time as a Unix time, the number of seconds elapsed since January 1, 1970 UTC (1970-01-01T00:00:00Z), or 0 if not set. Returns an error if unknown.
func (Algorithm) Registered ¶
Registered checks whether the given hash algorithm is supported, meaning the hash value can be calculated using the API.
func (Algorithm) Size ¶
Size returns the resulting digest length in bytes. In case of an error, a negative value is returned.
func (Algorithm) StatusAt ¶
func (a Algorithm) StatusAt(at int64) FunctionStatus
StatusAt checks the status of the hash function at a given time. Returns Deprecated if the hash algorithm was deprecated at the given time; Obsolete if the hash algorithm was obsolete at the given time; or an error.
func (Algorithm) String ¶
String returns a string representation of the given hash algorithm. Returns empty string in case of unknown algorithm.
func (Algorithm) Trusted ¶
Trusted is used to check if the given hash algorithm is trusted. If the algorithm has been marked as deprecated or obsolete, it will return false (otherwise true is returned). It is not checked if the deprecated and/or obsolete dates have passed but operation is impossible as soon as one of the dates is set. The intention is to make the change apparent right after upgrading the library rather than wait and possibly break normal operations in an apparently arbitrary moment.
func (Algorithm) ZeroImprint ¶
ZeroImprint returns a zero imprint for the given algorithm.
type DataHasher ¶
type DataHasher struct {
// contains filtered or unexported fields
}
DataHasher is the data hash computation object.
func (*DataHasher) BlockSize ¶
func (h *DataHasher) BlockSize() int
BlockSize returns the hash's underlying block size. The Write method must be able to accept any amount of data, but it may operate more efficiently if all writes are a multiple of the block size. In case of an error, a negative value is returned.
func (*DataHasher) Imprint ¶
func (h *DataHasher) Imprint() (Imprint, error)
Imprint returns KSI imprint for the current computation. It does not change the underlying hash state.
func (*DataHasher) Reset ¶
func (h *DataHasher) Reset()
Reset resets the hasher to its initial state.
func (*DataHasher) Size ¶
func (h *DataHasher) Size() int
Size returns the resulting digest length in bytes for the given hash function. In case of an error, a negative value is returned.
type FunctionStatus ¶
type FunctionStatus byte
FunctionStatus describes the hash function state at a certain time.
Algorithm functions are being deprecated for which it has become evident that collisions have been found and are affordable. A deprecation date D (based on when the collisions become affordable) will be assigned to the deprecated function. In case the time of the signature can be trusted (e.g. it is extended to a publication before D, or does not have the deprecated hash function in its calendar chain), the signature remains valid as long as its time is before D.
Similarly, when 2nd pre-image resistance is broken, the function is marked as obsolete since date F. When the 2nd pre-image resistance is broken, verification of the signature will always fail by default if such function is used somewhere in the signature.
type Imprint ¶
type Imprint []byte
Imprint represents a hash value and consists of a one-octet hash function identifier concatenated with the hash value itself.
func CryptoHashToImprint ¶
CryptoHashToImprint wraps the digest into Imprint. In case the digest parameter is nil, a zero imprint is returned.
Note that the status of the hash algorithm is not verified. See (Algorithm).StatusAt().
Possible return errors:
- KsiUnknownHashAlgorithm error in case the provided cryptoId is not defined by KSI;
- KsiInvalidFormatError error in case the length of the provided digest mismatch.
func (Imprint) Algorithm ¶
Algorithm returns the hash functions used to generate digest. Returns SHA_NA in case the imprint is not valid (see (Imprint).IsValid()).
func (Imprint) Digest ¶
Digest returns the binary hash value. Returns nil in case the imprint is not valid (see (Imprint).IsValid()).
Source Files