cipher: update comments

Author: emmansun

cipher/ghash.go

@@ -1,3 +1,7 @@
+// Copyright 2025 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher
 
 import "github.com/emmansun/gmsm/internal/byteorder"

cipher/gxm.go

@@ -1,3 +1,7 @@
+// Copyright 2025 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher
 
 import (
@@ -19,12 +23,16 @@ type gxm struct {
 }
 
 // NewGXM creates a new GXM instance using the provided cipher stream and hash key.
-// It uses the default tag size of 16 bytes.
+// It uses the default tag size of 16 bytes. 
+//
+// Due to the nature of GXM, the same stream cipher instance should not be reused.
 func NewGXM(stream cipher.Stream, hkey []byte) (*gxm, error) {
 	return NewGXMWithTagSize(stream, hkey, 16)
 }
 
 // NewGXMWithTagSize creates a new instance of GXM (Galois XOR Mode) with a specified tag size.
+//
+// Due to the nature of GXM, the same stream cipher instance should not be reused.
 func NewGXMWithTagSize(stream cipher.Stream, hkey []byte, tagSize int) (*gxm, error) {
 	if len(hkey) != ghashBlockSize {
 		return nil, errors.New("cipher: invalid hash key length")
@@ -65,8 +73,7 @@ func (g *gxm) Overhead() int {
 
 // Seal encrypts and authenticates plaintext, authenticates the
 // additional data and appends the result to dst, returning the updated
-// slice. The nonce must be NonceSize() bytes long and unique for all
-// time, for a given key.
+// slice. 
 //
 // To reuse plaintext's storage for the encrypted output, use plaintext[:0]
 // as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
@@ -87,8 +94,7 @@ func (g *gxm) Seal(dst, plaintext, additionalData []byte) []byte {
 
 // 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
+// to dst, returning the updated slice. The additional data must match the
 // value passed to Seal.
 //
 // To reuse ciphertext's storage for the decrypted output, use ciphertext[:0]

cipher/hctr.go

@@ -1,3 +1,7 @@
+// Copyright 2024 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher
 
 import (

cipher/mur.go

@@ -1,3 +1,7 @@
+// Copyright 2025 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher
 
 import (
@@ -70,13 +74,12 @@ func (g *mur) Overhead() int {
 
 // Seal encrypts and authenticates plaintext, authenticates the
 // additional data and appends the result to dst, returning the updated
-// slice. The nonce must be NonceSize() bytes long and unique for all
-// time, for a given key.
+// slice. 
 //
 // To reuse plaintext's storage for the encrypted output, use plaintext[:0]
 // as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
 // dst and additionalData may not overlap.
-func (g *mur) Seal(iv, key1, key2, dst, plaintext, additionalData []byte) ([]byte, error) {
+func (g *mur) Seal(iv, dataKey, tagKey, dst, plaintext, additionalData []byte) ([]byte, error) {
 	ret, out := alias.SliceForAppend(dst, len(plaintext)+g.tagSize)
 	if alias.InexactOverlap(out, plaintext) {
 		panic("cipher: invalid buffer overlap")
@@ -95,15 +98,15 @@ func (g *mur) Seal(iv, key1, key2, dst, plaintext, additionalData []byte) ([]byt
 	copy(tmpIV[:], iv)
 	g.murAuth(tmpIV[:], plaintext, additionalData)
 	subtle.XORBytes(tmpIV[:], tmpIV[:], iv)
-	tagStream, err := g.streamCipherCreator(key2, tmpIV[:ivLen])
+	tagStream, err := g.streamCipherCreator(tagKey, tmpIV[:ivLen])
 	if err != nil {
 		return nil, err
 	}
 	tagStream.XORKeyStream(tag[:g.tagSize], tag[:g.tagSize])
 
 	clear(tmpIV[:])
 	subtle.XORBytes(tmpIV[:], iv, tag[:])
-	dataStream, err := g.streamCipherCreator(key1, tmpIV[:ivLen])
+	dataStream, err := g.streamCipherCreator(dataKey, tmpIV[:ivLen])
 	if err != nil {
 		return nil, err
 	}
@@ -114,17 +117,16 @@ func (g *mur) Seal(iv, key1, key2, dst, plaintext, additionalData []byte) ([]byt
 
 // 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.
+// to dst, returning the updated slice. The iv, dataKey, tagKey
+// and the additional data must match the value passed to Seal.
 //
 // To reuse ciphertext's storage for the decrypted output, use ciphertext[:0]
 // as dst. Otherwise, the remaining capacity of dst must not overlap ciphertext.
 // dst and additionalData may not overlap.
 //
 // Even if the function fails, the contents of dst, up to its capacity,
 // may be overwritten.
-func (g *mur) Open(iv, key1, key2, dst, ciphertext, additionalData []byte) ([]byte, error) {
+func (g *mur) Open(iv, dataKey, tagKey, dst, ciphertext, additionalData []byte) ([]byte, error) {
 	if len(ciphertext) < g.tagSize {
 		return nil, errOpen
 	}
@@ -148,7 +150,7 @@ func (g *mur) Open(iv, key1, key2, dst, ciphertext, additionalData []byte) ([]by
 	}
 	copy(tmpIV[:], tag)
 	subtle.XORBytes(tmpIV[:], iv, tmpIV[:])
-	dataStream, err := g.streamCipherCreator(key1, tmpIV[:ivLen])
+	dataStream, err := g.streamCipherCreator(dataKey, tmpIV[:ivLen])
 	if err != nil {
 		return nil, err
 	}
@@ -157,7 +159,7 @@ func (g *mur) Open(iv, key1, key2, dst, ciphertext, additionalData []byte) ([]by
 	clear(tmpIV[:])
 	g.murAuth(tmpIV[:], out, additionalData)
 	subtle.XORBytes(tmpIV[:], tmpIV[:], iv)
-	tagStream, err := g.streamCipherCreator(key2, tmpIV[:ivLen])
+	tagStream, err := g.streamCipherCreator(tagKey, tmpIV[:ivLen])
 	if err != nil {
 		return nil, err
 	}

cipher/zuc_gxm_test.go

@@ -1,3 +1,7 @@
+// Copyright 2025 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher_test
 
 import (

cipher/zuc_mur_test.go

@@ -1,3 +1,7 @@
+// Copyright 2025 Sun Yimin. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
 package cipher_test
 
 import (