Refine the public API interface

algorithm.go

@@ -2,14 +2,13 @@ package itsdangerous
 
 import (
 	"crypto/hmac"
-	"crypto/subtle"
 	"hash"
 )
 
 // SigningAlgorithm provides interfaces to generate and verify signature
 type SigningAlgorithm interface {
-	GetSignature(key, value string) []byte
-	VerifySignature(key, value string, sig []byte) bool
+	GetSignature(key []byte, value string) []byte
+	VerifySignature(key []byte, value string, signature []byte) bool
 }
 
 // HMACAlgorithm provides signature generation using HMACs.
@@ -18,15 +17,16 @@ type HMACAlgorithm struct {
 }
 
 // GetSignature returns the signature for the given key and value.
-func (a *HMACAlgorithm) GetSignature(key, value string) []byte {
-	a.DigestMethod().Reset()
-	h := hmac.New(func() hash.Hash { return a.DigestMethod() }, []byte(key))
+func (a *HMACAlgorithm) GetSignature(key []byte, value string) []byte {
+	h := hmac.New(a.DigestMethod, key)
 	h.Write([]byte(value))
 	return h.Sum(nil)
 }
 
 // VerifySignature verifies the given signature matches the expected signature.
-func (a *HMACAlgorithm) VerifySignature(key, value string, sig []byte) bool {
-	eq := subtle.ConstantTimeCompare(sig, []byte(a.GetSignature(key, value)))
-	return eq == 1
+func (a *HMACAlgorithm) VerifySignature(key []byte, value string, signature []byte) bool {
+	return hmac.Equal(
+		signature,
+		a.GetSignature(key, value),
+	)
 }

errors.go

@@ -0,0 +1,22 @@
+package itsdangerous
+
+import "fmt"
+
+type InvalidSignatureError struct {
+	err error
+}
+
+func (e InvalidSignatureError) Error() string { return e.err.Error() }
+func (e InvalidSignatureError) Unwrap() error { return e.err }
+
+type SignatureExpiredError struct {
+	age, maxAge int64
+}
+
+func (e SignatureExpiredError) Error() string {
+	return fmt.Sprintf("signature age %d > %d seconds", e.age, e.maxAge)
+}
+
+func signatureExpired(age, maxAge int64) error {
+	return InvalidSignatureError{SignatureExpiredError{age: age, maxAge: maxAge}}
+}

python_examples/generate_examples.py

@@ -0,0 +1,18 @@
+from freezegun import freeze_time
+from itsdangerous import Signer, TimestampSigner
+
+key = "secret_key"
+salt = "salt"
+
+print(f"Signer examples {key=} {salt=}")
+s = Signer(key, salt)
+print("  'my string' ->", s.sign("my string"))
+print("  'aaaaaaaaaaaaaaaa' ->", s.sign("aaaaaaaaaaaaaaaa"))
+print()
+
+print(f"TimestampSigner examples {key=} {salt=}")
+s = TimestampSigner(key, salt)
+with freeze_time("2024-09-27T14:00:00Z"):
+    print("  'my string' ->", s.sign("my string"), "at time 2024-09-27T14:00:00Z")
+with freeze_time("2024-09-27T15:00:00Z"):
+    print("  'my string' ->", s.sign("my string"), "at time 2024-09-27T15:00:00Z")