You can calculate SHA-256 or SHA-512 hashes and format hash bytes as text from OCL in Turnkey by declaring the supported external methods on SysSingleton.

What these methods do

Turnkey supports the following predefined methods on SysSingleton. They accept and return Blob values, where a Blob is the byte-array value used for binary data.

Method	Signature	Result
SHA512ComputeHash	SHA512ComputeHash(bytes:Blob):Blob	Calculates a SHA-512 checksum for the supplied bytes and returns the checksum bytes as a Blob.
SHA256ComputeHash	SHA256ComputeHash(bytes:Blob):Blob	Calculates a SHA-256 checksum for the supplied bytes and returns the checksum bytes as a Blob.
BitConverterToString	BitConverterToString(bytes:Blob):String	Formats bytes as a hyphen-separated string. For example, bytes with values 01, A0, and FF become 01-A0-FF.

Use BitConverterToString after either hash method when an external service expects the hash as text rather than as binary data.

Add the methods to SysSingleton

Declare the methods on your model's SysSingleton class so that Turnkey can provide their implementations.

1. Add these method declarations to SysSingleton:
   • SHA512ComputeHash(bytes:Blob):Blob
   • SHA256ComputeHash(bytes:Blob):Blob
   • BitConverterToString(bytes:Blob):String
2. Mark each method with the tagged value Eco.ExternalLateBound. The value of the tag can be any value; Turnkey checks for the tag's presence.
3. Make the methods queries when you need to call them from OCL.
4. Call the method through SysSingleton.oclSingleton.

These are ExternalLateBound methods: Turnkey supplies them at runtime. They are available at the Turnkey level, not at the MDrivenServer level. If code executing on MDrivenServer needs a hash, do not assume these Turnkey-provided methods are available there.

Hash text in OCL

The hash methods require a Blob, not a String. Convert the text to bytes first, calculate the hash, then format the returned hash Blob.

The following example creates a SHA-512 hash for a request body, merchant secret, and timestamp. It removes the hyphens from the formatted hash because the receiving value in this example requires a continuous hexadecimal string.

let orgdata=requestbody+SveaSettingsSingleton.oclSingleton.MerchantSecret+timestamp in
(
  let thehash=SysSingleton.oclSingleton.SHA512ComputeHash(orgdata.StringToBase64.Base64ToBlob) in
  (
    (SveaSettingsSingleton.oclSingleton.MerchantId+':'+SysSingleton.oclSingleton.BitConverterToString(thehash).Replace('-','')).StringToBase64
  )
)

The key steps in this example are:

1. orgdata.StringToBase64.Base64ToBlob produces the Blob passed to SHA512ComputeHash.
2. SHA512ComputeHash(...) returns the checksum as a Blob.
3. BitConverterToString(thehash) produces text such as 01-A0-FF.
4. Replace('-',) changes that representation to 01A0FF when required by the target protocol.

For a SHA-256 value, use the same pattern and replace the hash call:

let hashBytes=SysSingleton.oclSingleton.SHA256ComputeHash(value.StringToBase64.Base64ToBlob) in
SysSingleton.oclSingleton.BitConverterToString(hashBytes)

Choose the byte representation deliberately

A hash is calculated from bytes. The same visible text can produce different hash values if it is converted to bytes using different encodings. Establish the required encoding with the system you integrate with before calculating the hash.

Use Convert String to Bytes for the OCL conversion pattern used above. For other conversions between strings and byte arrays, see Documentation:Encoding.

Do not use these methods for Turnkey password storage

SHA256ComputeHash and SHA512ComputeHash are general byte-hash helpers. For Turnkey user passwords, use the dedicated SysUser.HashPassword and SysUser.VerifyHashedPassword methods described in HowTos:Hash and Validate Passwords.

Related Turnkey methods

SysSingleton also exposes other supported ExternalLateBound methods, including GetSystemUrl. Refer to Documentation:Pattern supported methods for the maintained list of methods with server support.

See also

• HowTos:Convert String to Bytes
• Documentation:Encoding
• HowTos:Hash and Validate Passwords
• Documentation:SysSingleton GetSystemUrl
• Documentation:Pattern supported methods