encrypt

README

GoForge Encrypt

encrypt is the standalone cryptography module for GoForge. It exposes a repository-style API for symmetric encryption, hashing, RSA/ECC helpers, and digital signatures, with interchangeable local and cloud-backed implementations.

Installation

go get github.com/PointerByte/GoForge/encrypt

Update the dependencies used by the current module:

go get -u ./...

Packages

• github.com/PointerByte/GoForge/encrypt: shared interfaces and composite repository wrapper
• github.com/PointerByte/GoForge/encrypt/local: in-process cryptography
• github.com/PointerByte/GoForge/encrypt/aws-kms: AWS KMS-backed operations with local fallback paths
• github.com/PointerByte/GoForge/encrypt/azure-key-vault: Azure Key Vault-backed operations with local fallback paths
• github.com/PointerByte/GoForge/encrypt/gcp-kms: Google Cloud KMS-backed operations with local fallback paths

Capabilities

• AES-GCM encryption and decryption
• HMAC-SHA256 generation
• SHA-256 and BLAKE3 hashing
• RSA key generation and RSA-OAEP encryption/decryption
• ECC key generation and ECDH-derived encryption/decryption
• Ed25519 signing and verification
• RSA-PSS and RSA PKCS#1 v1.5 SHA-256 signing and verification
• context-aware APIs for cancellation and deadlines

Repository Model

The root package exposes focused interfaces:

• SymmetricRepository
• AsymmetricRepository
• HashRepository
• SignatureRepository
• IRepository, which combines all of them

Use encrypt.NewRepository(...) when you want one value that exposes every capability from a backend implementation:

repository := encrypt.NewRepository(local.NewRepository())

Backend packages also expose their own NewRepository() constructors:

localRepository := local.NewRepository()
awsRepository := awskms.NewRepository()
azureRepository := azurekeyvault.NewRepository()
gcpRepository := gcpkms.NewRepository()

_, _, _, _ = localRepository, awsRepository, azureRepository, gcpRepository

Key Data

Key-generation methods return *models.KeyData:

• KeyID: local private key, symmetric key, or provider key identifier
• PublicKey: local public key when exportable
• KeyRef: provider-specific reference such as ARN, URL, or version name
• Provider: backend name, for example local, aws-kms, azure-key-vault, or gcp-kms

For local symmetric keys, use KeyID as the AES key. For local asymmetric keys, use KeyID as the private key and PublicKey as the public key.

Quick Start

package main

import (
	"context"

	"github.com/PointerByte/GoForge/encrypt"
	"github.com/PointerByte/GoForge/encrypt/common"
	"github.com/PointerByte/GoForge/encrypt/local"
)

func main() {
	ctx := context.Background()
	repository := encrypt.NewRepository(local.NewRepository())

	keyData, err := repository.GenerateSymetrycKeys(ctx, common.Key256Bits)
	if err != nil {
		panic(err)
	}

	additional := "aad"
	cipherText, err := repository.EncryptAES(ctx, keyData.KeyID, "hello", &additional)
	if err != nil {
		panic(err)
	}

	plainText, err := repository.DecryptAES(ctx, keyData.KeyID, cipherText, &additional)
	if err != nil {
		panic(err)
	}

	_ = plainText
}

Hashing And HMAC

hmacValue := repository.HMAC(ctx, "secret", "message")
sha256Value := repository.Sha256Hex(ctx, "message")
blake3Value := repository.Blake3(ctx, "message")

_, _, _ = hmacValue, sha256Value, blake3Value

RSA

keys, err := repository.GenerateRSAKeys(ctx, common.Key2048Bits)
if err != nil {
	panic(err)
}

cipherText, err := repository.RSA_OAEP_Encode(ctx, keys.PublicKey, "hello")
if err != nil {
	panic(err)
}

plainText, err := repository.RSA_OAEP_Decode(ctx, keys.KeyID, cipherText)
if err != nil {
	panic(err)
}

