Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 11439] ファイルの概要

このコミットは、Go 1リリースノートのドキュメントを更新するものです。具体的には、crypto/hmacパッケージの変更に関する記述が追加されています。影響を受けるファイルは以下の通りです。

  • doc/go1.html
  • doc/go1.tmpl

コミット

commit 68aff958ae7076ded8b4f05154106625c8dd56d
Author: Adam Langley <agl@golang.org>
Date:   Fri Jan 27 10:12:27 2012 -0800

    doc: update Go1 release notes in light of the crypto/hmac change.
    
    R=r
    CC=golang-dev
    https://golang.org/cl/5532108

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/68aff958ae7076ded8b4f05154106625c8dd56d

元コミット内容

doc: update Go1 release notes in light of the crypto/hmac change.

R=r
CC=golang-dev
https://golang.org/cl/5532108

変更の背景

このコミットは、Go言語のバージョン1（Go 1）のリリースに向けて、標準ライブラリであるcrypto/hmacパッケージに加えられた重要な変更を、公式リリースノートに反映させるために行われました。Go 1では、APIの整理と汎用性の向上が図られ、crypto/hmacパッケージ内のハッシュ関数固有のファクトリ関数（例: hmac.NewMD5）が削除されました。これにより、より柔軟なHMACの生成方法が導入されたため、既存のコードを新しいAPIに適合させるための情報と、その移行を支援するgofixツールの利用について、ユーザーに周知する必要がありました。

前提知識の解説

HMAC (Hash-based Message Authentication Code)

HMACは、メッセージ認証コード（MAC）の一種で、メッセージの完全性と認証性を保証するために使用されます。HMACは、秘密鍵とハッシュ関数（例: MD5, SHA-256）を組み合わせてメッセージの認証タグ（MAC値）を生成します。これにより、メッセージが改ざんされていないこと、および送信者が秘密鍵を知っている正当なエンティティであることを検証できます。

crypto/hmacパッケージ

Go言語の標準ライブラリに含まれるcrypto/hmacパッケージは、HMACを実装するための機能を提供します。このパッケージは、様々なハッシュ関数と組み合わせてHMACを生成・検証するためのAPIを提供します。

hash.Hashインターフェース

Go言語のhashパッケージで定義されているhash.Hashインターフェースは、任意のハッシュアルゴリズムを抽象化するための共通のインターフェースです。このインターフェースを実装する型は、データの追加（Writeメソッド）、ハッシュ値の計算（Sumメソッド）、状態のリセット（Resetメソッド）などの操作を提供します。md5.New()やsha256.New()のような関数は、このhash.Hashインターフェースを実装する新しいハッシュ関数インスタンスを返します。

gofixツール

gofixは、Go言語のツールチェーンに含まれるユーティリティで、GoのAPI変更に伴うコードの自動修正を支援します。Go言語のバージョンアップに伴い、一部のAPIが変更された場合、gofixは古いAPIの使用箇所を検出し、新しいAPIに自動的に書き換えることができます。これにより、開発者は手動でのコード修正の手間を大幅に削減し、スムーズな移行を可能にします。

技術的詳細

