# Cryptographic Algorithms Supported by Fabrica-Util's Security Package: A Complete Guide

> Explore cryptographic algorithms in fabrica-util like AES-GCM, RSA-PKCS#1 v1.5, Curve25519, and Ed25519 for secure Go applications. Understand authenticated encryption, key exchange, and digital signatures.

- Repository: [Pantheon/fabrica-util](https://github.com/go-pantheon/fabrica-util)
- Tags: deep-dive
- Published: 2026-03-02

---

**Fabrica-util's security package provides four modern cryptographic primitives—AES-GCM, RSA-PKCS#1 v1.5, Curve25519 ECDH, and Ed25519—that enable authenticated encryption, asymmetric key exchange, and digital signatures for Go applications.**

The `go-pantheon/fabrica-util` repository delivers a streamlined **security** package designed for developers who need battle-tested cryptographic operations without external dependencies beyond Go's standard library. Each algorithm is encapsulated in dedicated sub-packages with consistent error handling via the repository's custom `errors` package, providing clear abstraction layers for confidential data protection, secure key agreement, and entity authentication.

## AES-GCM for Authenticated Encryption

The **AES-GCM** implementation in [`security/aes/aes.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/aes/aes.go) provides authenticated encryption with associated data (AEAD), ensuring both confidentiality and integrity for stored or transmitted data.

### Implementation Details

The `Cipher` type wraps Go's standard `crypto/aes` and `crypto/cipher` packages to create a 128-bit, 192-bit, or 256-bit AES block cipher (accepting 16, 24, or 32-byte keys). It instantiates Galois/Counter Mode (GCM) via `cipher.NewGCM`, exposing `Encrypt` and `Decrypt` methods. The implementation includes "allow-empty" variants that return the original slice when input is empty, preventing unnecessary allocations for nullable data fields.

### Use Cases

- **Database field encryption** for PII or credentials requiring integrity verification
- **Token encryption** where ciphertext tampering must be detectable
- **Secure transport** of messages up to several gigabytes (GCM's design limits)

```go
package main

import (
	"fmt"
	"log"

	"github.com/go-pantheon/fabrica-util/security/aes"
)

func main() {
	key := []byte("0123456789ABCDEF0123456789ABCDEF") // 32‑byte (AES‑256) key
	c, err := aes.NewAESCipher(key)
	if err != nil {
		log.Fatalf("cipher init: %v", err)
	}

	plaintext := []byte("Sensitive payload")
	ciphertext, err := c.Encrypt(plaintext)
	if err != nil {
		log.Fatalf("encrypt: %v", err)
	}
	fmt.Printf("ciphertext (hex): %x\n", ciphertext)

	// Decrypt back
	dec, err := c.Decrypt(ciphertext)
	if err != nil {
		log.Fatalf("decrypt: %v", err)
	}
	fmt.Printf("decrypted: %s\n", dec)
}

```

## RSA Encryption and Decryption

Located in [`security/rsa/rsa.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/rsa/rsa.go), the **RSA** implementation handles asymmetric encryption using the legacy but widely supported PKCS#1 v1.5 padding scheme.

### PKCS#1 v1.5 Implementation

The `Encrypt` function utilizes `rsa.EncryptPKCS1v15` with a provided public key, while `Decrypt` uses `rsa.DecryptPKCS1v15` with the matching private key. Helper utilities parse DER-encoded PKIX public keys and PKCS#1/PKCS#8 private keys, abstracting the complexity of `crypto/x509` and `encoding/pem` operations.

### When to Use RSA

- **Key transport** of small payloads such as AES session keys or access tokens
- **Legacy system compatibility** where PKCS#1 v1.5 is mandatory
- **Simple data exchange** scenarios requiring public-key cryptography without ECDH infrastructure

```go
package main

import (
	"crypto/rand"
	"crypto/rsa"
	"log"

	rsautil "github.com/go-pantheon/fabrica-util/security/rsa"
)

func main() {
	// Generate a temporary RSA key pair for demo
	priv, _ := rsa.GenerateKey(rand.Reader, 2048)
	pub := &priv.PublicKey

	plain := []byte("Hello RSA")
	cipher, err := rsautil.Encrypt(pub, plain)
	if err != nil {
		log.Fatalf("RSA encrypt: %v", err)
	}

	dec, err := rsautil.Decrypt(priv, cipher)
	if err != nil {
		log.Fatalf("RSA decrypt: %v", err)
	}
	log.Printf("Decrypted: %s", dec)
}

```

## Curve25519 for Elliptic Curve Diffie-Hellman

The **Curve25519 (X25519)** implementation in [`security/ecdh/curve25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/ecdh/curve25519.go) enables high-performance ECDH key agreement for establishing shared secrets without transmitting the key itself.

### X25519 Key Agreement

`GenKeyPair` generates a cryptographically secure random 32-byte private scalar and derives the corresponding public key using `curve25519.ScalarBaseMult`. The `ComputeSharedKey` function performs the X25519 scalar multiplication to derive an identical shared secret on both endpoints, suitable for seeding symmetric algorithms like AES-GCM.

### ECDH Use Cases

- **Session key establishment** in TLS-like handshake simulations
- **End-to-end encryption** where two parties need a shared secret without prior key distribution
- **Perfect forward secrecy** implementations requiring ephemeral key exchanges

```go
package main

import (
	"log"

	"github.com/go-pantheon/fabrica-util/security/ecdh"
)

func main() {
	// Alice's key pair
	aliPri, aliPub, _ := ecdh.GenKeyPair()
	// Bob's key pair
	bobPri, bobPub, _ := ecdh.GenKeyPair()

	// Both compute the same shared secret
	secret1, _ := ecdh.ComputeSharedKey(aliPri, bobPub)
	secret2, _ := ecdh.ComputeSharedKey(bobPri, aliPub)

	if string(secret1) != string(secret2) {
		log.Fatalf("shared secret mismatch")
	}
	log.Printf("shared secret (hex): %x", secret1)
}

```

## Ed25519 Signatures and X.509 Certificates

The [`security/certificate/ed25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/certificate/ed25519.go) file bundles **Ed25519** elliptic curve signature functionality with X.509 certificate utilities for cryptographic identity verification.

### Digital Signatures and Certificate Management

`GenKeyPair` creates Ed25519 key pairs compatible with Go's `crypto/ed25519` package. The `Sign` and `Verify` methods handle raw signature operations using 64-byte signatures. Additional helpers include `CreateSelfSignedCert` for generating X.509 v3 certificates valid for a specified duration (in days), plus PEM/DER conversion utilities for key serialization and certificate lifecycle validation.

### Authentication Workflows

- **API request signing** for non-repudiation and integrity verification
- **Self-signed certificate generation** for TLS development environments or mTLS service meshes
- **Document signing** requiring compact, high-security 128-bit security level signatures

```go
package main

import (
	"log"

	"github.com/go-pantheon/fabrica-util/security/certificate"
)

func main() {
	// Generate an Ed25519 key pair
	kp, _ := certificate.GenKeyPair()

	// Sign a message
	msg := "Important data"
	sig, _ := certificate.Sign(kp.Pri, []byte(msg))

	// Verify the signature
	if !certificate.Verify(kp.Pub, []byte(msg), sig.Sign) {
		log.Fatalf("signature verification failed")
	}
	log.Println("Signature OK")

	// Create a self‑signed X.509 certificate valid for 365 days
	cert, _ := certificate.CreateSelfSignedCert(
		// Subject details
		certificate.Subject{
			CommonName:   "demo.example.com",
			Organization: []string{"Demo Corp"},
		},
		365,
	)
	log.Printf("Generated certificate PEM:\n%s", cert.CertPEM)
}

```

## Summary

- **AES-GCM** in [`security/aes/aes.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/aes/aes.go) provides authenticated symmetric encryption for data confidentiality and integrity using 128/192/256-bit keys.
- **RSA-PKCS#1 v1.5** in [`security/rsa/rsa.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/rsa/rsa.go) handles asymmetric encryption for small payloads and key transport scenarios.
- **Curve25519 (X25519)** in [`security/ecdh/curve25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/ecdh/curve25519.go) enables ECDH key agreement to derive shared secrets without transmitting private material.
- **Ed25519** in [`security/certificate/ed25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/certificate/ed25519.go) offers high-performance digital signatures and self-signed X.509 certificate generation for entity authentication.

## Frequently Asked Questions

### What is the primary use case for AES-GCM in fabrica-util?

AES-GCM is designed for **authenticated encryption** where both data confidentiality and tamper detection are required. According to the source code in [`security/aes/aes.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/aes/aes.go), it is ideal for encrypting database fields, session tokens, or transport payloads where any modification to the ciphertext must be immediately detectable during decryption.

### How does the RSA implementation handle key parsing?

The RSA utilities in [`security/rsa/rsa.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/rsa/rsa.go) automatically parse DER-encoded PKIX public keys and PKCS#1/PKCS#8 private keys through helper functions. These abstractions eliminate the need to manually handle `encoding/pem` and `crypto/x509` boilerplate when loading keys from files or byte slices.

### Can Curve25519 and Ed25519 keys be used interchangeably?

**No.** Curve25519 (X25519) and Ed25519 use different elliptic curve scalar multiplication functions and serve distinct purposes. X25519 in [`security/ecdh/curve25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/ecdh/curve25519.go) is strictly for ECDH key agreement, while Ed25519 in [`security/certificate/ed25519.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/certificate/ed25519.go) is for digital signatures. The private key formats differ and are not compatible between the two algorithms.

### Does the security package support RSA-OAEP padding?

The current implementation in [`security/rsa/rsa.go`](https://github.com/go-pantheon/fabrica-util/blob/main/security/rsa/rsa.go) exclusively supports **PKCS#1 v1.5** padding via `rsa.EncryptPKCS1v15` and `rsa.DecryptPKCS1v15`. RSA-OAEP is not implemented in the current codebase, meaning developers requiring OAEP must extend the package or use Go's standard library directly.