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

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

このコミットは、Go言語の標準ライブラリ crypto/cipher パッケージ内の AEAD.Open メソッドのドキュメンテーションの修正に関するものです。具体的には、エラー処理に関する記述がGoの一般的な慣習に沿うように調整されています。

コミット

commit c7157bf44926f489c5db1c830748d9072d17852f
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Tue Mar 4 09:58:54 2014 -0800

    crypto/cipher: fix AEAD.Open documentation nit

    It mentioned true and false for error values. Instead, just
    don't mention the error semantics, as they match normal Go
    conventions (if error is non-nil, the other value is
    meaningless). We generally only document error values when
    they're interesting (where non-nil, non-nil is valid, or the
    error value can be certain known values or types).

    Fixes #7464

    LGTM=agl
    R=agl
    CC=golang-codereviews
    https://golang.org/cl/68440044

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

https://github.com/golang/go/commit/c7157bf44926f489c5db1c830748d9072d17852f

元コミット内容

crypto/cipher: fix AEAD.Open documentation nit

このコミットは、AEAD.Open のドキュメンテーションにおける些細な（"nit"）修正です。以前のドキュメンテーションでは、エラー値に対して true や false といったブール値が言及されていましたが、これはGoの標準的なエラー処理の慣習に合致しないため削除されました。Goでは、エラーが nil でない場合、他の戻り値は意味を持たないという一般的なルールがあります。エラー値が特に興味深い（例えば、nil でないエラーと nil でない他の値が同時に有効な場合、またはエラー値が特定の既知の値や型である場合）にのみ、エラー値についてドキュメントに記載するのが一般的です。

この修正は、Issue #7464 を解決します。

変更の背景

Go言語では、関数の戻り値として (result, error) のペアを返すのが一般的な慣習です。ここで error が nil でない場合、通常 result の値は未定義または無意味と見なされます。これは、エラーが発生した際には、そのエラー自体が主要な情報であり、部分的な結果や不完全な結果を返すことは稀であるという設計思想に基づいています。

crypto/cipher パッケージの AEAD.Open メソッドの以前のドキュメンテーションでは、エラー時に nil と false が返されると記載されていました。しかし、AEAD.Open メソッドのシグネチャは ([]byte, error) であり、ブール値を返すようにはなっていません。この記述は、Goのエラー処理の一般的な慣習と矛盾しており、誤解を招く可能性がありました。

このコミットの目的は、ドキュメンテーションをGoの標準的なエラー処理の慣習に合わせ、不要な混乱を避けることです。つまり、「エラーが nil でない場合、他の戻り値は無意味である」という暗黙の了解を前提とし、特に言及する必要がない限り、エラー時の他の戻り値の状態については記述しないという方針に沿っています。

前提知識の解説

Go言語のエラーハンドリング

Go言語では、例外処理のメカニズムとして try-catch のような構文は提供されていません。代わりに、関数は通常、最後の戻り値として error 型の値を返します。

func doSomething() (resultType, error) {
    // ... 処理 ...
    if someErrorCondition {
        return zeroValue, errors.New("something went wrong")
    }
    return actualResult, nil
}

呼び出し元は、返された error 値が nil かどうかをチェックすることで、処理が成功したか失敗したかを判断します。

result, err := doSomething()
if err != nil {
    // エラー処理
    fmt.Println("Error:", err)
    return
}
// 成功時の処理
fmt.Println("Success:", result)

この慣習において、err が nil でない場合、result の値は通常、有効なものとして扱われません。これは、関数がエラーを返した時点で、その関数の目的が達成されなかったことを意味するためです。

crypto/cipher パッケージ

crypto/cipher パッケージは、Go言語における共通の暗号化インターフェースを提供します。このパッケージは、ブロック暗号、ストリーム暗号、認証付き暗号（Authenticated Encryption with Associated Data: AEAD）などのプリミティブを定義しています。

AEAD (Authenticated Encryption with Associated Data)

AEADは、データの機密性（暗号化）と完全性（認証）の両方を提供する暗号化モードです。さらに、暗号化されていないが認証されるべき追加データ（Associated Data: AD）を含めることができます。これは、例えばネットワークプロトコルのヘッダーなど、暗号化する必要はないが改ざんを検出したい情報に利用されます。

AEADの主要な操作は以下の2つです。

  • Seal: 平文と追加データを入力として受け取り、暗号文と認証タグを生成します。
  • Open: 暗号文、認証タグ、追加データを入力として受け取り、それらを検証し、成功すれば平文を復号します。検証に失敗した場合（データが改ざんされた場合など）はエラーを返します。

GCM (Galois/Counter Mode)

GCMは、AEADを提供する一般的なブロック暗号モードの一つです。AES-GCMなどがよく知られています。crypto/cipher/gcm.go は、このGCMモードの実装に関連するコードが含まれています。

