README
¶
Go - Advanced Encryption Standard (AES)
Secure and easy-to-use Go library that provides AES helpers with a focus on compliance with NIST standards (SP 800-38 series).
Features
- AES-GCM (Authenticated Encryption) - Highly Recommended
- AES-XTS (XEX-based-tweaked-codebook-mode with ciphertext stealing) - For Disk Encryption
- AES-CBC, AES-CFB, AES-OFB, AES-CTR (Confidentiality modes)
- AES-ECB (Included for legacy compatibility, use with caution)
- Secure key and nonce generation using
crypto/rand. - Helpers for Base64 and Hex encoding.
- PKCS#7 padding implemented for block modes.
NIST Compliance (SP 800-38 Series)
This library is designed following NIST recommendations:
- Authenticated Encryption (SP 800-38D): AES-GCM is the preferred choice for most applications as it provides both confidentiality and data integrity (AEAD).
- Key Size: Always prefer 256-bit (32-byte) keys for maximum security and post-quantum resistance.
- Data-at-Rest (SP 800-38E): AES-XTS is the standard for disk and storage encryption.
- Legacy Modes (SP 800-38A): CBC, CFB, CTR, and OFB provide confidentiality only. If you use these, you should implement a separate Message Authentication Code (HMAC) to ensure integrity.
- Insecure Mode: AES-ECB is insecure for data larger than one block. Use it only for single-block operations or legacy system interoperability.
Installation
go get github.com/fawwazid/go-aes@latest
Quick Start
AES-GCM (Recommended)
package main
import (
"fmt"
"log"
goaes "github.com/fawwazid/go-aes"
)
func main() {
// Generate a secure 256-bit key
key, err := goaes.GenerateAESKey(256)
if err != nil {
log.Fatal(err)
}
plaintext := []byte("secret message for AES-GCM")
// Encrypt (nonce is automatically generated and prepended)
ciphertext, err := goaes.EncryptGCM(key, plaintext, nil)
if err != nil {
log.Fatal(err)
}
// Decrypt
decrypted, err := goaes.DecryptGCM(key, ciphertext, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(decrypted))
}
API Overview
Encryption / Decryption
| Mode | Encryption | Decryption | Note |
|---|---|---|---|
| GCM | EncryptGCM(key, pt, aad) |
DecryptGCM(key, ct, aad) |
Recommended (AEAD) |
| XTS | EncryptXTS(key, pt, sector) |
DecryptXTS(key, ct, sector) |
For Disk/Storage |
| CBC | EncryptCBC(key, pt) |
DecryptCBC(key, ct) |
Confidentiality only |
| CFB | EncryptCFB(key, pt) |
DecryptCFB(key, ct) |
Confidentiality only |
| CTR | EncryptCTR(key, pt) |
DecryptCTR(key, ct) |
Confidentiality only |
| OFB | EncryptOFB(key, pt) |
DecryptOFB(key, ct) |
Confidentiality only |
| ECB | EncryptECB(key, pt) |
DecryptECB(key, ct) |
Insecure |
Utilities
GenerateAESKey(bits): Generate a random key (128, 192, or 256 bits).GenerateNonce(size): Generate a random nonce.EncodeBase64(data)/DecodeBase64(string): Base64 helpers.HexEncode(data)/HexDecode(string): Hex helpers.
Running Tests
go test -v ./...
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Index ¶
- func DecodeBase64(s string) ([]byte, error)
- func DecryptCBC(key, ciphertext []byte) ([]byte, error)
- func DecryptCFB(key, ciphertext []byte) ([]byte, error)
- func DecryptCTR(key, ciphertext []byte) ([]byte, error)
- func DecryptECB(key, ciphertext []byte) ([]byte, error)
- func DecryptGCM(key, ciphertext, aad []byte) ([]byte, error)
- func DecryptOFB(key, ciphertext []byte) ([]byte, error)
- func DecryptXTS(key, ciphertext []byte, sectorNum uint64) ([]byte, error)
- func EncodeBase64(b []byte) string
- func EncryptCBC(key, plaintext []byte) ([]byte, error)
- func EncryptCFB(key, plaintext []byte) ([]byte, error)
- func EncryptCTR(key, plaintext []byte) ([]byte, error)
- func EncryptECB(key, plaintext []byte) ([]byte, error)
- func EncryptGCM(key, plaintext, aad []byte) ([]byte, error)
- func EncryptOFB(key, plaintext []byte) ([]byte, error)
- func EncryptXTS(key, plaintext []byte, sectorNum uint64) ([]byte, error)
- func GenerateAESKey(bits int) ([]byte, error)
- func GenerateKey(size int) ([]byte, error)
- func GenerateNonce(size int) ([]byte, error)
- func GenerateRandomBytes(n int) ([]byte, error)
- func GenerateXTSKeyForAES(bits int) ([]byte, error)
- func HexDecode(s string) ([]byte, error)
- func HexEncode(b []byte) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeBase64 ¶
DecodeBase64 decodes a Base64 string into bytes.
func DecryptCBC ¶
DecryptCBC decrypts data produced by EncryptCBC. It expects the IV to be prepended to the ciphertext.
Parameters:
- key: same key used for encryption.
- ciphertext: iv||ciphertext.
Returns: decrypted plaintext (unpadded).
func DecryptCFB ¶
DecryptCFB decrypts data produced by EncryptCFB. It expects the IV to be prepended to the ciphertext.
Parameters:
- key: same key used for encryption.
- ciphertext: iv||ciphertext.
Returns: decrypted plaintext.
func DecryptCTR ¶
DecryptCTR decrypts data produced by EncryptCTR. It expects the IV to be prepended to the ciphertext.
Parameters:
- key: same key used for encryption.
- ciphertext: iv||ciphertext.
Returns: decrypted plaintext.
func DecryptECB ¶
DecryptECB decrypts ciphertext produced by EncryptECB and removes PKCS#7 padding.
Parameters:
- key: same key used for encryption.
- ciphertext: Data to be decrypted.
Returns: decrypted plaintext (unpadded).
func DecryptGCM ¶
DecryptGCM decrypts data produced by EncryptGCM. It expects the nonce to be prepended to the ciphertext.
Parameters:
- key: same key used for encryption.
- ciphertext: nonce||ciphertext.
- aad: same additional data used for encryption.
Returns: decrypted plaintext.
func DecryptOFB ¶
DecryptOFB decrypts data produced by EncryptOFB. It expects the IV to be prepended to the ciphertext.
Parameters:
- key: same key used for encryption.
- ciphertext: iv||ciphertext.
Returns: decrypted plaintext.
func DecryptXTS ¶
DecryptXTS decrypts ciphertext produced by EncryptXTS.
Parameters:
- key: same key used for encryption.
- ciphertext: Data to be decrypted.
- sectorNum: same sector number used for encryption.
Returns: decrypted plaintext.
func EncodeBase64 ¶
EncodeBase64 returns a Base64 encoding of the input bytes.
func EncryptCBC ¶
EncryptCBC encrypts plaintext using AES-CBC with PKCS#7 padding.
NIST SP 800-38A Warning: This mode provides Confidentiality ONLY. It DOES NOT provide integrity or authenticity. Vulnerable to Padding Oracle attacks if not implemented with constant-time MAC.
Recommendation: Use EncryptGCM (AEAD) instead for better security.
Parameters:
- key: 16, 24, or 32 bytes (AES-128, 192, or 256).
- plaintext: Data to be encrypted.
Returns: IV prepended to ciphertext (iv||ciphertext).
func EncryptCFB ¶
EncryptCFB encrypts plaintext using AES in CFB mode.
NIST SP 800-38A Warning: This mode provides Confidentiality ONLY. It is malleable: bit-flipping attacks on ciphertext will change plaintext predictably.
Recommendation: Use EncryptGCM (AEAD) instead.
Parameters:
- key: 16, 24, or 32 bytes (AES-128, 192, or 256).
- plaintext: Data to be encrypted.
Returns: IV prepended to ciphertext (iv||ciphertext).
func EncryptCTR ¶
EncryptCTR encrypts plaintext using AES in CTR mode (Counter Mode).
NIST SP 800-38A Warning: This mode provides Confidentiality ONLY. It is malleable: bit-flipping attacks on ciphertext will directly flip bits in plaintext. NEVER reuse a (Key, IV) pair.
Recommendation: Use EncryptGCM (AEAD) instead.
Parameters:
- key: 16, 24, or 32 bytes (AES-128, 192, or 256).
- plaintext: Data to be encrypted.
Returns: IV prepended to ciphertext (iv||ciphertext).
func EncryptECB ¶
EncryptECB encrypts plaintext using AES in ECB mode with PKCS#7 padding.
NIST SP 800-38A Warning: INSECURE MODE. Do NOT use for data larger than one block. Patterns in plaintext remain visible in ciphertext. This mode is provided for legacy compatibility only.
Recommendation: Use EncryptGCM (AEAD) instead.
Parameters:
- key: 16, 24, or 32 bytes (AES-128, 192, or 256).
- plaintext: Data to be encrypted.
Returns: ciphertext (no IV used in ECB).
func EncryptGCM ¶
EncryptGCM encrypts plaintext using AES-GCM (Galois/Counter Mode).
NIST SP 800-38D Recommendation: Authenticated Encryption (AEAD). This mode provides both confidentiality and authenticity (AEAD).
Parameters:
- key: 16/24/32 bytes (AES-128/192/256). Use 32 bytes for top security.
- plaintext: Data to be encrypted.
- aad: Additional Authenticated Data (optional, can be nil). PROOF of integrity, not encrypted.
Returns: nonce||ciphertext
func EncryptOFB ¶
EncryptOFB encrypts plaintext using AES in OFB mode (Output Feedback).
NIST SP 800-38A Warning: This mode provides Confidentiality ONLY.
Recommendation: Use EncryptGCM (AEAD) instead.
Parameters:
- key: 16, 24, or 32 bytes (AES-128, 192, or 256).
- plaintext: Data to be encrypted.
Returns: IV prepended to ciphertext (iv||ciphertext).
func EncryptXTS ¶
EncryptXTS encrypts plaintext using AES-XTS.
NIST SP 800-38E Recommendation: Approved for Storage Devices (Data-at-Rest) ONLY. NOT intended for General Purpose encryption or Data-in-Transit.
Parameters:
- key: twice the length of the underlying AES key (32, 48 or 64 bytes).
- plaintext: Data to be encrypted (must be multiple of 16 bytes).
- sectorNum: the tweak (typically the sector or block number).
Returns: ciphertext.
func GenerateAESKey ¶
GenerateAESKey creates an AES key of the specified bit length (128, 192, 256).
NIST SP 800-57 Recommendation: Use bits=256 for top-secret data or long-term protection.
func GenerateKey ¶
GenerateKey returns a random key of the specified byte length. Allowed AES key lengths are 16 (AES-128), 24 (AES-192), or 32 (AES-256) bytes.
NIST SP 800-57 Recommendation: Use 32 bytes (AES-256) for long-term security and post-quantum resistance.
func GenerateNonce ¶
GenerateNonce returns a random nonce of the given size in bytes. If size is 0, it returns a 12-byte nonce (recommended for GCM).
func GenerateRandomBytes ¶
GenerateRandomBytes returns securely-generated random bytes of length n. It is a thin wrapper over crypto/rand.
func GenerateXTSKeyForAES ¶
GenerateXTSKeyForAES generates a combined XTS key for AES-XTS. `bits` is the AES key size in bits (128, 192, 256). The returned key length will be twice the AES key length (32, 48, 64 bytes).
Types ¶
This section is empty.
Source Files