path: root/devdocs/go/crypto%2Fecdsa%2Findex.html

<h1> Package ecdsa  </h1>     <ul id="short-nav">
<li><code>import "crypto/ecdsa"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
<li><a href="#pkg-examples" class="examplesLink">Examples</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>Package ecdsa implements the Elliptic Curve Digital Signature Algorithm, as defined in FIPS 186-4 and SEC 1, Version 2.0. </p>
<p>Signatures generated by this package are not deterministic, but entropy is mixed with the private key and the message, achieving the same level of security in case of randomness source failure. </p>   <h4 id="example_"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">
privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
if err != nil {
    panic(err)
}

msg := "hello, world"
hash := sha256.Sum256([]byte(msg))

sig, err := ecdsa.SignASN1(rand.Reader, privateKey, hash[:])
if err != nil {
    panic(err)
}
fmt.Printf("signature: %x\n", sig)

valid := ecdsa.VerifyASN1(&amp;privateKey.PublicKey, hash[:], sig)
fmt.Println("signature verified:", valid)
</pre>        <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#Sign">func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err error)</a></li>
<li><a href="#SignASN1">func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte) ([]byte, error)</a></li>
<li><a href="#Verify">func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool</a></li>
<li><a href="#VerifyASN1">func VerifyASN1(pub *PublicKey, hash, sig []byte) bool</a></li>
<li><a href="#PrivateKey">type PrivateKey</a></li>
<li> <a href="#GenerateKey">func GenerateKey(c elliptic.Curve, rand io.Reader) (*PrivateKey, error)</a>
</li>
<li> <a href="#PrivateKey.ECDH">func (k *PrivateKey) ECDH() (*ecdh.PrivateKey, error)</a>
</li>
<li> <a href="#PrivateKey.Equal">func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool</a>
</li>
<li> <a href="#PrivateKey.Public">func (priv *PrivateKey) Public() crypto.PublicKey</a>
</li>
<li> <a href="#PrivateKey.Sign">func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)</a>
</li>
<li><a href="#PublicKey">type PublicKey</a></li>
<li> <a href="#PublicKey.ECDH">func (k *PublicKey) ECDH() (*ecdh.PublicKey, error)</a>
</li>
<li> <a href="#PublicKey.Equal">func (pub *PublicKey) Equal(x crypto.PublicKey) bool</a>
</li>
</ul> <div id="pkg-examples"> <h3>Examples</h3>  <dl> <dd><a class="exampleLink" href="#example_">Package</a></dd> </dl> </div> <h3>Package files</h3> <p>  <span>ecdsa.go</span> <span>ecdsa_legacy.go</span> <span>ecdsa_noasm.go</span> <span>notboring.go</span>  </p>   <h2 id="Sign">func <span>Sign</span>  </h2> <pre data-language="go">func Sign(rand io.Reader, priv *PrivateKey, hash []byte) (r, s *big.Int, err error)</pre> <p>Sign signs a hash (which should be the result of hashing a larger message) using the private key, priv. If the hash is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the signature as a pair of integers. Most applications should use <a href="#SignASN1">SignASN1</a> instead of dealing directly with r, s. </p>
<h2 id="SignASN1">func <span>SignASN1</span>  <span title="Added in Go 1.15">1.15</span> </h2> <pre data-language="go">func SignASN1(rand io.Reader, priv *PrivateKey, hash []byte) ([]byte, error)</pre> <p>SignASN1 signs a hash (which should be the result of hashing a larger message) using the private key, priv. If the hash is longer than the bit-length of the private key's curve order, the hash will be truncated to that length. It returns the ASN.1 encoded signature. </p>
<p>The signature is randomized. Most applications should use <span>crypto/rand.Reader</span> as rand. Note that the returned signature does not depend deterministically on the bytes read from rand, and may change between calls and/or between versions. </p>
<h2 id="Verify">func <span>Verify</span>  </h2> <pre data-language="go">func Verify(pub *PublicKey, hash []byte, r, s *big.Int) bool</pre> <p>Verify verifies the signature in r, s of hash using the public key, pub. Its return value records whether the signature is valid. Most applications should use VerifyASN1 instead of dealing directly with r, s. </p>
<h2 id="VerifyASN1">func <span>VerifyASN1</span>  <span title="Added in Go 1.15">1.15</span> </h2> <pre data-language="go">func VerifyASN1(pub *PublicKey, hash, sig []byte) bool</pre> <p>VerifyASN1 verifies the ASN.1 encoded signature, sig, of hash using the public key, pub. Its return value records whether the signature is valid. </p>
<h2 id="PrivateKey">type <span>PrivateKey</span>  </h2> <p>PrivateKey represents an ECDSA private key. </p>
<pre data-language="go">type PrivateKey struct {
    PublicKey
    D *big.Int
}
</pre> <h3 id="GenerateKey">func <span>GenerateKey</span>  </h3> <pre data-language="go">func GenerateKey(c elliptic.Curve, rand io.Reader) (*PrivateKey, error)</pre> <p>GenerateKey generates a new ECDSA private key for the specified curve. </p>
<p>Most applications should use <span>crypto/rand.Reader</span> 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. </p>
<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() (*ecdh.PrivateKey, error)</pre> <p>ECDH returns k as a <span>ecdh.PrivateKey</span>. It returns an error if the key is invalid according to the definition of <span>ecdh.Curve.NewPrivateKey</span>, or if the Curve is not supported by <span>crypto/ecdh</span>. </p>
<h3 id="PrivateKey.Equal">func (*PrivateKey) <span>Equal</span>  <span title="Added in Go 1.15">1.15</span> </h3> <pre data-language="go">func (priv *PrivateKey) Equal(x crypto.PrivateKey) bool</pre> <p>Equal reports whether priv and x have the same value. </p>
<p>See <a href="#PublicKey.Equal">PublicKey.Equal</a> for details on how Curve is compared. </p>
<h3 id="PrivateKey.Public">func (*PrivateKey) <span>Public</span>  <span title="Added in Go 1.4">1.4</span> </h3> <pre data-language="go">func (priv *PrivateKey) Public() crypto.PublicKey</pre> <p>Public returns the public key corresponding to priv. </p>
<h3 id="PrivateKey.Sign">func (*PrivateKey) <span>Sign</span>  <span title="Added in Go 1.4">1.4</span> </h3> <pre data-language="go">func (priv *PrivateKey) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)</pre> <p>Sign signs digest with priv, reading randomness from rand. The opts argument is not currently used but, in keeping with the crypto.Signer interface, should be the hash function used to digest the message. </p>
<p>This method implements crypto.Signer, which is an interface to support keys where the private part is kept in, for example, a hardware module. Common uses can use the <a href="#SignASN1">SignASN1</a> function in this package directly. </p>
<h2 id="PublicKey">type <span>PublicKey</span>  </h2> <p>PublicKey represents an ECDSA public key. </p>
<pre data-language="go">type PublicKey struct {
    elliptic.Curve
    X, Y *big.Int
}
</pre> <h3 id="PublicKey.ECDH">func (*PublicKey) <span>ECDH</span>  <span title="Added in Go 1.20">1.20</span> </h3> <pre data-language="go">func (k *PublicKey) ECDH() (*ecdh.PublicKey, error)</pre> <p>ECDH returns k as a <span>ecdh.PublicKey</span>. It returns an error if the key is invalid according to the definition of <span>ecdh.Curve.NewPublicKey</span>, or if the Curve is not supported by crypto/ecdh. </p>
<h3 id="PublicKey.Equal">func (*PublicKey) <span>Equal</span>  <span title="Added in Go 1.15">1.15</span> </h3> <pre data-language="go">func (pub *PublicKey) Equal(x crypto.PublicKey) bool</pre> <p>Equal reports whether pub and x have the same value. </p>
<p>Two keys are only considered to have the same value if they have the same Curve value. Note that for example <span>elliptic.P256</span> and elliptic.P256().Params() are different values, as the latter is a generic not constant time implementation. </p><div class="_attribution">
  <p class="_attribution-p">
    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
    <a href="http://golang.org/pkg/crypto/ecdsa/" class="_attribution-link">http://golang.org/pkg/crypto/ecdsa/</a>
  </p>
</div>