sm2: update comments

pkcs7/sign_enveloped.go

@@ -221,7 +221,7 @@ func (saed *SignedAndEnvelopedData) AddSignerChain(ee *smx509.Certificate, pkey
 	var tobeSigned []byte
 
 	if saed.isSM {
-		signOpt = sm2.NewSM2SignerOption(true, nil)
+		signOpt = sm2.DefaultSM2SignerOpts
 		tobeSigned = saed.data
 	} else {
 		signOpt = hasher

sm2/example_test.go

@@ -98,7 +98,7 @@ func ExamplePrivateKey_Sign_forceSM2() {
 	testkey.PublicKey.X, testkey.PublicKey.Y = testkey.ScalarBaseMult(testkey.D.Bytes())
 
 	// force SM2 sign standard and use default UID
-	sig, err := testkey.Sign(rand.Reader, toSign, sm2.NewSM2SignerOption(true, nil))
+	sig, err := testkey.Sign(rand.Reader, toSign, sm2.DefaultSM2SignerOpts)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error from sign: %s\n", err)
 		return

sm2/sm2.go

@@ -87,10 +87,12 @@ type DecrypterOpts struct {
 	CipherTextSplicingOrder ciphertextSplicingOrder
 }
 
+// NewPlainEncrypterOpts creates a SM2 non-ASN1 encrypter options.
 func NewPlainEncrypterOpts(marhsalMode pointMarshalMode, splicingOrder ciphertextSplicingOrder) *EncrypterOpts {
 	return &EncrypterOpts{ENCODING_PLAIN, marhsalMode, splicingOrder}
 }
 
+// NewPlainDecrypterOpts creates a SM2 non-ASN1 decrypter options.
 func NewPlainDecrypterOpts(splicingOrder ciphertextSplicingOrder) *DecrypterOpts {
 	return &DecrypterOpts{ENCODING_PLAIN, splicingOrder}
 }
@@ -124,7 +126,7 @@ type SM2SignerOption struct {
 	ForceGMSign bool
 }
 
-// NewSM2SignerOption create a SM2 specific signer option.
+// NewSM2SignerOption creates a SM2 specific signer option.
 // forceGMSign - if use GM specific sign logic, if yes, should pass raw message to sign.
 // uid - if forceGMSign is true, then you can pass uid, if no uid is provided, system will use default one.
 func NewSM2SignerOption(forceGMSign bool, uid []byte) *SM2SignerOption {
@@ -138,6 +140,9 @@ func NewSM2SignerOption(forceGMSign bool, uid []byte) *SM2SignerOption {
 	return opt
 }
 
+// DefaultSM2SignerOpts uses default UID and forceGMSign is true.
+var DefaultSM2SignerOpts = NewSM2SignerOption(true, nil)
+
 func (*SM2SignerOption) HashFunc() crypto.Hash {
 	return directSigning
 }
@@ -171,8 +176,7 @@ func bigIntEqual(a, b *big.Int) bool {
 // digest argument will be treated as raw data and UID will be taken from opts.
 //
 // This method implements crypto.Signer, which is an interface to support keys
-// where the private part is kept in, for example, a hardware module. Common
-// uses can use the SignASN1 function in this package directly.
+// where the private part is kept in, for example, a hardware module.
 func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error) {
 	return SignASN1(rand, priv, digest, opts)
 }
@@ -446,7 +450,9 @@ func parseCiphertextASN1(c *sm2Curve, ciphertext []byte) (*_sm2ec.SM2P256Point,
 var defaultUID = []byte{0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38}
 
 // CalculateZA ZA = H256(ENTLA || IDA || a || b || xG || yG || xA || yA).
-// Compliance with GB/T 32918.2-2016 5.5
+// Compliance with GB/T 32918.2-2016 5.5.
+//
+// This function will not use default UID even the uid argument is empty.
 func CalculateZA(pub *ecdsa.PublicKey, uid []byte) ([]byte, error) {
 	uidLen := len(uid)
 	if uidLen >= 0x2000 {
@@ -486,7 +492,9 @@ func calculateSM2Hash(pub *ecdsa.PublicKey, data, uid []byte) ([]byte, error) {
 // using the private key, priv. If the hash is longer than the bit-length of the
 // private key's curve order, the hash will be truncated to that length. It
 // returns the ASN.1 encoded signature.
-// It invokes priv.Sign directly.
+//
+// If the opts argument is instance of [*SM2SignerOption], and its ForceGMSign is true,
+// then the hash will be treated as raw message.
 func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte, opts crypto.SignerOpts) ([]byte, error) {
 	if sm2Opts, ok := opts.(*SM2SignerOption); ok && sm2Opts.ForceGMSign {
 		newHash, err := calculateSM2Hash(&priv.PublicKey, hash, sm2Opts.UID)
@@ -605,7 +613,8 @@ func addASN1IntBytes(b *cryptobyte.Builder, bytes []byte) {
 // public key, pub. Its return value records whether the signature is valid.
 //
 // Compliance with GB/T 32918.2-2016 regardless it's SM2 curve or not.
-// Caller should make sure the hash's correctness.
+// Caller should make sure the hash's correctness, in other words,
+// the caller must pre-calculate the hash value.
 func VerifyASN1(pub *ecdsa.PublicKey, hash, sig []byte) bool {
 	switch pub.Curve.Params() {
 	case P256().Params():
@@ -668,7 +677,7 @@ func verifySM2EC(c *sm2Curve, pub *ecdsa.PublicKey, hash, sig []byte) bool {
 }
 
 // VerifyASN1WithSM2 verifies the signature in ASN.1 encoding format sig of raw msg
-// and uid using the public key, pub.
+// and uid using the public key, pub. The uid can be empty, meaning to use the default value.
 //
 // It returns value records whether the signature is valid. Compliance with GB/T 32918.2-2016.
 func VerifyASN1WithSM2(pub *ecdsa.PublicKey, uid, msg, sig []byte) bool {
@@ -780,7 +789,7 @@ func IsSM2PublicKey(publicKey interface{}) bool {
 	return ok && pub.Curve == sm2ec.P256()
 }
 
-// P256 return sm2 curve signleton, this function is for backward compatibility.
+// P256 returns sm2 curve signleton, this function is for backward compatibility.
 func P256() elliptic.Curve {
 	return sm2ec.P256()
 }

smx509/x509.go

@@ -1513,7 +1513,7 @@ func CreateCertificate(rand io.Reader, template, parent, pub, priv interface{})
 			Hash:       hashFunc,
 		}
 	} else if signatureAlgorithm.Algorithm.Equal(oidSignatureSM2WithSM3) {
-		signerOpts = sm2.NewSM2SignerOption(true, nil)
+		signerOpts = sm2.DefaultSM2SignerOpts
 	}
 	signature, err = key.Sign(rand, signed, signerOpts)
 	if err != nil {
@@ -1612,7 +1612,7 @@ func (c *Certificate) CreateCRL(rand io.Reader, priv interface{}, revokedCerts [
 	signed := tbsCertListContents
 	var opts crypto.SignerOpts = hashFunc
 	if signatureAlgorithm.Algorithm.Equal(oidSignatureSM2WithSM3) {
-		opts = sm2.NewSM2SignerOption(true, nil)
+		opts = sm2.DefaultSM2SignerOpts
 	}
 	if hashFunc != 0 {
 		h := hashFunc.New()
@@ -1899,7 +1899,7 @@ func CreateCertificateRequest(rand io.Reader, template *x509.CertificateRequest,
 		signed = h.Sum(nil)
 	}
 	if sigAlgo.Algorithm.Equal(oidSignatureSM2WithSM3) {
-		opts = sm2.NewSM2SignerOption(true, nil)
+		opts = sm2.DefaultSM2SignerOpts
 	}
 
 	var signature []byte
@@ -2130,7 +2130,7 @@ func CreateRevocationList(rand io.Reader, template *x509.RevocationList, issuer
 			Hash:       hashFunc,
 		}
 	} else if signatureAlgorithm.Algorithm.Equal(oidSignatureSM2WithSM3) {
-		signerOpts = sm2.NewSM2SignerOption(true, nil)
+		signerOpts = sm2.DefaultSM2SignerOpts
 	}
 
 	signature, err := priv.Sign(rand, input, signerOpts)