gitlab.com/omnifi/automaatio/cryptography.git

Automaatio Cryptography

A minimal set of secure cryptographic functions designed to reduce repetitive code in automation projects. This package provides digital signature operations, SSH key management, and certificate handling with proper security controls and error handling, focusing on common cryptographic use cases.

Important note: This is not intended as a comprehensive cryptography replacement library. It provides a curated set of convenience functions that will be extended over time based on actual project needs.

Purpose

This package eliminates common patterns that appear across automation projects:

• Secure SSH key generation and format conversion
• Digital signature creation and verification with multiple algorithms
• Certificate authority operations for self-sovereign infrastructure
• Cryptographically secure random number generation

Features

Core cryptographic operations

• Ed25519 key generation with built-in validation and testing
• ECDSA key generation supporting P-224, P-256, P-384, and P-521 curves
• SSH key format conversion with OpenSSH compatibility
• Digital signature operations for data integrity verification

SSH key management

• Ed25519 SSH key generation with proper OpenSSH format marshaling
• ECDSA SSH key generation with configurable curve selection
• Key validation ensuring generated keys are functional
• Format conversion between cryptographic and SSH formats

Security features

• Cryptographically secure randomness using crypto/rand for all operations
• Comprehensive error handling with detailed error context
• Side-channel resistance through proper algorithm selection
• Input validation on all cryptographic parameters

Installation

go get git.omnifi.foundation/automaatio/cryptography

Quick start

Ed25519 key generation

package main

import (
    "log"
    
    "git.omnifi.foundation/automaatio/cryptography/signatures"
    "git.omnifi.foundation/automaatio/cryptography/ssh"
)

func main() {
    // Generate Ed25519 cryptographic key pair
    publicKey, privateKey, err := signatures.GenerateEd25519Keys()
    if err != nil {
        log.Fatal(err)
    }
    
    // Convert to SSH format for use with SSH clients
    sshPublicKey, sshPrivateKey, err := ssh.GenerateEd25519KeysForSSH(&privateKey)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Generated Ed25519 key pair for SSH use")
}

ECDSA key generation with curve selection

package main

import (
    "log"
    
    "git.omnifi.foundation/automaatio/cryptography/signatures"
    "git.omnifi.foundation/automaatio/cryptography/ssh"
)

func main() {
    // Generate P-384 ECDSA key (recommended for high security)
    ecdsaPrivateKey, err := signatures.GenerateECDSAKeys(384)
    if err != nil {
        log.Fatal(err)
    }
    
    // Convert to SSH format
    publicKeyString, privateKeyString, err := ssh.GenerateECDSAKeysForSSH(ecdsaPrivateKey)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Generated P-384 ECDSA key pair for SSH use")
}

API reference

Signatures package functions

GenerateEd25519Keys() (ed25519.PublicKey, ed25519.PrivateKey, error)

Creates a new Ed25519 cryptographic key pair with built-in validation.

GenerateECDSAKeys(bitSize int) (*ecdsa.PrivateKey, error)

Creates a new ECDSA key pair using the specified curve size (224, 256, 384, or 521 bits).

SSH package functions

GenerateEd25519KeysForSSH(privateKey *ed25519.PrivateKey) ([]byte, []byte, error)

Converts Ed25519 keys to OpenSSH format for use with SSH clients and servers.

GenerateECDSAKeysForSSH(privateKey *ecdsa.PrivateKey) (string, string, error)

Converts ECDSA keys to SSH format with proper PEM encoding.

Error handling

All functions return detailed error information through Go's standard error interface with contextual information:

• Functions validate input parameters and return errors for invalid configurations
• Cryptographic operations include error checking at each step
• Key generation includes validation to ensure generated keys are functional

Each error includes context about the operation that failed and the underlying cause.

Security considerations

• All key generation uses crypto/rand for cryptographically secure randomness
• Ed25519 is recommended for new applications due to security and performance
• ECDSA curve selection affects security level (P-384 recommended minimum)
• Private keys must be kept confidential and stored securely
• Consider hardware security modules for high-value private keys

Performance

The library includes comprehensive benchmarks for all operations:

# Run performance benchmarks
go test -bench=. ./...

Typical performance characteristics:

• Ed25519 key generation: ~1-2ms per key pair
• ECDSA key generation: ~5-50ms depending on curve size
• SSH format conversion: ~1ms for Ed25519, ~2-5ms for ECDSA
• All operations are suitable for automated workflows

Testing

Run the complete test suite:

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

# Run benchmarks
go test -bench=. ./...

The package includes:

• Unit tests for all public functions
• Validation tests ensuring generated keys work correctly
• Error handling tests for failure scenarios
• Performance benchmarks for all operations

Building

Building the basic binary can be achieved by the simple go build command:

go build -o .bin/ ./...

Cross-platform builds:

go generate ./... && \
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o .bin/darwin-amd64/ ./... && \
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o .bin/darwin-arm64/ ./... && \
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o .bin/linux-amd64/ ./... && \
CGO_ENABLED=0 GOOS=linux GOARCH=arm go build -o .bin/linux-arm/ ./... && \
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o .bin/linux-arm64/ ./... && \
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o .bin/windows-amd64/ ./... && \
CGO_ENABLED=0 GOOS=windows GOARCH=arm go build -o .bin/windows-arm/ ./...

Code quality

Formatting:

go fmt ./...

Linting:

go vet ./...

Requirements

• Go 1.25 or later
• No external dependencies beyond Go standard library and golang.org/x/crypto

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the LICENSE.txt file for complete license terms.

Contributing

This package follows strict code quality standards:

• Verbose comments and documentation
• No abbreviations in variable or function names
• Comprehensive error handling
• Security-first approach to all operations

Development philosophy

This package prioritizes:

• Minimal scope: Only includes functions that solve real, recurring problems
• Security by default: All operations use secure configurations and cryptographically secure randomness
• Gradual expansion: New functions are added based on actual project needs
• Consistency: All functions follow the same patterns for error handling and security

Roadmap

This library will expand gradually based on actual usage patterns in automation projects. Potential future additions may include:

• Certificate authority operations for PKI management
• File signing and verification capabilities
• Key derivation functions (PBKDF2, Argon2id, scrypt)
• Symmetric encryption utilities (AES-256-GCM)
• Hardware security module integration