Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us