crypto

Common cryptographic constants and interfaces

The crypto package collects common cryptographic constants and provides core interfaces for cryptographic operations.

Overview

The crypto package provides:

• Hash function identifiers and management
• Public and private key interfaces
• Signing and verification interfaces
• Encryption and decryption interfaces
• Key encapsulation mechanism (KEM) interfaces

This package provides primitives and interfaces. For actual cryptographic implementations, use specific packages like crypto/aes, crypto/rsa, or crypto/sha256.

Hash Functions

Hash Type

The Hash type identifies cryptographic hash functions implemented in other packages.

type Hash uint

Supported Hash Functions:

• MD5 - crypto/md5
• SHA1 - crypto/sha1
• SHA224 - crypto/sha256
• SHA256 - crypto/sha256
• SHA384 - crypto/sha512
• SHA512 - crypto/sha512
• SHA3_224, SHA3_256, SHA3_384, SHA3_512 - crypto/sha3
• SHA512_224, SHA512_256 - crypto/sha512
• BLAKE2s_256, BLAKE2b_256, BLAKE2b_384, BLAKE2b_512 - golang.org/x/crypto/blake2b

Methods

Hash.New()

Returns a new hash.Hash calculating the given hash function.

func (h Hash) New() hash.Hash

Example:

import "crypto"

h := crypto.SHA256.New()
h.Write([]byte("hello world"))
sum := h.Sum(nil)

Hash.Available()

Reports whether the given hash function is linked into the binary.

func (h Hash) Available() bool

Hash.Size()

Returns the length, in bytes, of a digest resulting from the hash function.

func (h Hash) Size() int

RegisterHash()

Registers a function that returns a new instance of the given hash function. This is intended to be called from init functions in packages that implement hash functions.

func RegisterHash(h Hash, f func() hash.Hash)

Key Interfaces

PublicKey and PrivateKey

type PublicKey any
type PrivateKey any

These are empty interfaces for backwards compatibility. All standard library key types implement:

interface{
    Equal(x crypto.PublicKey) bool
}

Private keys also implement:

interface{
    Public() crypto.PublicKey
    Equal(x crypto.PrivateKey) bool
}

Signing and Verification

Signer Interface

Interface for opaque private keys that can be used for signing operations.

type Signer interface {
    Public() PublicKey
    Sign(rand io.Reader, digest []byte, opts SignerOpts) (signature []byte, err error)
}

Example:

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
)

privateKey, _ := rsa.GenerateKey(rand.Reader, 2048)
message := []byte("important message")

hashed := sha256.Sum256(message)
signature, err := privateKey.Sign(rand.Reader, hashed[:], crypto.SHA256)

MessageSigner Interface

Interface for signing operations where the message is not pre-hashed.

type MessageSigner interface {
    Signer
    SignMessage(rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error)
}

SignMessage()

Signs a message with a signer. Uses SignMessage if available, otherwise hashes and uses Sign.

func SignMessage(signer Signer, rand io.Reader, msg []byte, opts SignerOpts) (signature []byte, err error)

Decryption

Decrypter Interface

Interface for opaque private keys that can be used for asymmetric decryption.

type Decrypter interface {
    Public() PublicKey
    Decrypt(rand io.Reader, msg []byte, opts DecrypterOpts) (plaintext []byte, err error)
}

Example with RSA:

import (
    "crypto/rand"
    "crypto/rsa"
)

privateKey, _ := rsa.GenerateKey(rand.Reader, 2048)
ciphertext := []byte{...} // encrypted data

plaintext, err := privateKey.Decrypt(rand.Reader, ciphertext, nil)

Key Encapsulation Mechanisms (KEM)

Encapsulator Interface

Interface for public KEM keys that can be used for encapsulation.

type Encapsulator interface {
    Bytes() []byte
    Encapsulate() (sharedKey, ciphertext []byte)
}

Decapsulator Interface

Interface for private KEM keys that can be used for decapsulation.

type Decapsulator interface {
    Encapsulator() Encapsulator
    Decapsulate(ciphertext []byte) (sharedKey []byte, err error)
}

Example:

import "crypto/mlkem"

// Generate a key pair
decapsulationKey, err := mlkem.GenerateKey768()
if err != nil {
    // handle error
}

encapsulationKey := decapsulationKey.EncapsulationKey()

// Encapsulate to create shared secret
sharedKey, ciphertext := encapsulationKey.Encapsulate()

// Decapsulate to recover shared secret
recoveredKey, err := decapsulationKey.Decapsulate(ciphertext)

KEM interfaces are implemented by post-quantum cryptography packages like crypto/mlkem. Traditional key exchange mechanisms use different interfaces.

Security Considerations

Important Security Notes:

• Always use crypto/rand.Reader for random number generation in cryptographic operations
• Verify that hash functions are available with Hash.Available() before use
• Use appropriate hash sizes for your security requirements (SHA-256 minimum for new applications)
• Consider using MessageSigner when available to avoid pre-hashing mistakes
• Never implement your own cryptographic primitives - use standard library implementations

See Also

• crypto/tls - TLS 1.2 and 1.3 implementation
• crypto/x509 - X.509 certificate parsing and verification
• hash - Hash function interfaces