Signing Algorithms

CyberGo JWT supports 4 categories with 12 signing algorithms, covering scenarios from monolithic apps to microservice architectures.

Algorithm Overview

Type	Algorithms	Key Type	Use Case
HMAC	HS256 / HS384 / HS512	Symmetric key	Single apps, simple services
RSA	RS256 / RS384 / RS512	Public/Private key	Microservices, multi-service validation
RSA-PSS	PS256 / PS384 / PS512	Public/Private key	Microservices (recommended over RSA)
ECDSA	ES256 / ES384 / ES512	Public/Private key	High-performance microservices

HMAC (Symmetric Key)

HMAC uses the same key for signing and verification — the simplest approach.

Key Requirements

• Minimum 32 bytes
• Library auto-detects weak keys (repeated characters, sequential patterns, etc.)

Usage

cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
cfg.SigningMethod = jwt.SigningMethodHS256 // default, can be omitted

Algorithm Selection

Constant	Algorithm	Description
SigningMethodHS256	HMAC-SHA256	Recommended, balanced performance and security
SigningMethodHS384	HMAC-SHA384	Higher security
SigningMethodHS512	HMAC-SHA512	Highest security

Recommendation

HS256 is sufficient for most scenarios. Keys should be generated using cryptographically secure random methods, at least 32 bytes.

RSA (Asymmetric Key)

RSA uses a private key for signing and a public key for verification. Suitable when the verifying party doesn't need the private key.

Usage

cfg := jwt.DefaultConfig()
cfg.SigningMethod = jwt.SigningMethodRS256
cfg.SigningKey = rsaPrivateKey        // *rsa.PrivateKey
cfg.VerificationKey = rsaPublicKey    // *rsa.PublicKey (optional)

Verification Key

VerificationKey is optional. When not set, the library uses SigningKey for verification (internally extracts the public key from the private key).

Key Generation

// Generate 2048-bit RSA key pair
privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
    log.Fatal(err)
}
publicKey := &privateKey.PublicKey

Algorithm Selection

Constant	Algorithm	Description
SigningMethodRS256	RSA-SHA256	Recommended
SigningMethodRS384	RSA-SHA384	Higher security
SigningMethodRS512	RSA-SHA512	Highest security

RSA-PSS (Asymmetric Key, Recommended over RSA)

RSA-PSS is an improved RSA signing scheme using Probabilistic Signature Scheme (PSS) padding, offering better security than PKCS#1 v1.5. Uses the same keys as RSA.

Usage

cfg := jwt.DefaultConfig()
cfg.SigningMethod = jwt.SigningMethodPS256
cfg.SigningKey = rsaPrivateKey        // *rsa.PrivateKey (same key as RSA)
cfg.VerificationKey = rsaPublicKey    // *rsa.PublicKey (optional)

Recommended Replacement

RSA-PSS is more secure than RSA PKCS#1 v1.5. New projects should prefer RSA-PSS algorithms. Keys are identical to RSA — no additional key generation needed.

Algorithm Selection

Constant	Algorithm	Description
SigningMethodPS256	RSA-PSS-SHA256	Recommended
SigningMethodPS384	RSA-PSS-SHA384	Higher security
SigningMethodPS512	RSA-PSS-SHA512	Highest security

ECDSA (Elliptic Curve)

ECDSA is also asymmetric but with shorter keys and better performance.

Usage

cfg := jwt.DefaultConfig()
cfg.SigningMethod = jwt.SigningMethodES256
cfg.SigningKey = ecdsaPrivateKey      // *ecdsa.PrivateKey
cfg.VerificationKey = ecdsaPublicKey  // *ecdsa.PublicKey (optional)

Key Generation

// Generate P-256 curve key pair
privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
if err != nil {
    log.Fatal(err)
}
publicKey := &privateKey.PublicKey

Algorithm Selection

Constant	Algorithm	Curve	Description
SigningMethodES256	ECDSA-SHA256	P-256	Recommended
SigningMethodES384	ECDSA-SHA384	P-384	Higher security
SigningMethodES512	ECDSA-SHA512	P-521	Highest security

How to Choose

Monolithic app ────────→ HMAC
Microservices (same trust domain) → HMAC
Microservices (cross-service verification) → RSA, RSA-PSS, or ECDSA
Security priority ─────→ RSA-PSS (replaces RSA)
High performance ──────→ ECDSA
Short key length ──────→ ECDSA

Factor	HMAC	RSA	RSA-PSS	ECDSA
Sign speed	Fast	Slower	Slower	Fast
Verify speed	Fast	Fast	Fast	Fast
Key length	32+ bytes	2048+ bits	2048+ bits	256+ bits
Signature length	Fixed	Long (~256 bytes)	Long (~256 bytes)	Short (~64 bytes)
Architecture coupling	Tight	Loose	Loose	Loose
Security	High	High	Higher	High

Security Notes

Prohibited

• Never hardcode keys in source code
• Never use weak keys (pure digits, repeated characters, etc.)
• Never use the none algorithm (automatically rejected by this library)
• HMAC keys must not be shorter than 32 bytes

Best Practices

• Use environment variables or key management services
• Rotate signing keys regularly
• Use RSA or ECDSA in production
• RSA keys should be 2048 bits or larger

Next Steps

• Custom Claims — Define business fields
• API Reference → Package Functions — Complete API signatures
• Basic Examples — HMAC complete example