Master Secure Go Cryptography: Common Pitfalls & Best Practices

Introduction

Many Go projects still use insecure practices such as math/rand for key generation, RSA PKCS#1 v1.5 signatures, or raw AES‑CBC encryption. These mistakes lead to security incidents. This guide explains Go cryptographic techniques from basics to advanced usage, highlighting pitfalls and providing real‑world examples.

1. Fundamentals: Three Cryptography Categories

Symmetric encryption (AES, ChaCha20) – same key for encryption and decryption.

Asymmetric encryption (RSA, ECC, Ed25519) – different keys for encryption/signature and decryption/key exchange.

Hash & MAC (SHA, HMAC) – integrity verification and password storage.

Tip: Understand the category before selecting a tool.

2. Random Numbers & Key Management

Wrong:

key := make([]byte, 32)
for i := range key {
    key[i] = byte(rand.Intn(256)) // math/rand, insecure
}

Correct:

key := make([]byte, 32)
if _, err := rand.Read(key); err != nil {
    panic(err)
}
fmt.Printf("Secure key: %x
", key)

Principle: Always use crypto/rand for keys, IVs, nonces, and salts.

3. Symmetric Encryption – Proper AES Usage

❌ Bad AES‑CBC with custom HMAC

func EncryptCBCWithBadHMAC(key, data []byte) ([]byte, error) {
    block, _ := aes.NewCipher(key[:32]) // AES‑256
    iv := make([]byte, aes.BlockSize)
    rand.Read(iv)
    // CBC encryption
    mode := cipher.NewCBCEncrypter(block, iv)
    padded := pkcs7Pad(data, aes.BlockSize)
    ciphertext := make([]byte, len(padded))
    mode.CryptBlocks(ciphertext, padded)
    // ❌ HMAC does NOT cover IV
    mac := hmac.New(sha256.New, key[32:])
    mac.Write(ciphertext)
    tag := mac.Sum(nil)
    return append(append(iv, ciphertext...), tag...), nil
}

Problems: HMAC does not protect the IV, making the first block vulnerable; implementation is complex and prone to errors; CBC is susceptible to padding‑oracle attacks.

✅ Correct AES‑CBC with full HMAC

func EncryptCBCWithHMAC(keyEnc, keyMac, data []byte) ([]byte, error) {
    block, _ := aes.NewCipher(keyEnc)
    iv := make([]byte, aes.BlockSize)
    rand.Read(iv)
    mode := cipher.NewCBCEncrypter(block, iv)
    padded := pkcs7Pad(data, aes.BlockSize)
    ciphertext := make([]byte, len(padded))
    mode.CryptBlocks(ciphertext, padded)
    // ✅ HMAC covers IV + ciphertext
    mac := hmac.New(sha256.New, keyMac)
    mac.Write(iv)
    mac.Write(ciphertext)
    tag := mac.Sum(nil)
    return append(append(iv, ciphertext...), tag...), nil
}

Decryption steps: verify integrity with hmac.Equal, then decrypt with CBC and remove PKCS#7 padding. Recommendation: Use AES‑GCM, which provides built‑in authentication.

AES‑GCM Example

block, _ := aes.NewCipher(key)
gcm, _ := cipher.NewGCM(block)
nonce := make([]byte, gcm.NonceSize())
rand.Read(nonce)
ciphertext := gcm.Seal(nonce, nonce, []byte("hello world"), nil)
// Decrypt
nonce, data := ciphertext[:gcm.NonceSize()], ciphertext[gcm.NonceSize():]
plaintext, _ := gcm.Open(nil, nonce, data, nil)

Advantage: One‑step encryption + integrity, eliminates many pitfalls.

4. Asymmetric Encryption – RSA, ECC & Ed25519

RSA Example (OAEP & PSS)

ciphertext, _ := rsa.EncryptOAEP(sha256.New(), rand.Reader, pub, data, nil)
sig, _ := rsa.SignPSS(rand.Reader, priv, crypto.SHA256, hash[:], nil)

Tip: Use OAEP for encryption and PSS for signatures.

Ed25519 Example

pub, priv, _ := ed25519.GenerateKey(rand.Reader)
msg := []byte("hello")
sig := ed25519.Sign(priv, msg)
ok := ed25519.Verify(pub, msg, sig)

Advantage: Simple, efficient, and hard to misuse.

5. Hashes & Message Authentication

Simple SHA‑256 hash:

sum := sha256.Sum256([]byte("hello"))

HMAC creation and verification:

mac := hmac.New(sha256.New, key)
mac.Write([]byte("hello"))
tag := mac.Sum(nil)
// Compare safely
if hmac.Equal(tag, expected) { /* ok */ }

6. Password‑Derived Keys & Secure Storage

PBKDF2 example (120 000 iterations, 32‑byte key):

salt := make([]byte, 16)
rand.Read(salt)
key := pbkdf2.Key([]byte("password123"), salt, 120000, 32, sha256.New)

Argon2id example:

key := argon2.IDKey([]byte("password123"), salt, 3, 64*1024, 4, 32)

Tip: Never store raw password hashes; always use a salt and a KDF.

7. Common Pitfalls & Defensive Techniques

Wrong: math/rand for keys → Correct: crypto/rand Wrong: RSA PKCS#1 v1.5 padding → Correct: RSA‑OAEP / PSS

Wrong: Direct == comparison of keys → Correct: hmac.Equal Wrong: Reusing AES‑GCM nonce → Correct: Generate a fresh random nonce each encryption

Wrong: Hard‑coded keys → Correct: Use Vault/KMS or environment variables

8. Real‑World Case: File Encryption Tool

func EncryptFile(path, password string) []byte {
    salt := make([]byte, 16)
    rand.Read(salt)
    key := pbkdf2.Key([]byte(password), salt, 120000, 32, sha256.New)
    block, _ := aes.NewCipher(key)
    gcm, _ := cipher.NewGCM(block)
    nonce := make([]byte, gcm.NonceSize())
    rand.Read(nonce)
    data, _ := os.ReadFile(path)
    ciphertext := gcm.Seal(nonce, nonce, data, nil)
    // Return format: salt || nonce || ciphertext
    return append(salt, ciphertext...)
}

9. Advanced Techniques: API Design & Performance

Expose only high‑level Encrypt / Decrypt functions; hide nonce/salt handling internally.

Use cipher.Stream for large files to avoid loading entire file into memory.

AES‑NI hardware acceleration is automatically used by Go; on multi‑core CPUs AES‑GCM achieves very high throughput.

10. Testing & Verification

Validate implementations against NIST test vectors.

Apply fuzz testing to encryption functions to catch edge‑case crashes.

Test that incorrect passwords or tampered ciphertext produce proper errors.

11. Summary

Generate secure random numbers with crypto/rand.

Prefer AES‑GCM over AES‑CBC+HMAC for simplicity and security.

Use modern asymmetric schemes: Ed25519, RSA‑OAEP/PSS.

Combine SHA‑2/SHA‑3 with HMAC for integrity.

Derive password keys with PBKDF2 or Argon2id, always with a salt.

Encapsulate cryptographic APIs to reduce misuse.

Verify implementations with NIST vectors and fuzz tests.

12. Performance Comparison: AES‑CBC+HMAC vs AES‑GCM

Benchmark code:

func BenchmarkAESGCM(b *testing.B) {
    key := make([]byte, 32)
    rand.Read(key)
    block, _ := aes.NewCipher(key)
    gcm, _ := cipher.NewGCM(block)
    nonce := make([]byte, gcm.NonceSize())
    rand.Read(nonce)
    plaintext := make([]byte, 1<<20) // 1 MB
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        _ = gcm.Seal(nil, nonce, plaintext, nil)
    }
}

func BenchmarkAESCBC_HMAC(b *testing.B) {
    keyEnc := make([]byte, 32)
    keyMac := make([]byte, 32)
    rand.Read(keyEnc)
    rand.Read(keyMac)
    block, _ := aes.NewCipher(keyEnc)
    iv := make([]byte, aes.BlockSize)
    rand.Read(iv)
    plaintext := make([]byte, 1<<20) // 1 MB
    padded := pkcs7Pad(plaintext, aes.BlockSize)
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        mode := cipher.NewCBCEncrypter(block, iv)
        ciphertext := make([]byte, len(padded))
        mode.CryptBlocks(ciphertext, padded)
        mac := hmac.New(sha256.New, keyMac)
        mac.Write(iv)
        mac.Write(ciphertext)
        _ = mac.Sum(nil)
    }
}

Run with go test -bench .. Results show AES‑GCM achieving hundreds of MB/s to GB/s on modern CPUs, while AES‑CBC+HMAC is considerably slower and more error‑prone.

Conclusion: AES‑GCM is the preferred choice for production Go applications.