暗号化関数 ​

暗号化関数は、インテグレーションで実際に必要な暗号技術を扱います。たとえば、webhookが主張どおりの送信者から送信されたことの証明、送信APIリクエストへの署名、JWTの生成、チェックサムの計算などです。

アルゴリズムの選択 ​

ユースケースに最適なアルゴリズムを使用します。

MD5とSHA-1は破られています。セキュリティ上重要な用途には使用しないでください。 WELがこれらを提供しているのは、インテグレーションで、これらをまだ使用しているパートナーシステムに合わせる必要がある場合があるためです。新しい作業には選択しないでください。

命名規則 ​

各アルゴリズムには、hex_プレフィックスで区別される2つの形式があります。

• sha256(...)はBinaryダイジェスト、つまり生バイトを返します。
• hex_sha256(...)は16進文字のStringを返します。

16進形式を署名ヘッダーと比較するか、JSONフィールドに入れます。ダイジェストを別の関数に渡す場合は、Binary形式を使用します。

ハッシュ化 ​

すべてのハッシュ関数はStringまたはBinaryを受け入れます。

hex_sha256とsha256 ​

SHA-256は新しい作業のデフォルトの選択肢です。

hex_sha256(value)
sha256(value)

hex_sha256('acme')

822b33ad87c148a0a20a5ba7cd5ebcaa68d36a18e7aad165554903f52ca82757

byte_length(sha256('acme'))

32

hex_sha512とsha512 ​

SHA-512は、同じファミリーからより長いダイジェストを生成します。

hex_sha512(value)
sha512(value)

byte_length(sha512('acme'))

64

hex_sha512_256とsha512_256 ​

SHA-512/256は256ビットのダイジェストを生成し、SHA-256の長さ拡張特性を回避します。

シークレットとメッセージをハッシュ化する場合に使用します。ただし、その場合はHMACの方がより直接的に処理でき、通常はより適した選択肢です。

hex_sha512_256(value)
sha512_256(value)

hex_sha512_256('acme')

2e7a8d79ac01f85db494bfddf90cc808d091543addc18bb68ad643257234735a

hex_sha1とsha1 ​

SHA-1はレガシー専用であり、まだ必要としているシステムとの互換性のために保持されています。

hex_sha1(value)
sha1(value)

hex_sha1('acme')

293abb6b76d7791c0732cc517d38c4b5c734b87f

hex_md5とmd5 ​

MD5はレガシー専用であり、敵対的でないチェックサムにのみ適しています。

hex_md5(value)
md5(value)

hex_md5('acme')

53bce4f1dfa0fe8e7ca126f91b35d3a6

HMAC署名 ​

HMACは、メッセージと共有シークレットを組み合わせて署名を生成します。 webhookプロバイダーは通常、信頼された送信者からリクエストが送信されたことを検証するためにHMAC署名を使用します。

すべてのHMAC関数は、メッセージを先に、キーを後に取ります。

hmac_hexとhmac ​

引数として指定されたアルゴリズムでHMACを計算します。

hmac_hex(message, key, algorithm)
hmac(message, key, algorithm)

hmac_hex('payload', 'secret', 'sha256')

b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4

byte_length(hmac('payload', 'secret', 'sha256'))

32

hmac_algos ​

サポートされているHMACアルゴリズムを一覧表示します。

hmac_algos()

hmac_algos()

["md5", "sha1", "sha256", "sha384", "sha512"]

hmac_hex_sha256とhmac_sha256 ​

ほとんどのwebhookプロバイダーはHMAC-SHA256を使用します。

hmac_hex_sha256(message, key)
hmac_sha256(message, key)

hmac_hex_sha256('payload', 'secret')

b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4

hmac_hex_sha384とhmac_sha384 ​

HMAC-SHA384はHMAC-SHA256と同様に機能し、より長いダイジェストを使用します。

hmac_hex_sha384(message, key)
hmac_sha384(message, key)

byte_length(hmac_sha384('payload', 'secret'))

48

hmac_hex_sha512とhmac_sha512 ​

HMAC-SHA512はHMAC-SHA256と同様に機能し、HMAC-SHA384よりさらに長いダイジェストを使用します。

hmac_hex_sha512(message, key)
hmac_sha512(message, key)

byte_length(hmac_sha512('payload', 'secret'))

