Cryptography and secrets
Safe algorithms and parameters are the runtime's job. You say what you want - encrypt, hash a password, generate random bytes - not which cipher to use.
Availability: included in the current release candidate (1.0.0). Whether it is part of the supported Otter 1.0 surface has not been decided yet, so details may change.
Bytes
Everything here works on bytes, Otter's binary type. Text and bytes are never converted silently; ask for the conversion you mean:
Otter
data is bytes from text "Hello"
say hex from bytes data
say base64 from bytes data
say text from bytes data
say length of data
Hashing and signing
Otter
data is bytes from text "abc"
digest is sha256 of data
say hex from bytes digest
key is bytes from text "shared secret"
signature is hmac sha256 of data using key
say hex from bytes signature
sha256, sha384 and sha512 are available, and the same three for hmac. Obsolete hashes such as MD5 and SHA-1 are deliberately left out.
Secure random bytes
Otter
token is secure random bytes 32
say hex from bytes token
This uses the operating system's cryptographically secure source, unlike Otter's general random numbers.
Encryption
Encryption is authenticated: tampered or wrongly-keyed data is refused, never returned as garbage. The nonce is handled for you and stored inside the result.
Otter
generate encryption key and call it key
message is bytes from text "Attack at dawn"
encrypt message using key and call it encrypted
decrypt encrypted using key and call it original
say text from bytes original
Output
Attack at dawn
Store or send the result with base64 from bytes encrypted, and restore it with bytes from base64 encoded.
Passwords
Passwords are not hashed like other data. hash password uses a slow, salted algorithm chosen by the runtime and gives you text you can store safely:
Otter
password is "correct horse battery staple"
hash password password and call it storedHash
if password password matches hash storedHash
say "Correct"
.
Comparing secrets
securely equals compares bytes in constant time, so timing does not leak how much of a secret matched:
Otter
if expected securely equals actual
say "Valid"
.
The credential vault
Store secrets such as API tokens in the operating system's credential store instead of a file. Secrets are scoped to your program: two different Otter programs storing "api-token" never see each other's value. The vault uses Windows Credential Manager, so it works on Windows only; on macOS and Linux it stops with a clear message.
Otter
if secret "api-token" exists
token is secret "api-token"
otherwise
ask secretly "API token:" and call it token
store secret "api-token" with value token
.
delete secret "api-token"
A secret holds text or bytes and comes back as the same kind. Reading a secret that does not exist is an error, never an empty string. On Windows the vault is the Windows Credential Manager.
Cryptography also works in web applications, through the browser's Web Crypto API, with results that match the console. The credential vault does not: browser storage is not a secure credential store, so the web target reports it as unsupported.
Back to the reference