1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
<h1> Package ecdh </h1> <ul id="short-nav">
<li><code>import "crypto/ecdh"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
</ul> <h2 id="pkg-overview">Overview </h2> <p>Package ecdh implements Elliptic Curve Diffie-Hellman over NIST curves and Curve25519. </p> <h2 id="pkg-index">Index </h2> <ul id="manual-nav">
<li><a href="#Curve">type Curve</a></li>
<li> <a href="#P256">func P256() Curve</a>
</li>
<li> <a href="#P384">func P384() Curve</a>
</li>
<li> <a href="#P521">func P521() Curve</a>
</li>
<li> <a href="#X25519">func X25519() Curve</a>
</li>
<li><a href="#PrivateKey">type PrivateKey</a></li>
<li> <a href="#PrivateKey.Bytes">func (k *PrivateKey) Bytes() []byte</a>
</li>
<li> <a href="#PrivateKey.Curve">func (k *PrivateKey) Curve() Curve</a>
</li>
<li> <a href="#PrivateKey.ECDH">func (k *PrivateKey) ECDH(remote *PublicKey) ([]byte, error)</a>
</li>
<li> <a href="#PrivateKey.Equal">func (k *PrivateKey) Equal(x crypto.PrivateKey) bool</a>
</li>
<li> <a href="#PrivateKey.Public">func (k *PrivateKey) Public() crypto.PublicKey</a>
</li>
<li> <a href="#PrivateKey.PublicKey">func (k *PrivateKey) PublicKey() *PublicKey</a>
</li>
<li><a href="#PublicKey">type PublicKey</a></li>
<li> <a href="#PublicKey.Bytes">func (k *PublicKey) Bytes() []byte</a>
</li>
<li> <a href="#PublicKey.Curve">func (k *PublicKey) Curve() Curve</a>
</li>
<li> <a href="#PublicKey.Equal">func (k *PublicKey) Equal(x crypto.PublicKey) bool</a>
</li>
</ul> <h3>Package files</h3> <p> <span>ecdh.go</span> <span>nist.go</span> <span>x25519.go</span> </p> <h2 id="Curve">type <span>Curve</span> <span title="Added in Go 1.20">1.20</span> </h2> <pre data-language="go">type Curve interface {
// GenerateKey generates a random PrivateKey.
//
// 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) (*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.
NewPrivateKey(key []byte) (*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(key []byte) (*PublicKey, error)
// contains filtered or unexported methods
}</pre> <h3 id="P256">func <span>P256</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func P256() Curve</pre> <p>P256 returns a <a href="#Curve">Curve</a> which implements NIST P-256 (FIPS 186-3, section D.2.3), also known as secp256r1 or prime256v1. </p>
<p>Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. </p>
<h3 id="P384">func <span>P384</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func P384() Curve</pre> <p>P384 returns a <a href="#Curve">Curve</a> which implements NIST P-384 (FIPS 186-3, section D.2.4), also known as secp384r1. </p>
<p>Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. </p>
<h3 id="P521">func <span>P521</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func P521() Curve</pre> <p>P521 returns a <a href="#Curve">Curve</a> which implements NIST P-521 (FIPS 186-3, section D.2.5), also known as secp521r1. </p>
<p>Multiple invocations of this function will return the same value, which can be used for equality checks and switch statements. </p>
<h3 id="X25519">func <span>X25519</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func X25519() Curve</pre> <p>X25519 returns a <a href="#Curve">Curve</a> which implements the X25519 function over Curve25519 (RFC 7748, Section 5). </p>
<p>Multiple invocations of this function will return the same value, so it can be used for equality checks and switch statements. </p>
<h2 id="PrivateKey">type <span>PrivateKey</span> <span title="Added in Go 1.20">1.20</span> </h2> <p>PrivateKey is an ECDH private key, usually kept secret. </p>
<p>These keys can be parsed with <span>crypto/x509.ParsePKCS8PrivateKey</span> and encoded with <span>crypto/x509.MarshalPKCS8PrivateKey</span>. For NIST curves, they then need to be converted with <span>crypto/ecdsa.PrivateKey.ECDH</span> after parsing. </p>
<pre data-language="go">type PrivateKey struct {
// contains filtered or unexported fields
}
</pre> <h3 id="PrivateKey.Bytes">func (*PrivateKey) <span>Bytes</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) Bytes() []byte</pre> <p>Bytes returns a copy of the encoding of the private key. </p>
<h3 id="PrivateKey.Curve">func (*PrivateKey) <span>Curve</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) Curve() Curve</pre> <h3 id="PrivateKey.ECDH">func (*PrivateKey) <span>ECDH</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) ECDH(remote *PublicKey) ([]byte, error)</pre> <p>ECDH performs an ECDH exchange and returns the shared secret. The <a href="#PrivateKey">PrivateKey</a> and <a href="#PublicKey">PublicKey</a> must use the same curve. </p>
<p>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. </p>
<p>For <a href="#X25519">X25519</a>, this performs ECDH as specified in RFC 7748, Section 6.1. If the result is the all-zero value, ECDH returns an error. </p>
<h3 id="PrivateKey.Equal">func (*PrivateKey) <span>Equal</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) Equal(x crypto.PrivateKey) bool</pre> <p>Equal returns whether x represents the same private key as k. </p>
<p>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]. </p>
<p>This check is performed in constant time as long as the key types and their curve match. </p>
<h3 id="PrivateKey.Public">func (*PrivateKey) <span>Public</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) Public() crypto.PublicKey</pre> <p>Public implements the implicit interface of all standard library private keys. See the docs of <span>crypto.PrivateKey</span>. </p>
<h3 id="PrivateKey.PublicKey">func (*PrivateKey) <span>PublicKey</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PrivateKey) PublicKey() *PublicKey</pre> <h2 id="PublicKey">type <span>PublicKey</span> <span title="Added in Go 1.20">1.20</span> </h2> <p>PublicKey is an ECDH public key, usually a peer's ECDH share sent over the wire. </p>
<p>These keys can be parsed with <span>crypto/x509.ParsePKIXPublicKey</span> and encoded with <span>crypto/x509.MarshalPKIXPublicKey</span>. For NIST curves, they then need to be converted with <span>crypto/ecdsa.PublicKey.ECDH</span> after parsing. </p>
<pre data-language="go">type PublicKey struct {
// contains filtered or unexported fields
}
</pre> <h3 id="PublicKey.Bytes">func (*PublicKey) <span>Bytes</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PublicKey) Bytes() []byte</pre> <p>Bytes returns a copy of the encoding of the public key. </p>
<h3 id="PublicKey.Curve">func (*PublicKey) <span>Curve</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PublicKey) Curve() Curve</pre> <h3 id="PublicKey.Equal">func (*PublicKey) <span>Equal</span> <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PublicKey) Equal(x crypto.PublicKey) bool</pre> <p>Equal returns whether x represents the same public key as k. </p>
<p>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. </p>
<p>This check is performed in constant time as long as the key types and their curve match. </p><div class="_attribution">
<p class="_attribution-p">
© Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
<a href="http://golang.org/pkg/crypto/ecdh/" class="_attribution-link">http://golang.org/pkg/crypto/ecdh/</a>
</p>
</div>
|
