path: root/server/resty/openssl/kdf.lua

local ffi = require "ffi"
local C = ffi.C
local ffi_gc = ffi.gc
local ffi_str = ffi.string

require("resty.openssl.objects")
require("resty.openssl.include.evp.md")
-- used by legacy EVP_PKEY_derive interface
require("resty.openssl.include.evp.pkey")
local kdf_macro = require "resty.openssl.include.evp.kdf"
local ctx_lib = require "resty.openssl.ctx"
local format_error = require("resty.openssl.err").format_error
local version_num = require("resty.openssl.version").version_num
local version_text = require("resty.openssl.version").version_text
local BORINGSSL = require("resty.openssl.version").BORINGSSL
local OPENSSL_3X = require("resty.openssl.version").OPENSSL_3X
local ctypes = require "resty.openssl.auxiliary.ctypes"

--[[
https://wiki.openssl.org/index.php/EVP_Key_Derivation

OpenSSL 1.0.2 and above provides PBKDF2 by way of PKCS5_PBKDF2_HMAC and PKCS5_PBKDF2_HMAC_SHA1.
OpenSSL 1.1.0 and above additionally provides HKDF and TLS1 PRF KDF by way of EVP_PKEY_derive and Scrypt by way of EVP_PBE_scrypt
OpenSSL 1.1.1 and above additionally provides Scrypt by way of EVP_PKEY_derive.
OpenSSL 3.0 additionally provides Single Step KDF, SSH KDF, PBKDF2, Scrypt, HKDF, ANSI X9.42 KDF, ANSI X9.63 KDF and TLS1 PRF KDF by way of EVP_KDF.
From OpenSSL 3.0 the recommended way of performing key derivation is to use the EVP_KDF functions. If compatibility with OpenSSL 1.1.1 is required then a limited set of KDFs can be used via EVP_PKEY_derive.
]]

local NID_id_pbkdf2 = -1
local NID_id_scrypt = -2
local NID_tls1_prf = -3
local NID_hkdf = -4
if version_num >= 0x10002000 then
  NID_id_pbkdf2 = C.OBJ_txt2nid("PBKDF2")
  assert(NID_id_pbkdf2 > 0)
end
if version_num >= 0x10100000 and not BORINGSSL then
  NID_hkdf = C.OBJ_txt2nid("HKDF")
  assert(NID_hkdf > 0)
  NID_tls1_prf = C.OBJ_txt2nid("TLS1-PRF")
  assert(NID_tls1_prf > 0)
  -- we use EVP_PBE_scrypt to do scrypt, so this is supported >= 1.1.0
  NID_id_scrypt = C.OBJ_txt2nid("id-scrypt")
  assert(NID_id_scrypt > 0)
end

local _M = {
  HKDEF_MODE_EXTRACT_AND_EXPAND = kdf_macro.EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND,
  HKDEF_MODE_EXTRACT_ONLY       = kdf_macro.EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY,
  HKDEF_MODE_EXPAND_ONLY        = kdf_macro.EVP_PKEY_HKDEF_MODE_EXPAND_ONLY,

  PBKDF2   = NID_id_pbkdf2,
  SCRYPT   = NID_id_scrypt,
  TLS1_PRF = NID_tls1_prf,
  HKDF     = NID_hkdf,
}

local type_literals = {
  [NID_id_pbkdf2] = "PBKDF2",
  [NID_id_scrypt] = "scrypt",
  [NID_tls1_prf]  = "TLS-1PRF",
  [NID_hkdf]      = "HKDF",
}

local TYPE_NUMBER = 0x1
local TYPE_STRING = 0x2

local function check_options(opt, nid, field, typ, is_optional, required_only_if_nid)
  local v = opt[field]
  if not v then
    if is_optional or (required_only_if_nid and required_only_if_nid ~= nid) then
      return typ == TYPE_NUMBER and 0 or nil
    else
      return nil, "\"" .. field .. "\" must be set"
    end
  end

  if typ == TYPE_NUMBER then
    v = tonumber(v)
    if not typ then
      return nil, "except a number as \"" .. field .. "\""
    end
  elseif typ == TYPE_STRING then
    if type(v) ~= "string" then
      return nil, "except a string as \"" .. field .. "\""
    end
  else
    error("don't known how to check " .. typ, 2)
  end

  return v
end

local function check_hkdf_options(opt)
  local mode = opt.hkdf_mode
  if not mode or version_num < 0x10101000 then
    mode = _M.HKDEF_MODE_EXTRACT_AND_EXPAND
  end

  if mode == _M.HKDEF_MODE_EXTRACT_AND_EXPAND and (
    not opt.salt or not opt.hkdf_info) then
    return '""salt" and "hkdf_info" are required for EXTRACT_AND_EXPAND mode'
  elseif mode == _M.HKDEF_MODE_EXTRACT_ONLY and not opt.salt then
    return '"salt" is required for EXTRACT_ONLY mode'
  elseif mode == _M.EVP_PKEY_HKDEF_MODE_EXPAND_ONLY and not opt.hkdf_info then
    return '"hkdf_info" is required for EXPAND_ONLY mode'
  end

  return nil
