暗号化 & 署名

cryptoモジュールは、ランダム値の生成、HMACの計算、データの暗号化と復号、JWTのエンコードと検証、鍵の導出を行います。決定論的ワークフローでは、ランダム生成と暗号化（ランダムなnonceを生成します）は記録される副作用として実行され、リプレイでは記録済みのバイト列が返されます。HMAC、復号、JWT処理、PBKDF2、比較を含むその他の操作は直接実行されます。

このページはAPIリファレンスです。各コードブロックは独立した呼び出しであり、完全な鍵管理システムや認証システムではありません。data、key、aad、payload、tokenなどの名前は、アプリケーションから渡される値です。鍵とパスワードはアプリケーションのシークレット管理境界を通じて読み込み、ハードコード、ログ出力、診断結果への返却をしないでください。ここに示すvalue, error形式の結果は、値を使用する前にエラーを伝播または処理してください。

ロード

local crypto = require("crypto")

乱数生成

ランダムバイト

local bytes, err = crypto.random.bytes(32)

戻り値: string, error

ランダム文字列

local str, err = crypto.random.string(32)
local str, err = crypto.random.string(32, "0123456789abcdef")

戻り値: string, error

実装は、指定されたアルファベットからバイト単位で選択します。非ASCIIのアルファベットは不正なUTF-8に分割される可能性があり、剰余による選択が完全に一様になるのはアルファベットのバイト長が256を割り切る場合だけです。一様なランダム性を持つ秘密データにはcrypto.random.bytesを使用し、必要な転送形式に合わせて結果をエンコードしてください。

ランダムUUID

local id, err = crypto.random.uuid()

戻り値: string, error

HMAC

HMAC-SHA256

local hex, err = crypto.hmac.sha256(key, data)

戻り値: string, error

HMAC-SHA512

local hex, err = crypto.hmac.sha512(key, data)

戻り値: string, error

暗号化

AES-GCM {id="encrypt-aes-gcm"}

local encrypted, err = crypto.encrypt.aes(data, key)
local encrypted, err = crypto.encrypt.aes(data, key, aad)

戻り値: string, error（nonceが前置）

どちらの暗号化関数もnonceを生成して暗号文の先頭に付加します。nonceを削除または再利用せず、復号時には同じAADを使用してください。暗号文は、秘密情報を含まないログ値ではありません。長さや相関に関する情報を漏らす可能性があります。

ChaCha20-Poly1305 {id="encrypt-chacha20"}

local encrypted, err = crypto.encrypt.chacha20(data, key)
local encrypted, err = crypto.encrypt.chacha20(data, key, aad)

戻り値: string, error（nonceが前置）

復号

AES-GCM {id="decrypt-aes-gcm"}

local plaintext, err = crypto.decrypt.aes(encrypted, key)
local plaintext, err = crypto.decrypt.aes(encrypted, key, aad)

戻り値: string, error

ChaCha20-Poly1305 {id="decrypt-chacha20"}

local plaintext, err = crypto.decrypt.chacha20(encrypted, key)
local plaintext, err = crypto.decrypt.chacha20(encrypted, key, aad)

戻り値: string, error

JWT

エンコード

local token, err = crypto.jwt.encode(payload, secret)
local token, err = crypto.jwt.encode(payload, secret, "HS256")
local token, err = crypto.jwt.encode(payload, private_key_pem, "RS256")

戻り値: string, error

文書化されているアルゴリズム名のいずれか一つだけを渡してください。このランタイムの固定バージョンでは、未対応の値をencodeに渡すとエラーではなくHS256へフォールバックします。設定可能なアルゴリズムは呼び出し前に検証し、信頼できないフィールドを_headerへコピーしないでください。特に、入力からalgなどの予約済みJWTヘッダーを上書きさせないでください。

検証

local claims, err = crypto.jwt.verify(token, secret)
local claims, err = crypto.jwt.verify(token, secret, "HS256", false)
local claims, err = crypto.jwt.verify(token, public_key_pem, "RS256")

戻り値: table, error

expとnbfが存在する場合は常に、ワークフローの時刻基準ではなくJWTライブラリの現在の実時間に対して検証されます。require_exp = falseを設定するとexpクレームの欠落を許容しますが、存在するクレームの検証は無効になりません。時間に依存する結果をリプレイに影響するワークフロー制御に使わないでください。アクティビティ内で確認するか、明示的にリプレイ安全な値と比較して時刻を検証してください。

発行者が想定するアルゴリズムを必ず渡してください。検証ではトークンをその方式だけに制限します。返されたクレームは認証済みデータとして扱いますが、自動的に認可されたアプリケーション入力とは見なさず、発行者、オーディエンス、サブジェクト、アプリケーション固有の制約も検証してください。

鍵導出

PBKDF2

local key, err = crypto.pbkdf2(password, salt, iterations, key_length)
local key, err = crypto.pbkdf2(password, salt, iterations, key_length, "sha512")

戻り値: string, error

導出される鍵は生のバイト列です。保存するパスワード検証子ごとに新しいランダムソルトを使用し、ソルトとワークファクターのパラメータを検証子と一緒に保存してください。ソルトを秘密にする必要はありません。本番環境のパスワード保存に固定のサンプルソルトを使用しないでください。

ユーティリティ

定数時間比較

local equal = crypto.constant_time_compare(a, b)

戻り値: boolean

長さが異なる場合、結果はfalseです。基盤となる定数時間比較の保証は同じ長さの入力に対して適用されるため、固定長のダイジェストまたは同じ長さのシークレットを比較してください。

エラー

エラーの扱いについては、エラー処理を参照してください。