Documentation ¶
Overview ¶
Package ECDH implements Elliptic Curve Diffie-Hellman over NIST curves and Curve25519.
Index ¶
- Constants
- Variables
- type Curve
- type CurveType
- type PrivateKey
- func (k *PrivateKey) Bytes() []byte
- func (k *PrivateKey) Curve() Curve
- func (k *PrivateKey) CurveType() CurveType
- func (k *PrivateKey) ECDH(remote *PublicKey, out []byte) error
- func (k *PrivateKey) Equal(x crypto.PrivateKey) bool
- func (k *PrivateKey) Public() crypto.PublicKey
- func (k *PrivateKey) PublicKey() *PublicKey
- func (k *PrivateKey) SetPublicKey(pub *PublicKey) error
- type PublicKey
- type X25519Curve
- func (c *X25519Curve) ECDH(local *PrivateKey, remote *PublicKey, out []byte) error
- func (c *X25519Curve) FillKeyBuffer(rand io.Reader, out []byte) error
- func (c *X25519Curve) GenerateKey(rand io.Reader, out *PrivateKey) error
- func (c *X25519Curve) NewPrivateKey(pvtKeyBuf []byte, out *PrivateKey) error
- func (c *X25519Curve) NewPublicKey(key []byte, out *PublicKey) error
- func (c *X25519Curve) PrivateKeyBlockSize() int
- func (c *X25519Curve) PublicKeyBlockSize() int
- func (c *X25519Curve) SetPublicKeyFromPrivateKey(key *PrivateKey, out *PublicKey) error
- func (c *X25519Curve) SharedSecretBlockSize() int
- func (c *X25519Curve) String() string
Constants ¶
const ( X25519PublicKeySize = 32 X25519PrivateKeySize = 32 )
Variables ¶
var ( ErrInvalidPrivateKeySize = errors.New("crypto/ECDH: invalid private key size") ErrInvalidPublicKeySize = errors.New("crypto/ECDH: invalid public key size") )
Functions ¶
This section is empty.
Types ¶
type Curve ¶
type Curve interface { // PrivateKeyBlockSize reports the private key data block size. PrivateKeyBlockSize() int // PublicKeyBlockSize reports the public key data block size. PublicKeyBlockSize() int SharedSecretBlockSize() int // 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. NewPrivateKey(pvtKeyBuf []byte, out *PrivateKey) 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. NewPublicKey(data []byte, out *PublicKey) error // GenerateKey fills a PrivateKey with data from a reader. // // Most applications should use [crypto/rand.Reader] as rand. Note that the // returned key does not depend deterministically on the bytes read from rand, // and may change between calls and/or between versions. GenerateKey(rand io.Reader, out *PrivateKey) error // SetPublicKeyFromPrivateKey sets a PublicKey to match the corresponding PrivateKey. // // This method always succeeds: for X25519, the zero key can't be // constructed due to clamping; for NIST curves, it is rejected by // NewPrivateKey. SetPublicKeyFromPrivateKey(inp *PrivateKey, out *PublicKey) error // ECDH performs an ECDH exchange and returns the shared secret. It's also // exposed as the [PrivateKey.ECDH] method. ECDH(local *PrivateKey, remote *PublicKey, out []byte) error }
type PrivateKey ¶
type PrivateKey struct {
// contains filtered or unexported fields
}
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.
func (*PrivateKey) Curve ¶
func (k *PrivateKey) Curve() Curve
func (*PrivateKey) CurveType ¶
func (k *PrivateKey) CurveType() CurveType
func (*PrivateKey) ECDH ¶
func (k *PrivateKey) ECDH(remote *PublicKey, out []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.
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.
func (*PrivateKey) Equal ¶
func (k *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.
func (*PrivateKey) Public ¶
func (k *PrivateKey) Public() crypto.PublicKey
Public implements the implicit interface of all standard library private keys. See the docs of crypto.PrivateKey.
func (*PrivateKey) PublicKey ¶
func (k *PrivateKey) PublicKey() *PublicKey
func (*PrivateKey) SetPublicKey ¶
func (k *PrivateKey) SetPublicKey(pub *PublicKey) error
SetPublicKey sets the given PublicKey to match the PrivateKey.
type PublicKey ¶
type PublicKey struct {
// contains filtered or unexported fields
}
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.
func (*PublicKey) Equal ¶
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.
type X25519Curve ¶
type X25519Curve struct{}
func X25519 ¶
func X25519() *X25519Curve
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.
func (*X25519Curve) ECDH ¶
func (c *X25519Curve) ECDH(local *PrivateKey, remote *PublicKey, out []byte) error
func (*X25519Curve) FillKeyBuffer ¶
func (c *X25519Curve) FillKeyBuffer(rand io.Reader, out []byte) error
func (*X25519Curve) GenerateKey ¶
func (c *X25519Curve) GenerateKey(rand io.Reader, out *PrivateKey) error
func (*X25519Curve) NewPrivateKey ¶
func (c *X25519Curve) NewPrivateKey(pvtKeyBuf []byte, out *PrivateKey) error
func (*X25519Curve) NewPublicKey ¶
func (c *X25519Curve) NewPublicKey(key []byte, out *PublicKey) error
func (*X25519Curve) PrivateKeyBlockSize ¶
func (c *X25519Curve) PrivateKeyBlockSize() int
func (*X25519Curve) PublicKeyBlockSize ¶
func (c *X25519Curve) PublicKeyBlockSize() int
func (*X25519Curve) SetPublicKeyFromPrivateKey ¶
func (c *X25519Curve) SetPublicKeyFromPrivateKey(key *PrivateKey, out *PublicKey) error
func (*X25519Curve) SharedSecretBlockSize ¶
func (c *X25519Curve) SharedSecretBlockSize() int
func (*X25519Curve) String ¶
func (c *X25519Curve) String() string