end

local options_schema = {
  outlen = { TYPE_NUMBER },
  pass   = { TYPE_STRING, true },
  salt   = { TYPE_STRING, true },
  md     = { TYPE_STRING, true },
  -- pbkdf2 only
  pbkdf2_iter = { TYPE_NUMBER, true },
  -- hkdf only
  hkdf_key  = { TYPE_STRING, nil, NID_hkdf },
  hkdf_mode = { TYPE_NUMBER, true },
  hkdf_info = { TYPE_STRING, true },
  -- tls1-prf
  tls1_prf_secret = { TYPE_STRING, nil, NID_tls1_prf },
  tls1_prf_seed   = { TYPE_STRING, nil, NID_tls1_prf },
  -- scrypt only
  scrypt_maxmem = { TYPE_NUMBER, true },
  scrypt_N      = { TYPE_NUMBER, nil, NID_id_scrypt },
  scrypt_r      = { TYPE_NUMBER, nil, NID_id_scrypt },
  scrypt_p      = { TYPE_NUMBER, nil, NID_id_scrypt },
}

local outlen = ctypes.ptr_of_uint64()

function _M.derive(options)
  local typ = options.type
  if not typ then
    return nil, "kdf.derive: \"type\" must be set"
  elseif type(typ) ~= "number" then
    return nil, "kdf.derive: expect a number as \"type\""
  end

  if typ <= 0 then
    return nil, "kdf.derive: kdf type " ..  (type_literals[typ] or tostring(typ)) ..
                " not supported in " .. version_text
  end

  for k, v in pairs(options_schema) do
    local v, err = check_options(options, typ, k, unpack(v))
    if err then
      return nil, "kdf.derive: " .. err
    end
    options[k] = v
  end

  if typ == NID_hkdf then
    local err = check_hkdf_options(options)
    if err then
      return nil, "kdf.derive: " .. err
    end
  end

  local salt_len = 0
  if options.salt then
    salt_len = #options.salt
  end
  local pass_len = 0
  if options.pass then
    pass_len = #options.pass
  end

  local md
  if OPENSSL_3X then
    md = C.EVP_MD_fetch(ctx_lib.get_libctx(), options.md or 'sha1', options.properties)
  else
    md = C.EVP_get_digestbyname(options.md or 'sha1')
  end
  if md == nil then
    return nil, string.format("kdf.derive: invalid digest type \"%s\"", md)
  end

  local buf = ctypes.uchar_array(options.outlen)

  -- begin legacay low level routines
  local code
  if typ == NID_id_pbkdf2 then
    -- make openssl 1.0.2 happy
    if version_num < 0x10100000 and not options.pass then
      options.pass = ""
      pass_len = 0
    end
    -- https://www.openssl.org/docs/man1.1.0/man3/PKCS5_PBKDF2_HMAC.html
    local iter = options.pbkdf2_iter
    if iter < 1 then
      iter = 1
    end
    code = C.PKCS5_PBKDF2_HMAC(
      options.pass, pass_len,
      options.salt, salt_len, iter,
      md, options.outlen, buf
    )
  elseif typ == NID_id_scrypt then
    code = C.EVP_PBE_scrypt(
      options.pass, pass_len,
      options.salt, salt_len,
      options.scrypt_N, options.scrypt_r, options.scrypt_p, options.scrypt_maxmem,
      buf, options.outlen
    )
  elseif typ ~= NID_tls1_prf and typ ~= NID_hkdf then
    return nil, string.format("kdf.derive: unknown type %d", typ)
  end
  if code then
    if code ~= 1 then
      return nil, format_error("kdf.derive")
    else
      return ffi_str(buf, options.outlen)
    end
  end
  -- end legacay low level routines

  -- begin EVP_PKEY_derive routines
  outlen[0] = options.outlen

  local ctx = C.EVP_PKEY_CTX_new_id(typ, nil)
  if ctx == nil then
    return nil, format_error("kdf.derive: EVP_PKEY_CTX_new_id")
  end
  ffi_gc(ctx, C.EVP_PKEY_CTX_free)
  if C.EVP_PKEY_derive_init(ctx) ~= 1 then
    return nil, format_error("kdf.derive: EVP_PKEY_derive_init")
  end

  if typ == NID_tls1_prf then
    if kdf_macro.EVP_PKEY_CTX_set_tls1_prf_md(ctx, md) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_set_tls1_prf_md")
    end
    if kdf_macro.EVP_PKEY_CTX_set1_tls1_prf_secret(ctx, options.tls1_prf_secret) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_set1_tls1_prf_secret")
    end
    if kdf_macro.EVP_PKEY_CTX_add1_tls1_prf_seed(ctx, options.tls1_prf_seed) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_add1_tls1_prf_seed")
    end
  elseif typ == NID_hkdf then
    if kdf_macro.EVP_PKEY_CTX_set_hkdf_md(ctx, md) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_set_hkdf_md")
    end
    if options.salt and
      kdf_macro.EVP_PKEY_CTX_set1_hkdf_salt(ctx, options.salt) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_set1_hkdf_salt")
    end
    if options.hkdf_key and
      kdf_macro.EVP_PKEY_CTX_set1_hkdf_key(ctx, options.hkdf_key) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_set1_hkdf_key")
    end
    if options.hkdf_info and
      kdf_macro.EVP_PKEY_CTX_add1_hkdf_info(ctx, options.hkdf_info) ~= 1 then
      return nil, format_error("kdf.derive: EVP_PKEY_CTX_add1_hkdf_info")
    end
    if options.hkdf_mode then
      if version_num >= 0x10101000 then
        if kdf_macro.EVP_PKEY_CTX_set_hkdf_mode(ctx, options.hkdf_mode) ~= 1 then
          return nil, format_error("kdf.derive: EVP_PKEY_CTX_set_hkdf_mode")
        end
        if options.hkdf_mode == _M.HKDEF_MODE_EXTRACT_ONLY then
          local md_size = OPENSSL_3X and C.EVP_MD_get_size(md) or C.EVP_MD_size(md)
          if options.outlen ~= md_size then
            options.outlen = md_size
            ngx.log(ngx.WARN, "hkdf_mode EXTRACT_ONLY outputs fixed length of ", md_size,
                    " key, ignoring options.outlen")
          end
          outlen[0] = md_size
          buf = ctypes.uchar_array(md_size)
        end
      else
        ngx.log(ngx.WARN, "hkdf_mode is not effective in ", version_text)
      end
    end
  else
    return nil, string.format("kdf.derive: unknown type %d", typ)
  end
  code = C.EVP_PKEY_derive(ctx, buf, outlen)
  if code == -2 then
    return nil, "kdf.derive: operation is not supported by the public key algorithm"
  end
  -- end EVP_PKEY_derive routines

  return ffi_str(buf, options.outlen)