64

hmac_hex_sha1とhmac_sha1 ​

HMAC-SHA1はレガシー専用であり、まだ必要としているシステムとの互換性のために保持されています。

hmac_hex_sha1(message, key)
hmac_sha1(message, key)

byte_length(hmac_sha1('payload', 'secret'))

20

hmac_hex_md5とhmac_md5 ​

HMAC-MD5はレガシー専用であり、まだ必要としているシステムとの互換性のために保持されています。

hmac_hex_md5(message, key)
hmac_md5(message, key)

byte_length(hmac_md5('payload', 'secret'))

16

ユースケース: インバウンドwebhook署名の検証 ​

プロバイダーは共有シークレットを使用して生の本文に署名し、その結果をヘッダーで送信します。 hmac_hex_sha256を使用して署名を再計算し、ヘッダーと比較します。

入力

{
  "body": "payload",
  "secret": "secret",
  "signature_header": "b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4"
}

Formula

{
  expected: hmac_hex_sha256(_.body, _.secret),
  valid: hmac_hex_sha256(_.body, _.secret) == _.signature_header
}

出力

{
  "expected": "b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4",
  "valid": true
}

受信したとおりの生の本文に署名します。 JSONを解析して再シリアル化すると、キーの順序や空白を含むバイトが変化します。何も問題がなくても、署名は一致しません。

JSON webトークン ​

WELはHMAC署名付きJWTをサポートしています: HS256、HS384、HS512。

jwt_encode ​

JWTを構築して署名します。

jwt_encode(payload, key, algorithm, options)

jwt_encode({sub: 'user-1'}, '0123456789abcdef0123456789abcdef', 'HS256')

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEifQ.FKuUN7RwYyegTHXiye1jBlIKzmjIfb39oxKzJk_Gmdo

jwt_decode ​

JWTをデコードし、その署名を検証します。署名が一致しないトークンは、その内容を返すのではなくエラーを発生させます。

jwt_decode(token, key, algorithm, options)

jwt_decode(jwt_encode({sub: 'user-1'}, '0123456789abcdef0123456789abcdef', 'HS256'), '0123456789abcdef0123456789abcdef', 'HS256')

{header: {alg: "HS256", typ: "JWT"}, payload: {sub: "user-1"}}

jwt_algos ​

サポートされているJWT署名アルゴリズムを一覧表示します。

jwt_algos()

jwt_algos()

["HS256", "HS384", "HS512"]

キー導出 ​

キー導出は、パスワードを暗号化に適した暗号キーに変換します。

pbkdf2 ​

PBKDF2を使用してパスワードからキーを導出します。

反復回数を増やすとパスワード推測のコストが高くなるため、宛先システムで許可される最大値を使用します。固定のソルトを書き込むのではなく、random_bytesからソルトを取得します。

pbkdf2(password, salt, iterations, key_length, algorithm)

encode_hex_string(pbkdf2('password', 'salt', 1000, 16, 'sha256'))

632c2812e46d4604102ba7618e9d6d7d

暗号化 ​

次の関数は、CBCモードのAESでデータを暗号化および復号化します。

aes_cbc_encrypt ​

PKCS7パディングを適用して、CBCモードのAESでデータを暗号化します。

aes_cbc_encrypt(data, key, iv)

encode_base64(aes_cbc_encrypt('secret data!!!!!', '0123456789abcdef', 'abcdef0123456789'))

NsFUgzVrilJO5OF/imH/gbF6NPToZkf1hbVBJkaXXoY=

aes_cbc_decrypt ​

AES-CBCデータを復号化し、PKCS7パディングを削除します。

aes_cbc_decrypt(data, key, iv)

decode_string(aes_cbc_decrypt(aes_cbc_encrypt('secret data!!!!!', '0123456789abcdef', 'abcdef0123456789'), '0123456789abcdef', 'abcdef0123456789'), 'UTF-8')

secret data!!!!!

関連情報 ​

• バイナリ関数: encode_base64、encode_hex_string、およびbyte_lengthに関する詳細情報。
• ランダム関数: ソルトと初期化ベクトル用にrandom_bytesを生成します。
• エンコード関数: decode_stringを使用して、復号化されたバイトをテキストに戻します。
• エラーコード: E220などのジョブ失敗をトラブルシューティングします。