Package: crypto/ecdh

package ecdh Import Path crypto/ecdh (on go.dev) Dependency Relation imports 10 packages, and imported by 4 packages

Involved Source Files d ecdh.go Package ecdh implements Elliptic Curve Diffie-Hellman over NIST curves and Curve25519. nist.go x25519.go

Package-Level Type Names (total 4)

/* sort by: alphabet | popularity */

type Curve (interface) Methods (total 3) ( Curve) GenerateKey(rand io.Reader) (*PrivateKey, error) GenerateKey generates a random PrivateKey. Since Go 1.26, a secure source of random bytes is always used, and rand is ignored unless GODEBUG=cryptocustomrand=1 is set. This setting will be removed in a future Go release. Instead, use [testing/cryptotest.SetGlobalRandom]. ( Curve) NewPrivateKey(key []byte) (*PrivateKey, error) NewPrivateKey checks that key is valid and returns a PrivateKey. For NIST curves, this follows SEC 1, Version 2.0, Section 2.3.6, which amounts to decoding the bytes as a fixed length big endian integer and checking that the result is lower than the order of the curve. The zero private key is also rejected, as the encoding of the corresponding public key would be irregular. For X25519, this only checks the scalar length. ( Curve) NewPublicKey(key []byte) (*PublicKey, error) NewPublicKey checks that key is valid and returns a PublicKey. For NIST curves, this decodes an uncompressed point according to SEC 1, Version 2.0, Section 2.3.4. Compressed encodings and the point at infinity are rejected. For X25519, this only checks the u-coordinate length. Adversarially selected public keys can cause ECDH to return an error. As Outputs Of (at least 7) func P256() Curve func P384() Curve func P521() Curve func X25519() Curve func KeyExchanger.Curve() Curve func (*PrivateKey).Curve() Curve func (*PublicKey).Curve() Curve As Inputs Of (at least one exported) func crypto/hpke.DHKEM(curve Curve) hpke.KEM

type KeyExchanger (interface) KeyExchanger is an interface for an opaque private key that can be used for key exchange operations. For example, an ECDH key kept in a hardware module. It is implemented by [PrivateKey]. Methods (total 3) ( KeyExchanger) Curve() Curve ( KeyExchanger) ECDH(*PublicKey) ([]byte, error) ( KeyExchanger) PublicKey() *PublicKey Implemented By (at least one exported) *PrivateKey As Inputs Of (at least 2) func crypto/hpke.NewDHKEMPrivateKey(priv KeyExchanger) (hpke.PrivateKey, error) func crypto/hpke.NewHybridPrivateKey(pq crypto.Decapsulator, t KeyExchanger) (hpke.PrivateKey, error)

type PrivateKey (struct) PrivateKey is an ECDH private key, usually kept secret. These keys can be parsed with [crypto/x509.ParsePKCS8PrivateKey] and encoded with [crypto/x509.MarshalPKCS8PrivateKey]. For NIST curves, they then need to be converted with [crypto/ecdsa.PrivateKey.ECDH] after parsing. Methods (total 6) (*PrivateKey) Bytes() []byte Bytes returns a copy of the encoding of the private key. (*PrivateKey) Curve() Curve (*PrivateKey) ECDH(remote *PublicKey) ([]byte, error) ECDH performs an ECDH exchange and returns the shared secret. The [PrivateKey] and [PublicKey] must use the same curve. For NIST curves, this performs ECDH as specified in SEC 1, Version 2.0, Section 3.3.1, and returns the x-coordinate encoded according to SEC 1, Version 2.0, Section 2.3.5. The result is never the point at infinity. This is also known as the Shared Secret Computation of the Ephemeral Unified Model scheme specified in NIST SP 800-56A Rev. 3, Section 6.1.2.2. For [X25519], this performs ECDH as specified in RFC 7748, Section 6.1. If the result is the all-zero value, ECDH returns an error. (*PrivateKey) Equal(x crypto.PrivateKey) bool Equal returns whether x represents the same private key as k. Note that there can be equivalent private keys with different encodings which would return false from this check but behave the same way as inputs to [ECDH]. This check is performed in constant time as long as the key types and their curve match. (*PrivateKey) Public() crypto.PublicKey Public implements the implicit interface of all standard library private keys. See the docs of [crypto.PrivateKey]. (*PrivateKey) PublicKey() *PublicKey Implements (at least one exported) *PrivateKey : KeyExchanger As Outputs Of (at least 3) func Curve.GenerateKey(rand io.Reader) (*PrivateKey, error) func Curve.NewPrivateKey(key []byte) (*PrivateKey, error) func crypto/ecdsa.(*PrivateKey).ECDH() (*PrivateKey, error)

type PublicKey (struct) PublicKey is an ECDH public key, usually a peer's ECDH share sent over the wire. These keys can be parsed with [crypto/x509.ParsePKIXPublicKey] and encoded with [crypto/x509.MarshalPKIXPublicKey]. For NIST curves, they then need to be converted with [crypto/ecdsa.PublicKey.ECDH] after parsing. Methods (total 3) (*PublicKey) Bytes() []byte Bytes returns a copy of the encoding of the public key. (*PublicKey) Curve() Curve (*PublicKey) Equal(x crypto.PublicKey) bool Equal returns whether x represents the same public key as k. Note that there can be equivalent public keys with different encodings which would return false from this check but behave the same way as inputs to ECDH. This check is performed in constant time as long as the key types and their curve match. As Outputs Of (at least 4) func Curve.NewPublicKey(key []byte) (*PublicKey, error) func KeyExchanger.PublicKey() *PublicKey func (*PrivateKey).PublicKey() *PublicKey func crypto/ecdsa.(*PublicKey).ECDH() (*PublicKey, error) As Inputs Of (at least 4) func KeyExchanger.ECDH(*PublicKey) ([]byte, error) func (*PrivateKey).ECDH(remote *PublicKey) ([]byte, error) func crypto/hpke.NewDHKEMPublicKey(pub *PublicKey) (hpke.PublicKey, error) func crypto/hpke.NewHybridPublicKey(pq crypto.Encapsulator, t *PublicKey) (hpke.PublicKey, error)

Package-Level Functions (total 4)

func P256() Curve P256 returns a [Curve] which implements NIST P-256 (FIPS 186-3, section D.2.3), also known as secp256r1 or prime256v1. Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements.

func P384() Curve P384 returns a [Curve] which implements NIST P-384 (FIPS 186-3, section D.2.4), also known as secp384r1. Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements.

func P521() Curve P521 returns a [Curve] which implements NIST P-521 (FIPS 186-3, section D.2.5), also known as secp521r1. Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements.

func X25519() Curve X25519 returns a [Curve] which implements the X25519 function over Curve25519 (RFC 7748, Section 5). Multiple invocations of this function will return the same value, so it can be used for equality checks and switch statements.