signature, err := repository.SignRSAPSS(ctx, keys.KeyID, "payload")
if err != nil {
	panic(err)
}

if err := repository.VerifyRSAPSS(ctx, keys.PublicKey, "payload", signature); err != nil {
	panic(err)
}

_ = plainText

ECC

keys, err := repository.GenerateECCKeys(ctx, common.CurveP256)
if err != nil {
	panic(err)
}

cipherText, err := repository.ECC_Encode(ctx, keys.PublicKey, "hello")
if err != nil {
	panic(err)
}

plainText, err := repository.ECC_Decode(ctx, keys.KeyID, cipherText)
if err != nil {
	panic(err)
}

_ = plainText

Ed25519

keys, err := repository.GenerateEd255Keys(ctx)
if err != nil {
	panic(err)
}

signature, err := repository.SignEd25519(ctx, keys.KeyID, "payload")
if err != nil {
	panic(err)
}

if err := repository.VerifyEd25519(ctx, keys.PublicKey, "payload", signature); err != nil {
	panic(err)
}

Cloud Backends

Cloud packages implement the same repository contract and route operations to the provider when the supplied key looks like a provider reference. Explicit local keys are handled by the local fallback where supported.

import (
	awskms "github.com/PointerByte/GoForge/encrypt/aws-kms"
	azurekeyvault "github.com/PointerByte/GoForge/encrypt/azure-key-vault"
	gcpkms "github.com/PointerByte/GoForge/encrypt/gcp-kms"
)

Configuration fallback keys:

• AWS KMS: encrypt.vault.aws-kms.arn
• Azure Key Vault: encrypt.vault.azure-key-vault.key-id
• Google Cloud KMS: encrypt.vault.gcp-kms.key-id

Azure and GCP also keep compatibility fallbacks for the older encrypt.azure-key-vault.key-id and encrypt.gcp-kms.key-id keys.

Relationship With security

security depends on this module internally for JWT signing and cryptographic helpers, but encrypt is independent. Use it directly when your application needs cryptographic primitives outside JWT middleware.

Tests

From the encrypt module directory:

go test ./...
go test -cover -covermode=atomic -coverprofile=coverage.out ./...

Documentation

Overview

Package encrypt provides high-level cryptographic repositories for the security module.

The package groups helpers for:

• symmetric encryption with AES-GCM
• hashing and HMAC generation
• RSA key generation and RSA-OAEP encryption
• Ed25519 and RSA-based digital signatures

Applications can depend on the focused repository interfaces when they need only one capability, or use NewRepository to obtain a combined entry point for the main encryption services. Every operation receives a context.Context so callers can control request scope, deadlines, and cancellation across local and provider-backed implementations.

NewRepository selects its backend from viper key "encrypt.vault.mode". Supported values are:

• "local" for in-process cryptography
• "aws-kms" for AWS KMS-backed repositories
• "azure-key-vault" for Azure Key Vault-backed repositories
• "gcp-kms" for Google Cloud KMS-backed repositories

When the configuration value is empty or unsupported, NewRepository falls back to the local repository implementation.

Index

• type AsymmetricRepository
• type HashRepository
• type IRepository
• type Repository
  • func NewRepository(input IRepository) *Repository
• type SignatureRepository
• type SymmetricRepository

Types

type AsymmetricRepository

type AsymmetricRepository interface {
	// GenerateRSAKeys creates an RSA key pair and returns the encoded key
	// material plus provider metadata.
	GenerateRSAKeys(ctx context.Context, size common.SizeAsymetrycKey) (*models.KeyData, error)
	// GenerateECCKeys creates an ECC key pair on the requested curve and returns
	// the encoded key material plus provider metadata.
	GenerateECCKeys(ctx context.Context, curve common.CurveAsymmetricKey) (*models.KeyData, error)
	// RSA_OAEP_Encode encrypts plaintext with a Base64-encoded RSA public key
	// and returns the ciphertext in Base64.
	RSA_OAEP_Encode(ctx context.Context, publicKey, text string) (string, error)
	// RSA_OAEP_Decode decrypts Base64 ciphertext with a Base64-encoded RSA
	// private key.
	RSA_OAEP_Decode(ctx context.Context, privateKey, cipherText string) (string, error)
	// ECC_Encode encrypts plaintext using an ECC public key with an ECDH-derived
	// AES-GCM key and returns an encoded payload.
	ECC_Encode(ctx context.Context, publicKey, text string) (string, error)
	// ECC_Decode decrypts ciphertext produced by ECC_Encode using the matching
	// ECC private key.
	ECC_Decode(ctx context.Context, privateKey, cipherText string) (string, error)
}

