Пакет hpke
Обзор
Пакет hpke реализует гибридное шифрование с открытым ключом (HPKE), определённое в RFC 9180.
Пример
Код:
// In this example, we use MLKEM768-X25519 as the KEM, HKDF-SHA256 as the
// KDF, and AES-256-GCM as the AEAD to encrypt a single message from a
// sender to a recipient using the one-shot API.
kem, kdf, aead := MLKEM768X25519(), HKDFSHA256(), AES256GCM()
// Recipient side
var (
recipientPrivateKey PrivateKey
publicKeyBytes []byte
)
{
k, err := kem.GenerateKey()
if err != nil {
panic(err)
}
recipientPrivateKey = k
publicKeyBytes = k.PublicKey().Bytes()
}
// Sender side
var ciphertext []byte
{
publicKey, err := kem.NewPublicKey(publicKeyBytes)
if err != nil {
panic(err)
}
message := []byte("|-()-|")
ct, err := Seal(publicKey, kdf, aead, []byte("example"), message)
if err != nil {
panic(err)
}
ciphertext = ct
}
// Recipient side
{
plaintext, err := Open(recipientPrivateKey, kdf, aead, []byte("example"), ciphertext)
if err != nil {
panic(err)
}
fmt.Printf("Decrypted message: %s\n", plaintext)
}
Результат:
Decrypted message: |-()-|
Указатель
Примеры
Файлы пакета
aead.go aead_fips140v1.26.go hpke.go kdf.go kem.go pq.go
func Open 1.26
func Open(k PrivateKey, kdf KDF, aead AEAD, info, ciphertext []byte) ([]byte, error)
Open создаёт одноразовый контекст приёма HPKE, подобный контексту NewRecipient, а затем расшифровывает предоставленный шифротекст, как Recipient.Open (без aad). ciphertext должен представлять собой конкатенацию инкапсулированного ключа и собственно шифротекста.
func Seal 1.26
func Seal(pk PublicKey, kdf KDF, aead AEAD, info, plaintext []byte) ([]byte, error)
Seal создаёт одноразовый контекст отправки HPKE, подобный контексту NewSender, а затем шифрует предоставленный открытый текст, как Sender.Seal (без aad). Seal возвращает конкатенацию инкапсулированного ключа и шифротекста.
type AEAD 1.26
AEAD — один из трёх компонентов набора шифров HPKE, реализующий симметричное шифрование.
type AEAD interface {
ID() uint16
// contains filtered or unexported methods
} func AES128GCM 1.26
func AES128GCM() AEAD
AES128GCM возвращает реализацию AEAD на основе AES-128-GCM.
func AES256GCM 1.26
func AES256GCM() AEAD
AES256GCM возвращает реализацию AEAD на основе AES-256-GCM.
func ChaCha20Poly1305 1.26
func ChaCha20Poly1305() AEAD
ChaCha20Poly1305 возвращает реализацию AEAD на основе ChaCha20Poly1305.
func ExportOnly 1.26
func ExportOnly() AEAD
ExportOnly возвращает заглушку реализации AEAD, которая не может шифровать или расшифровывать данные, а может только экспортировать секреты с помощью Sender.Export или Recipient.Export.
При её использовании Sender.Seal и Recipient.Open возвращают ошибки.
func NewAEAD 1.26
func NewAEAD(id uint16) (AEAD, error)
NewAEAD возвращает реализацию AEAD для указанного идентификатора AEAD.
Рекомендуется использовать конкретные реализации, например AES128GCM или ChaCha20Poly1305, если только не требуется возможность переключения во время выполнения.
type KDF 1.26
KDF — один из трёх компонентов набора шифров HPKE, реализующий выведение ключей.
type KDF interface {
ID() uint16
// contains filtered or unexported methods
} func HKDFSHA256 1.26
func HKDFSHA256() KDF
HKDFSHA256 возвращает реализацию KDF на основе HKDF-SHA256.
func HKDFSHA384 1.26
func HKDFSHA384() KDF
HKDFSHA384 возвращает реализацию KDF на основе HKDF-SHA384.
func HKDFSHA512 1.26
func HKDFSHA512() KDF
HKDFSHA512 возвращает реализацию KDF на основе HKDF-SHA512.
func NewKDF 1.26
func NewKDF(id uint16) (KDF, error)
NewKDF возвращает реализацию KDF для указанного идентификатора KDF.
Рекомендуется использовать конкретные реализации, например HKDFSHA256, если только не требуется возможность переключения во время выполнения.
func SHAKE128 1.26
func SHAKE128() KDF
SHAKE128 возвращает реализацию KDF на основе SHAKE128.
func SHAKE256 1.26
func SHAKE256() KDF
SHAKE256 возвращает реализацию KDF на основе SHAKE256.
type KEM 1.26
KEM — это механизм инкапсуляции ключа, один из трёх компонентов набора шифров HPKE.
type KEM interface {
// ID returns the HPKE KEM identifier.
ID() uint16
// GenerateKey generates a new key pair.
GenerateKey() (PrivateKey, error)
// NewPublicKey deserializes a public key from bytes.
//
// It implements DeserializePublicKey, as defined in RFC 9180.
NewPublicKey([]byte) (PublicKey, error)
// NewPrivateKey deserializes a private key from bytes.
//
// It implements DeserializePrivateKey, as defined in RFC 9180.
NewPrivateKey([]byte) (PrivateKey, error)
// DeriveKeyPair derives a key pair from the given input keying material.
//
// It implements DeriveKeyPair, as defined in RFC 9180.
DeriveKeyPair(ikm []byte) (PrivateKey, error)
// contains filtered or unexported methods
} func DHKEM 1.26
func DHKEM(curve ecdh.Curve) KEM
DHKEM возвращает KEM, реализующий один из вариантов:
- DHKEM(P-256, HKDF-SHA256)
- DHKEM(P-384, HKDF-SHA384)
- DHKEM(P-521, HKDF-SHA512)
- DHKEM(X25519, HKDF-SHA256)
в зависимости от кривой.
func MLKEM1024 1.26
func MLKEM1024() KEM
MLKEM1024 возвращает KEM, реализующий ML-KEM-1024 из draft-ietf-hpke-pq.
func MLKEM1024P384 1.26
func MLKEM1024P384() KEM
MLKEM1024P384 возвращает KEM, реализующий MLKEM1024-P384 из draft-ietf-hpke-pq.
func MLKEM768 1.26
func MLKEM768() KEM
MLKEM768 возвращает KEM, реализующий ML-KEM-768 из draft-ietf-hpke-pq.
func MLKEM768P256 1.26
func MLKEM768P256() KEM
MLKEM768P256 возвращает KEM, реализующий MLKEM768-P256 из draft-ietf-hpke-pq.
func MLKEM768X25519 1.26
func MLKEM768X25519() KEM
MLKEM768X25519 возвращает KEM, реализующий MLKEM768-X25519 (также известный как X-Wing) из draft-ietf-hpke-pq.
func NewKEM 1.26
func NewKEM(id uint16) (KEM, error)
NewKEM возвращает реализацию KEM для указанного идентификатора KEM.
Рекомендуется использовать конкретные реализации, такие как DHKEM или MLKEM768X25519, если только не требуется динамически выбирать реализацию во время выполнения.
type PrivateKey 1.26
PrivateKey — это экземпляр KEM (одного из трёх компонентов набора шифров HPKE) с ключом декапсуляции (то есть секретным ключом).
PrivateKey обычно получается с помощью метода соответствующего KEM, например KEM.GenerateKey или KEM.NewPrivateKey.
type PrivateKey interface {
// KEM returns the instantiated KEM.
KEM() KEM
// Bytes returns the private key as the output of SerializePrivateKey, as
// defined in RFC 9180.
//
// Note that for X25519 this might not match the input to NewPrivateKey.
// This is a requirement of RFC 9180, Section 7.1.2.
Bytes() ([]byte, error)
// PublicKey returns the corresponding PublicKey.
PublicKey() PublicKey
// contains filtered or unexported methods
} func NewDHKEMPrivateKey 1.26
func NewDHKEMPrivateKey(priv ecdh.KeyExchanger) (PrivateKey, error)
NewDHKEMPrivateKey возвращает PrivateKey, реализующий
- DHKEM(P-256, HKDF-SHA256)
- DHKEM(P-384, HKDF-SHA384)
- DHKEM(P-521, HKDF-SHA512)
- DHKEM(X25519, HKDF-SHA256)
в зависимости от базовой кривой priv (ecdh.X25519, ecdh.P256, ecdh.P384 или ecdh.P521).
Эта функция предназначена для приложений, у которых уже есть экземпляр закрытого ключа crypto/ecdh или другая реализация ecdh.KeyExchanger (например, аппаратный ключ). В противном случае приложениям следует использовать метод KEM.NewPrivateKey для DHKEM.
func NewHybridPrivateKey 1.26
func NewHybridPrivateKey(pq crypto.Decapsulator, t ecdh.KeyExchanger) (PrivateKey, error)
NewHybridPrivateKey возвращает PrivateKey, реализующий
- MLKEM768-X25519 (также известный как X-Wing)
- MLKEM768-P256
- MLKEM1024-P384
из draft-ietf-hpke-pq в зависимости от базовой кривой t (ecdh.X25519, ecdh.P256 или ecdh.P384) и типа pq.Encapsulator() (либо *mlkem.EncapsulationKey768, либо *mlkem.EncapsulationKey1024).
Эта функция предназначена для приложений, у которых уже есть экземпляры закрытых ключей crypto/ecdh и crypto/mlkem или другая реализация ecdh.KeyExchanger и crypto.Decapsulator (например, аппаратный ключ). В противном случае приложениям следует использовать метод KEM.NewPrivateKey для, например, MLKEM768X25519.
func NewMLKEMPrivateKey 1.26
func NewMLKEMPrivateKey(priv crypto.Decapsulator) (PrivateKey, error)
NewMLKEMPrivateKey возвращает KEMPrivateKey, реализующий
- ML-KEM-768
- ML-KEM-1024
из draft-ietf-hpke-pq в зависимости от типа priv.Encapsulator() (либо *mlkem.EncapsulationKey768, либо *mlkem.EncapsulationKey1024).
Эта функция предназначена для приложений, у которых уже есть экземпляр закрытого ключа crypto/mlkem. В противном случае приложениям следует использовать метод KEM.NewPrivateKey для, например, MLKEM768.
type PublicKey 1.26
PublicKey — это экземпляр KEM (одного из трёх компонентов набора шифров HPKE) с ключом инкапсуляции (то есть открытым ключом).
PublicKey обычно получается с помощью метода соответствующего KEM или PrivateKey, например KEM.NewPublicKey или PrivateKey.PublicKey.
type PublicKey interface {
// KEM returns the instantiated KEM.
KEM() KEM
// Bytes returns the public key as the output of SerializePublicKey.
Bytes() []byte
// contains filtered or unexported methods
} func NewDHKEMPublicKey 1.26
func NewDHKEMPublicKey(pub *ecdh.PublicKey) (PublicKey, error)
NewDHKEMPublicKey возвращает PublicKey, реализующий
- DHKEM(P-256, HKDF-SHA256)
- DHKEM(P-384, HKDF-SHA384)
- DHKEM(P-521, HKDF-SHA512)
- DHKEM(X25519, HKDF-SHA256)
в зависимости от базовой кривой pub (ecdh.X25519, ecdh.P256, ecdh.P384 или ecdh.P521).
Эта функция предназначена для приложений, у которых уже есть экземпляр открытого ключа crypto/ecdh. В противном случае приложениям следует использовать метод KEM.NewPublicKey для DHKEM.
func NewHybridPublicKey 1.26
func NewHybridPublicKey(pq crypto.Encapsulator, t *ecdh.PublicKey) (PublicKey, error)
NewHybridPublicKey возвращает PublicKey, реализующий один из вариантов:
- MLKEM768-X25519 (также известный как X-Wing)
- MLKEM768-P256
- MLKEM1024-P384
из draft-ietf-hpke-pq в зависимости от базовой кривой t (ecdh.X25519, ecdh.P256 или ecdh.P384) и типа pq (либо *mlkem.EncapsulationKey768, либо *mlkem.EncapsulationKey1024).
Эта функция предназначена для приложений, у которых уже есть экземпляры открытых ключей crypto/ecdh и crypto/mlkem. В противном случае приложениям следует использовать метод KEM.NewPublicKey для, например, MLKEM768X25519.
func NewMLKEMPublicKey 1.26
func NewMLKEMPublicKey(pub crypto.Encapsulator) (PublicKey, error)
NewMLKEMPublicKey возвращает KEMPublicKey, реализующий
- ML-KEM-768
- ML-KEM-1024
из draft-ietf-hpke-pq в зависимости от типа pub (*mlkem.EncapsulationKey768 или *mlkem.EncapsulationKey1024).
Эта функция предназначена для приложений, у которых уже есть экземпляр открытого ключа crypto/mlkem. В противном случае приложениям следует использовать метод KEM.NewPublicKey для, например, MLKEM768.
type Recipient 1.26
Recipient — это принимающий контекст HPKE. Он создаётся с определённым ключом декапсуляции KEM (то есть секретным ключом) и является состоянием: счётчик nonce увеличивается при каждом успешном вызове Recipient.Open.
type Recipient struct {
// contains filtered or unexported fields
}
func NewRecipient 1.26
func NewRecipient(enc []byte, k PrivateKey, kdf KDF, aead AEAD, info []byte) (*Recipient, error)
NewRecipient возвращает принимающий контекст HPKE для указанного ключа декапсуляции KEM (то есть секретного ключа), использующий набор шифров, заданный комбинацией KEM, KDF и AEAD.
Параметр enc должен быть создан соответствующим отправляющим контекстом HPKE с соответствующим ключом инкапсуляции KEM. Параметр info — это дополнительные общедоступные данные, которые должны совпадать у отправителя и получателя.
func (*Recipient) Export 1.26
func (r *Recipient) Export(exporterContext string, length int) ([]byte, error)
Export создаёт секретное значение, производное от общего ключа отправителя и получателя. Длина не должна превышать 65 535.
func (*Recipient) Open 1.26
func (r *Recipient) Open(aad, ciphertext []byte) ([]byte, error)
Open расшифровывает указанный шифротекст, при необходимости привязывая его к дополнительным общедоступным данным aad, или возвращает ошибку, если расшифрование завершается неудачно.
При каждом успешном вызове Open использует увеличивающийся счётчик; вызовы должны выполняться в том же порядке, что и Seal на стороне отправителя.
type Sender 1.26
Sender — это отправляющий контекст HPKE. Он создаётся с определённым ключом инкапсуляции KEM (то есть открытым ключом) и является состоянием: счётчик nonce увеличивается при каждом вызове Sender.Seal.
type Sender struct {
// contains filtered or unexported fields
}
func NewSender 1.26
func NewSender(pk PublicKey, kdf KDF, aead AEAD, info []byte) (enc []byte, s *Sender, err error)
NewSender возвращает отправляющий контекст HPKE для указанного ключа инкапсуляции KEM (то есть открытого ключа), использующий набор шифров, заданный комбинацией KEM, KDF и AEAD.
Параметр info — это дополнительные общедоступные данные, которые должны совпадать у отправителя и получателя.
Возвращённый шифротекст enc можно использовать для создания соответствующего принимающего контекста HPKE с соответствующим ключом декапсуляции KEM.
func (*Sender) Export 1.26
func (s *Sender) Export(exporterContext string, length int) ([]byte, error)
Export создаёт секретное значение, производное от общего ключа отправителя и получателя. Длина не должна превышать 65 535.
func (*Sender) Seal 1.26
func (s *Sender) Seal(aad, plaintext []byte) ([]byte, error)
Seal шифрует указанный открытый текст, при необходимости привязывая его к дополнительным общедоступным данным aad.
При каждом вызове Seal использует увеличивающийся счётчик; вызовы Open на принимающей стороне должны выполняться в том же порядке, что и Seal.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/crypto/hpke/