技術的詳細

このコミットは、crypto/cipher/gcm.go ファイル内の AEAD インターフェースの Open メソッドのドキュメンテーションコメントを修正しています。

元のドキュメンテーションは以下のようでした（抜粋）：

// Open decrypts and authenticates ciphertext, authenticates the
// additional data and, if successful, appends the resulting plaintext
// to dst, returning the updated slice and true. On error, nil and
// false is returned. The nonce must be NonceSize() bytes long and both
// it and the additional data must match the value passed to Seal.

この中で問題とされたのは、「On error, nil and false is returned.」という部分です。

  1. false の言及: Open メソッドのシグネチャは Open(dst, nonce, ciphertext, data []byte) ([]byte, error) であり、ブール値を返すようにはなっていません。したがって、false が返されるという記述は誤りです。
  2. エラー時の戻り値の明示: Goの慣習では、エラーが返された場合（error が nil でない場合）、他の戻り値（この場合は []byte）は通常、意味を持たないと見なされます。そのため、特に「nil が返される」と明示的に記述する必要はありません。これはGoの設計哲学の一部であり、エラーが発生した場合は、そのエラー自体が唯一の信頼できる情報源であるべきだという考えに基づいています。

このコミットでは、上記の点を修正し、ドキュメンテーションをより簡潔でGoの慣習に沿ったものにしています。

修正後のドキュメンテーションは以下のようになります（抜粋）：

// Open decrypts and authenticates ciphertext, authenticates the
// additional data and, if successful, appends the resulting plaintext
// to dst, returning the updated slice. The nonce must be NonceSize()
// bytes long and both it and the additional data must match the
// value passed to Seal.

変更点としては、「On error, nil and false is returned.」という行が削除され、代わりに「returning the updated slice.」と簡潔に記述されています。これにより、エラー時の戻り値に関する誤解を招く記述が排除され、Goの標準的なエラー処理のセマンティクスに合致するようになりました。

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

変更は src/pkg/crypto/cipher/gcm.go ファイルの1箇所のみです。

--- a/src/pkg/crypto/cipher/gcm.go
+++ b/src/pkg/crypto/cipher/gcm.go
@@ -30,9 +30,9 @@ type AEAD interface {
 
 	// Open decrypts and authenticates ciphertext, authenticates the
 	// additional data and, if successful, appends the resulting plaintext
-	// to dst, returning the updated slice and true. On error, nil and
-	// false is returned. The nonce must be NonceSize() bytes long and both
-	// it and the additional data must match the value passed to Seal.
+	// to dst, returning the updated slice. The nonce must be NonceSize()
+	// bytes long and both it and the additional data must match the
+	// value passed to Seal.
 	//
 	// The ciphertext and dst may alias exactly or not at all.
 	Open(dst, nonce, ciphertext, data []byte) ([]byte, error)

具体的には、AEAD インターフェース内の Open メソッドのドキュメンテーションコメントが変更されています。

  • 削除された行: 
    // to dst, returning the updated slice and true. On error, nil and
// false is returned. The nonce must be NonceSize() bytes long and both
// it and the additional data must match the value passed to Seal.
  • 追加された行: 
    // to dst, returning the updated slice. The nonce must be NonceSize()
// bytes long and both it and the additional data must match the
// value passed to Seal.

これにより、エラー時の true や false の言及が削除され、Goの一般的なエラー処理の慣習に沿った記述になりました。

コアとなるコードの解説

このコミットで変更されたのは、Goのインターフェース定義におけるドキュメンテーションコメントです。Goでは、インターフェースのメソッドにはその動作を説明するコメントを記述することが推奨されています。このコメントは、GoDocツールによって自動的にドキュメントとして生成され、開発者がライブラリを使用する際の重要な情報源となります。

AEAD インターフェースは、認証付き暗号化の機能を提供するための抽象化です。Open メソッドは、暗号文を復号し、関連データを認証する役割を担います。

変更前のコメントは、Open メソッドが成功時に (slice, true) を返し、エラー時に (nil, false) を返すと誤って示していました。しかし、Open メソッドの実際のシグネチャは ([]byte, error) であり、ブール値を返すことはありません。また、Goの慣習として、エラーが返された場合（error が nil でない場合）、他の戻り値（この場合は []byte）は通常、意味を持たないため、その状態を明示的に記述する必要はありません。

この修正は、ドキュメンテーションの正確性を高め、Goのエラーハンドリングのベストプラクティスに準拠させることを目的としています。これにより、crypto/cipher パッケージを使用する開発者が、AEAD.Open メソッドの挙動、特にエラー処理について正しく理解できるようになります。これは、ライブラリの使いやすさと堅牢性を向上させる上で重要な「些細な」修正と言えます。

関連リンク

参考にした情報源リンク