AsymmetricRepository exposes RSA key generation and RSA-OAEP helpers.

type HashRepository

type HashRepository interface {
	// HMAC returns a Base64-encoded HMAC-SHA256 signature.
	HMAC(ctx context.Context, secretKey, message string) string
	// Sha256Hex returns the SHA-256 digest as a hexadecimal string.
	Sha256Hex(ctx context.Context, message string) string
	// Blake3 returns the BLAKE3 digest encoded as Base64.
	Blake3(ctx context.Context, message string) string
}

HashRepository exposes hashing and message-authentication helpers.

type IRepository

type IRepository interface {
	SymmetricRepository
	AsymmetricRepository
	HashRepository
	SignatureRepository
}

Repository groups the main encryption and signature capabilities exposed by the package in a single composite contract.

type Repository

type Repository struct {
	SymmetricRepository
	AsymmetricRepository
	SignatureRepository
	HashRepository
}

func NewRepository

func NewRepository(input IRepository) *Repository

NewRepository returns a combined repository with the main cryptographic capabilities exposed by this package using the provided implementation.

type SignatureRepository

type SignatureRepository interface {
	// GenerateEd255Keys creates an Ed25519 key pair and returns the encoded key
	// material plus provider metadata.
	GenerateEd255Keys(ctx context.Context) (*models.KeyData, error)
	// SignEd25519 signs text using a Base64-encoded Ed25519 private key and
	// returns the signature in Base64.
	SignEd25519(ctx context.Context, privateKey, text string) (string, error)
	// VerifyEd25519 validates an Ed25519 Base64 signature.
	VerifyEd25519(ctx context.Context, publicKey, text, signature string) error

	// SignRSAPSS signs text with RSA-PSS using a Base64-encoded private key and
	// returns the signature in Base64.
	SignRSAPSS(ctx context.Context, privateKey, text string) (string, error)
	// VerifyRSAPSS validates an RSA-PSS Base64 signature.
	VerifyRSAPSS(ctx context.Context, publicKey, text, signature string) error
	// Sign_RSA_PKCS1v15_SHA256 signs data with RSA PKCS#1 v1.5 using SHA-256.
	Sign_RSA_PKCS1v15_SHA256(ctx context.Context, privateKey, data string) (string, error)
	// Verify_RSA_PKCS1v15_SHA256 validates an RSA PKCS#1 v1.5 SHA-256 signature.
	Verify_RSA_PKCS1v15_SHA256(ctx context.Context, data, publicKey string, signature string) error
}

SignatureRepository exposes asymmetric signing and verification helpers.

type SymmetricRepository

type SymmetricRepository interface {
	// GenerateSymetrycKeys returns a random Base64-encoded symmetric key.
	GenerateSymetrycKeys(ctx context.Context, size common.SizeSymetrycKey) (*models.KeyData, error)

	// EncryptAES encrypts plaintext using a Base64-encoded AES key and optional
	// additional authenticated data, returning the ciphertext in Base64.
	EncryptAES(ctx context.Context, secretKey, value string, additional *string) (string, error)
	// DecryptAES decrypts Base64 ciphertext produced by EncryptAES using the
	// same Base64 AES key and optional additional authenticated data.
	DecryptAES(ctx context.Context, secretKey, cipherValue string, additional *string) (string, error)
}

SymmetricRepository exposes symmetric encryption helpers.