sodium.cr/src/sodium/kdf.cr

103 lines
3.3 KiB
Crystal
Raw Normal View History

require "./lib_sodium"
require "./secure_buffer"
require "./wipe"
module Sodium
2019-06-30 04:49:57 +02:00
# Key derivation function
#
# Usage:
# ```
# kdf = KDF.new
# subkey_id = 0
# output_size = 16
# subkey = kdf.derive "8bytectx", subkey_id, output_size
#
# Memory for this class is held in a sodium guarded page with noaccess.
# Readonly access is temporarily enabled when deriving keys.
# Calling #to_slice marks the page readonly permanently.
2019-06-30 04:49:57 +02:00
# ```
2019-05-28 23:31:31 +02:00
class Kdf
include Wipe
KEY_SIZE = LibSodium.crypto_kdf_keybytes.to_i
2019-06-30 04:49:57 +02:00
CONTEXT_SIZE = LibSodium.crypto_kdf_contextbytes
2019-08-07 01:45:20 +02:00
# Returns key
delegate to_slice, to: @sbuf
# Use an existing KDF key.
#
2019-07-09 09:42:56 +02:00
# * Copies key to a new SecureBuffer
# * Optionally erases bytes after copying if erase is set
def initialize(bytes : Bytes, erase = false)
2019-06-30 04:49:57 +02:00
if bytes.bytesize != KEY_SIZE
raise ArgumentError.new("bytes must be #{KEY_SIZE}, got #{bytes.bytesize}")
2019-05-28 23:31:31 +02:00
end
@sbuf = SecureBuffer.new(bytes, erase).noaccess
2019-05-28 23:31:31 +02:00
end
# Use an existing KDF SecureBuffer key.
def initialize(@sbuf : SecureBuffer)
if @sbuf.bytesize != KEY_SIZE
raise ArgumentError.new("bytes must be #{KEY_SIZE}, got #{sbuf.bytesize}")
end
@sbuf.noaccess
end
# Generate a new random KDF key.
#
# Make sure to save kdf.to_slice before kdf goes out of scope.
2019-05-28 23:31:31 +02:00
def initialize
@sbuf = SecureBuffer.random(KEY_SIZE).noaccess
2019-05-28 23:31:31 +02:00
end
# Derive a consistent subkey based on `context` and `subkey_id`.
#
# context and subkey don't need to be secret
# * context must be 8 bytes
# * subkey_size must be 16..64 bytes as of libsodium 1.0.17
#
# Returns a SecureBuffer. May transfer ownership to SecretBox or SecretKey without copying.
def derive(context, subkey_id, subkey_size) : SecureBuffer
2019-06-30 04:49:57 +02:00
context = context.to_slice
if context.bytesize != CONTEXT_SIZE
raise ArgumentError.new("context must be #{CONTEXT_SIZE}, got #{context.bytesize}")
2019-05-28 23:31:31 +02:00
end
subkey = SecureBuffer.new subkey_size
@sbuf.readonly do
if (ret = LibSodium.crypto_kdf_derive_from_key(subkey, subkey.bytesize, subkey_id, context, self.to_slice)) != 0
raise Sodium::Error.new("crypto_kdf_derive_from_key returned #{ret} (subkey size is probably out of range)")
end
2019-05-28 23:31:31 +02:00
end
2019-05-28 23:31:31 +02:00
subkey
end
# Convenience method to create a new CryptoBox::Secret without handling the key.
#
# See derive() for further information on context and subkey_id.
def derive_cryptobox(context, subkey_id) : CryptoBox::SecretKey
subkey = derive context, subkey_id, CryptoBox::SecretKey::SEED_SIZE
CryptoBox::SecretKey.new seed: subkey
end
# Convenience method to create a new Sign::Secret without handling the key.
#
# See derive() for further information on context and subkey_id.
def derive_sign(context, subkey_id) : Sign::SecretKey
subkey = derive context, subkey_id, Sign::SecretKey::SEED_SIZE
Sign::SecretKey.new seed: subkey
end
# Convenience method to create a new SecretBox without handling the key.
#
# See derive() for further information on context and subkey_id.
def derive_secretbox(context, subkey_id) : SecretBox
subkey = derive context, subkey_id, SecretBox::KEY_SIZE
SecretBox.new subkey
end
2019-05-28 23:31:31 +02:00
end
end