secret/core
an owned, page-locked, linearly-typed secret buffer.
Since: 0.1.0
Secret
(Secret)
an owned, locked, linear buffer of key material.
Since: 0.1.0
secret-random!
(secret-random! [n : int])
mint an n-byte secret from the OS CSPRNG.
| n | byte length; must be positive |
(Result Secret cstr) -- ok carries a live, locked Secret the caller must eventually consume with secret-wipe!; err carries a static description. A secret that could not be filled is released here rather than handed back, so the error path leaks neither memory nor a locked page and never yields a zero-filled "key".
(let [r (secret-random! 32)]
(if (ok? r)
(let [k (ok-val r)] (do (use k) (secret-wipe! k)))
0))
Since: 0.1.0
secret-of-bytes
(secret-of-bytes [p ptr<void> n : int] :)
copy `n` bytes into a fresh secret, wiping the source.
| p | source bytes; wiped in place before this returns | |
| n | byte count; must be positive |
(Result Secret cstr) -- ok carries a live, locked Secret.
(let [r (secret-of-bytes raw 32)] ; raw is zeroed on return
(if (ok? r) (ok-val r) ...))
Since: 0.1.0
secret-wipe!
(secret-wipe! [s : Secret] :)
zero, unlock, and free a secret. THE destructor.
| s | the secret to destroy |
Nothing.
(secret-wipe! k)
Since: 0.1.0
with-secret
(with-secret [^borrow s : Secret f : (fn [ptr<void> int])
run `f` over the secret's bytes for the duration of the call.
| s | the secret, borrowed for the duration of the call | |
| f | receives (bytes, length) and returns an int |
Whatever `f` returned.
(with-secret k hash-into)
Since: 0.1.0
secret-len
(secret-len [^borrow s : Secret] :)
the secret's payload length in bytes.
| s | the secret, borrowed |
The byte length passed at construction.
(secret-len k) ; => 32
Since: 0.1.0
secret-locked?
(secret-locked? [^borrow s : Secret] :)
did the backing pages actually get locked into RAM?
| s | the secret, borrowed |
true when mlock/VirtualLock succeeded at construction.
(if (secret-locked? k) 0 (warn "key may reach swap"))
Since: 0.1.0
secret-eq?
(secret-eq? [^borrow a : Secret ^borrow b : Secret] :)
constant-time equality of two secrets' contents.
| a | first secret, borrowed | |
| b | second secret, borrowed |
true when both hold the same bytes.
(if (secret-eq? computed supplied) (accept) (reject))
Since: 0.1.0
Internal definitions
secret-alloc-raw-- allocate and lock an n-byte secret; 0 on failure.secret-free-raw!-- wipe, unlock, and free a raw handle fromsecret-fill-random-raw!-- fill a raw handle's payload from the CSPRNG.secret-copy-in-raw!-- copy n bytes into a raw handle, wiping the source.secret-of-raw-- reinterpret a raw handle as the opaque Secret.secret-data-raw-- raw pointer to the payload bytes.