end

if not OPENSSL_3X then
  return _M
end

_M.derive_legacy = _M.derive
_M.derive = nil

-- OPENSSL 3.0 style API
local param_lib = require "resty.openssl.param"
local SIZE_MAX = ctypes.SIZE_MAX

local mt = {__index = _M}

local kdf_ctx_ptr_ct = ffi.typeof('EVP_KDF_CTX*')

function _M.new(typ, properties)
  local algo = C.EVP_KDF_fetch(ctx_lib.get_libctx(), typ, properties)
  if algo == nil then
    return nil, format_error(string.format("mac.new: invalid mac type \"%s\"", typ))
  end

  local ctx = C.EVP_KDF_CTX_new(algo)
  if ctx == nil then
    return nil, "mac.new: failed to create EVP_MAC_CTX"
  end
  ffi_gc(ctx, C.EVP_KDF_CTX_free)

  local buf
  local buf_size = tonumber(C.EVP_KDF_CTX_get_kdf_size(ctx))
  if buf_size == SIZE_MAX then -- no fixed size
    buf_size = nil
  else
    buf = ctypes.uchar_array(buf_size)
  end

  return setmetatable({
    ctx = ctx,
    algo = algo,
    buf = buf,
    buf_size = buf_size,
  }, mt), nil
end

function _M.istype(l)
  return l and l.ctx and ffi.istype(kdf_ctx_ptr_ct, l.ctx)
end

function _M:get_provider_name()
  local p = C.EVP_KDF_get0_provider(self.algo)
  if p == nil then
    return nil
  end
  return ffi_str(C.OSSL_PROVIDER_get0_name(p))
end

_M.settable_params, _M.set_params, _M.gettable_params, _M.get_param = param_lib.get_params_func("EVP_KDF_CTX")

function _M:derive(outlen, options, options_count)
  if not _M.istype(self) then
    return _M.derive_legacy(self)
  end

  if self.buf_size and outlen then
    return nil, string.format("kdf:derive: this KDF has fixed output size %d, ".. 
                              "it can't be set manually", self.buf_size)
  end

  outlen = self.buf_size or outlen
  local buf = self.buf or ctypes.uchar_array(outlen)

  if options_count then
    options_count = options_count - 1
  else
    options_count = 0
    for k, v in pairs(options) do options_count = options_count + 1 end
  end

  local param, err
  if options_count > 0 then
    local schema = self:settable_params(true) -- raw schema
    param, err = param_lib.construct(options, nil, schema)
    if err then
      return nil, "kdf:derive: " .. err
    end
  end

  if C.EVP_KDF_derive(self.ctx, buf, outlen, param) ~= 1 then
    return nil, format_error("kdf:derive")
  end

  return ffi_str(buf, outlen)
end

function _M:reset()
  C.EVP_KDF_CTX_reset(self.ctx)
  return true
end

return _M