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

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 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)

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, 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

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 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

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 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

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 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 handles asymmetric encryption for small payloads and key transport scenarios.
• Curve25519 (X25519) in security/ecdh/curve25519.go enables ECDH key agreement to derive shared secrets without transmitting private material.
• Ed25519 in 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, 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 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 is strictly for ECDH key agreement, while Ed25519 in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}