Go 1におけるcrypto/hmacパッケージの変更は、APIの汎用性と柔軟性を高めることを目的としていました。

  1. ハッシュ関数固有のNew関数の削除: Go 1より前は、crypto/hmacパッケージにはhmac.NewMD5やhmac.NewSHA1のように、特定のハッシュ関数に特化したHMAC生成関数が存在しました。これらの関数は、特定のハッシュアルゴリズムにHMACを結合する際に便利でしたが、新しいハッシュアルゴリズムが追加されるたびに、crypto/hmacパッケージも更新する必要がありました。

  2. hmac.New関数の変更: Go 1では、これらのハッシュ関数固有のNew関数が削除され、代わりに汎用的なhmac.New関数が強化されました。新しいhmac.New関数は、第一引数としてfunc() hash.Hash型の関数を受け取るようになりました。これは、md5.Newやsha256.Newのように、hash.Hashインターフェースを返す関数を渡すことを意味します。

    変更前（概念）:

    h := hmac.NewMD5(key) // MD5に特化

    変更後（概念）:

    h := hmac.New(md5.New, key) // 任意のhash.Hashを返す関数を受け入れる

    この変更により、crypto/hmacパッケージは、将来的に追加される可能性のある新しいハッシュアルゴリズムにも容易に対応できるようになり、APIの拡張性が向上しました。

  3. gofixによる移行支援: このAPI変更は、既存のGoコードベースに影響を与える可能性がありました。そのため、Go開発チームは、gofixツールがこの変更を自動的に検出し、古いhmac.NewMD5のような呼び出しを新しいhmac.New(md5.New, key)形式に変換するように実装しました。これにより、開発者は手動でコードを修正する手間を省き、Go 1への移行をスムーズに行うことができました。

このコミットは、これらの重要なAPI変更がGo 1のリリースノートに正確に反映されていることを確認するためのドキュメント更新です。

コアとなるコードの変更箇所

このコミットは、Go 1のリリースノートのHTMLファイルとテンプレートファイルに、crypto/hmacパッケージの変更に関する新しいセクションを追加しています。

diff --git a/doc/go1.html b/doc/go1.html
index 23ed3709fb..d839b7a278 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -875,6 +875,19 @@ in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
 as their first argument.
 </p>
 
+<h3 id="crypto/hmac">The crypto/hmac package</h3>
+
+<p>
+In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
+been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
+a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+Gofix will perform the needed changes.
+</p>
+
 <h3 id="crypto_x509">The crypto/x509 package</h3>
 
 <p>
diff --git a/doc/go1.tmpl b/doc/go1.tmpl
index fd005b102d..f1203f1907 100644
--- a/doc/go1.tmpl
+++ b/doc/go1.tmpl
@@ -779,6 +779,19 @@ in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
 as their first argument.
 </p>
 
+<h3 id="crypto/hmac">The crypto/hmac package</h3>
+
+<p>
+In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
+been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
+a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
+</p>
+
+<p>
+<em>Updating</em>:
+Gofix will perform the needed changes.
+</p>
+
 <h3 id="crypto_x509">The crypto/x509 package</h3>
 
 <p>

コアとなるコードの解説

上記の差分は、doc/go1.htmlとdoc/go1.tmplという2つのファイルに全く同じ内容が追加されていることを示しています。これは、Goのドキュメント生成システムがテンプレート（.tmpl）から最終的なHTML（.html）を生成するため、両方のファイルを更新する必要があるためです。

追加された内容は以下の通りです。

  • 見出し: <h3 id="crypto/hmac">The crypto/hmac package</h3> crypto/hmacパッケージに関する新しいセクションの開始を示します。id属性は、ドキュメント内のアンカーリンクとして機能します。

  • 変更内容の説明:

    <p>
In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
</p>

    この段落では、Go 1でhmac.NewMD5のようなハッシュ関数固有の関数が削除され、代わりにhmac.Newがhash.Hashを返す関数（例: md5.New）を受け取るようになったことが明確に説明されています。これは、前述の技術的詳細で説明したAPIの変更点をユーザーに伝えるためのものです。

  • 更新方法の指示:

    <p>
<em>Updating</em>:
Gofix will perform the needed changes.
</p>

    この重要な段落では、既存のコードを新しいAPIに適合させるための具体的な方法が示されています。Gofix will perform the needed changes.という記述は、開発者が手動でコードを修正する代わりに、gofixツールを使用することで自動的に移行できることを示唆しています。これは、Goエコシステムにおける後方互換性への配慮と、開発者の移行負担を軽減するための重要な情報です。

これらの変更は、Go 1のリリースノートが、ユーザーが新しいバージョンに移行する際に必要となる重要なAPI変更に関する正確かつ実用的な情報を提供することを保証します。

関連リンク

参考にした情報源リンク