From c1172749b4c774dae379c289cd8f7f5d00982326 Mon Sep 17 00:00:00 2001 From: Rajon Ahmed Date: Fri, 28 Aug 2026 12:54:30 +0800 Subject: [PATCH] upd: essential/file updated helper hash updated --- essential/visible/service/helper/hash/hash.go | 396 ++++++++++++++++++ 1 file changed, 396 insertions(+) diff --git a/essential/visible/service/helper/hash/hash.go b/essential/visible/service/helper/hash/hash.go index e69de29..5b03aa5 100644 --- a/essential/visible/service/helper/hash/hash.go +++ b/essential/visible/service/helper/hash/hash.go @@ -0,0 +1,396 @@ +/* +|-------------------------------------------------------------------------- +| Description +|-------------------------------------------------------------------------- +| +| Name: +| - Hash +| +| Purpose: +| - Generate and verify cryptographic hash values using standard or +| salted hashing methods for integrity verification, canonical +| fingerprinting, resource identification, comparison workflows, +| and security-oriented hashing requirements. +| +|-------------------------------------------------------------------------- +*/ + +/* +|-------------------------------------------------------------------------- +| Instruction +|-------------------------------------------------------------------------- +| +| Guideline: +| - Use to generate deterministic hashes in standard mode. +| - Use to generate salted hashes when salted hashing is required. +| - Use to verify supplied hash values against input values. +| - Use standard mode when deterministic hashing without a salt is +| required. +| - Use salted mode when a supplied or cryptographically secure +| generated salt is required. +| +| Example: +| - ObrimHash("calculate", map[string]any{ +| "mode": "standard", +| "algorithm": "...", +| "value": "...", +| }) +| +| - ObrimHash("calculate", map[string]any{ +| "mode": "salted", +| "algorithm": "...", +| "value": "...", +| "salt": "...", +| }) +| +| - ObrimHash("compare", map[string]any{ +| "mode": "standard", +| "algorithm": "...", +| "value": "...", +| "hash": "...", +| }) +| +| - ObrimHash("compare", map[string]any{ +| "mode": "salted", +| "algorithm": "...", +| "value": "...", +| "hash": "...", +| "salt": "...", +| }) +| +|-------------------------------------------------------------------------- +*/ + +/* +|-------------------------------------------------------------------------- +| Credit +|-------------------------------------------------------------------------- +| +| Contributor: +| - Rajon Ahmed +| - Blockonite +| +|-------------------------------------------------------------------------- +*/ + +package hash + +import ( + "crypto/rand" + "crypto/sha256" + "crypto/sha512" + "encoding/hex" + "errors" + "hash" +) + +// Hash result codes. +const ( + ObrimHashSuccessCalculated = "SUCCESS_CALCULATED" + ObrimHashSuccessCompared = "SUCCESS_COMPARED" + ObrimHashFailureInvalidType = "FAILURE_INVALID_TYPE" + ObrimHashFailureInvalidConfig = "FAILURE_INVALID_CONFIG" + ObrimHashFailureInvalidMode = "FAILURE_INVALID_MODE" + ObrimHashFailureInvalidAlgorithm = "FAILURE_INVALID_ALGORITHM" + ObrimHashFailureInvalidValue = "FAILURE_INVALID_VALUE" + ObrimHashFailureInvalidHash = "FAILURE_INVALID_HASH" + ObrimHashFailureInvalidSalt = "FAILURE_INVALID_SALT" + ObrimHashFailureProcessing = "FAILURE_PROCESSING" +) + +// Hash utility modes. +const ( + obrimHashModeStandard = "standard" + obrimHashModeSalted = "salted" +) + +// Hash utility algorithms. +const ( + obrimHashAlgorithmSHA256 = "sha256" + obrimHashAlgorithmSHA512 = "sha512" +) + +// Hash utility configuration keys. +const ( + obrimHashConfigMode = "mode" + obrimHashConfigAlgorithm = "algorithm" + obrimHashConfigValue = "value" + obrimHashConfigHash = "hash" + obrimHashConfigSalt = "salt" +) + +// Hash utility operation types. +const ( + obrimHashTypeCalculate = "calculate" + obrimHashTypeCompare = "compare" +) + +// Hash utility output structure. +type obrimHashOutput struct { + Status bool `json:"status"` + Code string `json:"code"` + Payload map[string]any `json:"payload"` +} + +// Hash utility request configuration. +type obrimHashConfig struct { + Mode string + Algorithm string + Value string + Hash string + Salt string +} + +// Hash utility execution function. +func ObrimHash(Type string, Config map[string]any) map[string]any { + ConfigData, Code := obrimHashValidateInput(Type, Config) + if Code != "" { + return obrimHashBuildOutput(false, Code, nil) + } + + return obrimHashRouteRequest(Type, ConfigData) +} + +// Validate hash utility input. +func obrimHashValidateInput(Type string, Config map[string]any) (obrimHashConfig, string) { + var ConfigData obrimHashConfig + + switch Type { + case obrimHashTypeCalculate, obrimHashTypeCompare: + default: + return ConfigData, ObrimHashFailureInvalidType + } + + if Config == nil { + return ConfigData, ObrimHashFailureInvalidConfig + } + + ConfigData.Mode = obrimHashReadStringConfig(Config, obrimHashConfigMode) + ConfigData.Algorithm = obrimHashReadStringConfig(Config, obrimHashConfigAlgorithm) + ConfigData.Value = obrimHashReadStringConfig(Config, obrimHashConfigValue) + ConfigData.Hash = obrimHashReadStringConfig(Config, obrimHashConfigHash) + ConfigData.Salt = obrimHashReadStringConfig(Config, obrimHashConfigSalt) + + switch ConfigData.Mode { + case obrimHashModeStandard, obrimHashModeSalted: + default: + return ConfigData, ObrimHashFailureInvalidMode + } + + switch ConfigData.Algorithm { + case obrimHashAlgorithmSHA256, obrimHashAlgorithmSHA512: + default: + return ConfigData, ObrimHashFailureInvalidAlgorithm + } + + if ConfigData.Value == "" { + return ConfigData, ObrimHashFailureInvalidValue + } + + switch Type { + case obrimHashTypeCalculate: + if ConfigData.Mode == obrimHashModeStandard && ConfigData.Salt != "" { + return ConfigData, ObrimHashFailureInvalidSalt + } + case obrimHashTypeCompare: + if ConfigData.Hash == "" { + return ConfigData, ObrimHashFailureInvalidHash + } + + switch ConfigData.Mode { + case obrimHashModeStandard: + if ConfigData.Salt != "" { + return ConfigData, ObrimHashFailureInvalidSalt + } + case obrimHashModeSalted: + if ConfigData.Salt == "" { + return ConfigData, ObrimHashFailureInvalidSalt + } + } + } + + return ConfigData, "" +} + +// Route the hash utility request. +func obrimHashRouteRequest(Type string, Config obrimHashConfig) map[string]any { + switch Type { + case obrimHashTypeCalculate: + return obrimHashCalculate(Config) + case obrimHashTypeCompare: + return obrimHashCompare(Config) + default: + return obrimHashBuildOutput(false, ObrimHashFailureInvalidType, nil) + } +} + +// Build standardized hash utility output. +func obrimHashBuildOutput(Status bool, Code string, Payload map[string]any) map[string]any { + Output := obrimHashOutput{ + Status: Status, + Code: Code, + Payload: Payload, + } + + return map[string]any{ + "status": Output.Status, + "code": Output.Code, + "payload": Output.Payload, + } +} + +// Process hash generation. +func obrimHashCalculate(Config obrimHashConfig) map[string]any { + switch Config.Mode { + case obrimHashModeStandard: + return obrimHashCalculateStandard(Config) + case obrimHashModeSalted: + return obrimHashCalculateSalted(Config) + default: + return obrimHashBuildOutput(false, ObrimHashFailureInvalidMode, nil) + } +} + +// Generate deterministic standard hash. +func obrimHashCalculateStandard(Config obrimHashConfig) map[string]any { + HashValue, Error := obrimHashGenerate(Config.Algorithm, Config.Value) + if Error != nil { + return obrimHashBuildOutput(false, ObrimHashFailureProcessing, nil) + } + + Payload := map[string]any{ + "algorithm": Config.Algorithm, + "hash": HashValue, + } + + return obrimHashBuildOutput(true, ObrimHashSuccessCalculated, Payload) +} + +// Generate salted hash. +func obrimHashCalculateSalted(Config obrimHashConfig) map[string]any { + Salt := Config.Salt + + if Salt == "" { + var Error error + + Salt, Error = obrimHashGenerateSalt() + if Error != nil { + return obrimHashBuildOutput(false, ObrimHashFailureProcessing, nil) + } + } + + HashValue, Error := obrimHashGenerate(Config.Algorithm, Salt+Config.Value) + if Error != nil { + return obrimHashBuildOutput(false, ObrimHashFailureProcessing, nil) + } + + Payload := map[string]any{ + "algorithm": Config.Algorithm, + "hash": HashValue, + "salt": Salt, + } + + return obrimHashBuildOutput(true, ObrimHashSuccessCalculated, Payload) +} + +// Generate a cryptographically secure random salt. +func obrimHashGenerateSalt() (string, error) { + Salt := make([]byte, 32) + + if _, Error := rand.Read(Salt); Error != nil { + return "", Error + } + + return hex.EncodeToString(Salt), nil +} + +// Process hash verification. +func obrimHashCompare(Config obrimHashConfig) map[string]any { + switch Config.Mode { + case obrimHashModeStandard: + return obrimHashCompareStandard(Config) + case obrimHashModeSalted: + return obrimHashCompareSalted(Config) + default: + return obrimHashBuildOutput(false, ObrimHashFailureInvalidMode, nil) + } +} + +// Verify standard hash. +func obrimHashCompareStandard(Config obrimHashConfig) map[string]any { + HashValue, Error := obrimHashGenerate(Config.Algorithm, Config.Value) + if Error != nil { + return obrimHashBuildOutput(false, ObrimHashFailureProcessing, nil) + } + + Matched := obrimHashVerify(HashValue, Config.Hash) + + Payload := map[string]any{ + "algorithm": Config.Algorithm, + "matched": Matched, + "hash": Config.Hash, + } + + return obrimHashBuildOutput(true, ObrimHashSuccessCompared, Payload) +} + +// Verify salted hash. +func obrimHashCompareSalted(Config obrimHashConfig) map[string]any { + HashValue, Error := obrimHashGenerate(Config.Algorithm, Config.Salt+Config.Value) + if Error != nil { + return obrimHashBuildOutput(false, ObrimHashFailureProcessing, nil) + } + + Matched := obrimHashVerify(HashValue, Config.Hash) + + Payload := map[string]any{ + "algorithm": Config.Algorithm, + "matched": Matched, + "hash": Config.Hash, + "salt": Config.Salt, + } + + return obrimHashBuildOutput(true, ObrimHashSuccessCompared, Payload) +} + +// Verify regenerated and supplied hashes using strict byte comparison. +func obrimHashVerify(Expected string, Supplied string) bool { + return string([]byte(Expected)) == string([]byte(Supplied)) +} + +// Generate a hash using the selected algorithm. +func obrimHashGenerate(Algorithm string, Value string) (string, error) { + var HashFunction func() hash.Hash + + switch Algorithm { + case obrimHashAlgorithmSHA256: + HashFunction = sha256.New + case obrimHashAlgorithmSHA512: + HashFunction = sha512.New + default: + return "", errors.New("unsupported hashing algorithm") + } + + Hasher := HashFunction() + + if _, Error := Hasher.Write([]byte(Value)); Error != nil { + return "", Error + } + + return hex.EncodeToString(Hasher.Sum(nil)), nil +} + +// Read a string configuration value. +func obrimHashReadStringConfig(Config map[string]any, Key string) string { + Value, Exists := Config[Key] + if !Exists || Value == nil { + return "" + } + + StringValue, Valid := Value.(string) + if !Valid { + return "" + } + + return StringValue +}