12.45 rfc.hmac - HMAC鍵付きハッシング

Module: rfc.hmac ¶

このモジュールは、RFC 2104で定義されている、メッセージ認証のための 鍵付きハッシングのHMACアルゴリズムを実装しています。

シンプルなバッチ処理での鍵付きハッシングでは、高レベルなAPIである hmac-digestとhmac-digest-stringが使えます。 あるいは、<hmac>オブジェクトを作成して、入力となるデータで その状態を更新することもできます。

以下は典型的なHMACハッシュを計算する例です。

(use rfc.sha)  ; import desired digest algorithm
(use rfc.hmac)

(hmac-message <sha256> "secret-key" "payload")
 ⇒ #u8(16 170 46 28 37 56 70 79 247 95 6 71 39 30 59 167 70 188 163
    252 222 175 50 44 88 27 245 133 30 140 221 183)

(hmac-message-to 'hex <sha256> "secret-key" "payload")
 ⇒ "10aa2e1c2538464ff75f0647271e3ba746bca3fcdeaf322c581bf5851e8cddb7"

高レベルAPI

Function: hmac-to target algorithm key ¶

{rfc.hmac} 現在の入力ポートから読んだデータの鍵つきHMACダイジェストを計算します。 hash-classはダイジェストアルゴリズムを指定するクラス、 keyはダイジェストに使う鍵です。

targetは結果の返し方を指定します。クラスオブジェクト<u8vector> もしくは<string>の場合はそのインスタンスが返ります。 targetにはまた、エンコーディングを表す以下のシンボルを渡すこともできます: base64, base64url, base64url-nopad, base32, base32hex, base16, hex。詳しくはutil.digest - メッセージダイジェストフレームワークを参照してください。

hash-class引数には<message-digest-algorithm>を実装している クラスを渡します。例えばrfc.shaモジュールの<sha256>です。 (rfc.sha - SHAメッセージダイジェスト参照)。

keyは文字列かu8vectorでなければなりません。

Function: hmac-message-to target hash-class key message ¶

{rfc.hmac} messageのHMACダイジェストを、 hash-classをアルゴリズム、keyを鍵として計算して返します。

hash-class引数は<message-digest-algorithm>を実装している クラスでなければなりません。例えばrfc.shaモジュールの<sha256>です。 (rfc.sha - SHAメッセージダイジェスト参照)。

key、messageには文字列かu8vectorを渡せます。

targetは結果のを返すオブジェクトのクラスを指定します。 <u8vector>と<string>がサポートされています。 targetにはまた、エンコーディングを表す以下のシンボルを渡すこともできます: base64, base64url, base64url-nopad, base32, base32hex, base16, hex。詳しくはutil.digest - メッセージダイジェストフレームワークを参照してください。

Function: hmac-message hash-class key message ¶

{rfc.hmac} (hmac-message-to <u8vector> hash-class key message) の短縮形です。

(hmac-message <sha256> "secret" "Aloha, honua")
 ⇒ #u8(78 232 135 13 246 139 36 242 133 33 99 185 4 249 244
    22 243 46 120 130 192 235 60 187 172 180 223 169 179 247 186 185)

Function: hmac-verify hash-class digest key message ¶

{rfc.hmac} messageの鍵つきダイジェストがdigestと一致するかどうか調べます。 機能的には(equal? digest (hmac-message hash-class key message)) と同じですが、タイミングアタックを防ぐ比較が使われます。

hash-classは<message-digest-algorithm>を継承したクラス、 例えば<sha256>です。digestはu8vectorでなければなりません。 keyとmessageには文字列edもu8vectorでも渡せます。

(hmac-verify <sha256>
             '#u8(78 232 135 13 246 139 36 242 133 33 99 185 4 249 244 22 243 46
                  120 130 192 235 60 187 172 180 223 169 179 247 186 185)
             "secret"
             "Aloha, honua")
 ⇒ #t

低レベルAPI

Class: <hmac> ¶

{rfc.hmac} HMACアルゴリズムの状態情報を保持します。インスタンスを作るには、 このクラスをmakeするのではなく、下に示すmake-hmacを使ってください。

Function: make-hmac algorithm key ¶

{rfc.hmac} 新たな<hmac>オブジェクトを作って返します。 algorithm引数は<message-digest-algorithm>を継承する クラスで、ダイジェストアルゴリズムを指定します。 例えば<sha256>が使えます。詳しくはrfc.sha - SHAメッセージダイジェスト参照。 key引数は文字列かu8vectorで鍵を指定します。

hmac-messageなどの高レベルAPIを使う場合、 <hmac>オブジェクトは内部で自動的に作られるので明示的にmakeする必要はありません。 下のストリーム更新手続きを使う場合だけ、<hmac>オブジェクトを 明示的に作る必要があります。

Method: hmac-update! (hmac <hmac>) data ¶

{rfc.hmac} (不完全かもしれない)文字列で表現されるdataにより、 hmacの内部状態を更新します。

Method: hmac-final! (hmac <hmac>) :optional target ¶

{rfc.hmac} hmacの内部状態を終了させ、ダイジェストをtargetで指定される インスタンスで返します。targetはクラスオブジェクト<string> または<u8vector>、あるいはエンコーディングを示すシンボルでなければ なりません。targetについて詳しくは上のhmac-toの項を参照してください。 targetが省略された場合は、歴史的な理由から<string>が使われます。

一旦終了されると、hmacに対してはhmac-update!や hmac-final!を呼ぶことはできません。

非推奨API

以下の手続きは非推奨になりました。hmac-toやhmac-messageが かわりに使えます。

Function: hmac-digest :key key hasher ¶

{rfc.hmac} Deprecated. <hmac>オブジェクトを作り、現在の入力ポートからの データストリームをハッシュし、不完全文字列でそのハッシュされた 結果を返します。

Function: hmac-digest-string string :key key hasher ¶

{rfc.hmac} Deprecated. <hmac>オブジェクトを作り、stringにあるデータをハッシュし、 不完全文字列でそのハッシュされた結果を返します。