all: gofmt
Gofmt to update doc comments to the new formatting.
For golang/go#51082.
Change-Id: I076031b6613691eefbb0f21739366e3fd2011ec9
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/399356
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Auto-Submit: Russ Cox <rsc@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
diff --git a/acme/acme.go b/acme/acme.go
index f2d23f6..2c86df3 100644
--- a/acme/acme.go
+++ b/acme/acme.go
@@ -77,12 +77,11 @@
// The only required field is Key. An example of creating a client with a new key
// is as follows:
//
-// key, err := rsa.GenerateKey(rand.Reader, 2048)
-// if err != nil {
-// log.Fatal(err)
-// }
-// client := &Client{Key: key}
-//
+// key, err := rsa.GenerateKey(rand.Reader, 2048)
+// if err != nil {
+// log.Fatal(err)
+// }
+// client := &Client{Key: key}
type Client struct {
// Key is the account key used to register with a CA and sign requests.
// Key.Public() must return a *rsa.PublicKey or *ecdsa.PublicKey.
diff --git a/acme/autocert/listener.go b/acme/autocert/listener.go
index cb48609..9d62f8c 100644
--- a/acme/autocert/listener.go
+++ b/acme/autocert/listener.go
@@ -20,7 +20,7 @@
//
// It enables one-line HTTPS servers:
//
-// log.Fatal(http.Serve(autocert.NewListener("example.com"), handler))
+// log.Fatal(http.Serve(autocert.NewListener("example.com"), handler))
//
// NewListener is a convenience function for a common configuration.
// More complex or custom configurations can use the autocert.Manager
diff --git a/acme/internal/acmeprobe/prober.go b/acme/internal/acmeprobe/prober.go
index 471707d..25dba0c 100644
--- a/acme/internal/acmeprobe/prober.go
+++ b/acme/internal/acmeprobe/prober.go
@@ -11,12 +11,12 @@
//
// A usage example:
//
-// go run prober.go \
-// -d https://acme-staging-v02.api.letsencrypt.org/directory \
-// -f order \
-// -t http-01 \
-// -a :8080 \
-// -domain some.example.org
+// go run prober.go \
+// -d https://acme-staging-v02.api.letsencrypt.org/directory \
+// -f order \
+// -t http-01 \
+// -a :8080 \
+// -domain some.example.org
//
// The above assumes a TCP tunnel from some.example.org:80 to 0.0.0.0:8080
// in order for the test to be able to fulfill http-01 challenge.
diff --git a/argon2/argon2.go b/argon2/argon2.go
index b423fea..29f0a2d 100644
--- a/argon2/argon2.go
+++ b/argon2/argon2.go
@@ -11,8 +11,7 @@
// If you aren't sure which function you need, use Argon2id (IDKey) and
// the parameter recommendations for your scenario.
//
-//
-// Argon2i
+// # Argon2i
//
// Argon2i (implemented by Key) is the side-channel resistant version of Argon2.
// It uses data-independent memory access, which is preferred for password
@@ -21,8 +20,7 @@
// parameters (taken from [2]) for non-interactive operations are time=3 and to
// use the maximum available memory.
//
-//
-// Argon2id
+// # Argon2id
//
// Argon2id (implemented by IDKey) is a hybrid version of Argon2 combining
// Argon2i and Argon2d. It uses data-independent memory access for the first
@@ -59,7 +57,7 @@
// For example, you can get a derived key for e.g. AES-256 (which needs a
// 32-byte key) by doing:
//
-// key := argon2.Key([]byte("some password"), salt, 3, 32*1024, 4, 32)
+// key := argon2.Key([]byte("some password"), salt, 3, 32*1024, 4, 32)
//
// The draft RFC recommends[2] time=3, and memory=32*1024 is a sensible number.
// If using that amount of memory (32 MB) is not possible in some contexts then
@@ -83,7 +81,7 @@
// For example, you can get a derived key for e.g. AES-256 (which needs a
// 32-byte key) by doing:
//
-// key := argon2.IDKey([]byte("some password"), salt, 1, 64*1024, 4, 32)
+// key := argon2.IDKey([]byte("some password"), salt, 1, 64*1024, 4, 32)
//
// The draft RFC recommends[2] time=1, and memory=64*1024 is a sensible number.
// If using that amount of memory (64 MB) is not possible in some contexts then
diff --git a/chacha20/chacha_s390x.go b/chacha20/chacha_s390x.go
index c5898db..4652247 100644
--- a/chacha20/chacha_s390x.go
+++ b/chacha20/chacha_s390x.go
@@ -15,6 +15,7 @@
// xorKeyStreamVX is an assembly implementation of XORKeyStream. It must only
// be called when the vector facility is available. Implementation in asm_s390x.s.
+//
//go:noescape
func xorKeyStreamVX(dst, src []byte, key *[8]uint32, nonce *[3]uint32, counter *uint32)
diff --git a/cryptobyte/builder.go b/cryptobyte/builder.go
index ca7b1db..c7ded75 100644
--- a/cryptobyte/builder.go
+++ b/cryptobyte/builder.go
@@ -106,13 +106,13 @@
// supplied to them. The child builder passed to the continuation can be used
// to build the content of the length-prefixed sequence. For example:
//
-// parent := cryptobyte.NewBuilder()
-// parent.AddUint8LengthPrefixed(func (child *Builder) {
-// child.AddUint8(42)
-// child.AddUint8LengthPrefixed(func (grandchild *Builder) {
-// grandchild.AddUint8(5)
-// })
-// })
+// parent := cryptobyte.NewBuilder()
+// parent.AddUint8LengthPrefixed(func (child *Builder) {
+// child.AddUint8(42)
+// child.AddUint8LengthPrefixed(func (grandchild *Builder) {
+// grandchild.AddUint8(5)
+// })
+// })
//
// It is an error to write more bytes to the child than allowed by the reserved
// length prefix. After the continuation returns, the child must be considered
diff --git a/curve25519/internal/field/fe_alias_test.go b/curve25519/internal/field/fe_alias_test.go
index 5ad81df..64e57c4 100644
--- a/curve25519/internal/field/fe_alias_test.go
+++ b/curve25519/internal/field/fe_alias_test.go
@@ -77,11 +77,11 @@
// TestAliasing checks that receivers and arguments can alias each other without
// leading to incorrect results. That is, it ensures that it's safe to write
//
-// v.Invert(v)
+// v.Invert(v)
//
// or
//
-// v.Add(v, v)
+// v.Add(v, v)
//
// without any of the inputs getting clobbered by the output being written.
func TestAliasing(t *testing.T) {
diff --git a/curve25519/internal/field/fe_amd64.go b/curve25519/internal/field/fe_amd64.go
index 44dc8e8..edcf163 100644
--- a/curve25519/internal/field/fe_amd64.go
+++ b/curve25519/internal/field/fe_amd64.go
@@ -1,13 +1,16 @@
// Code generated by command: go run fe_amd64_asm.go -out ../fe_amd64.s -stubs ../fe_amd64.go -pkg field. DO NOT EDIT.
+//go:build amd64 && gc && !purego
// +build amd64,gc,!purego
package field
// feMul sets out = a * b. It works like feMulGeneric.
+//
//go:noescape
func feMul(out *Element, a *Element, b *Element)
// feSquare sets out = a * a. It works like feSquareGeneric.
+//
//go:noescape
func feSquare(out *Element, a *Element)
diff --git a/internal/poly1305/sum_generic.go b/internal/poly1305/sum_generic.go
index c942a65..e041da5 100644
--- a/internal/poly1305/sum_generic.go
+++ b/internal/poly1305/sum_generic.go
@@ -136,7 +136,7 @@
// updateGeneric absorbs msg into the state.h accumulator. For each chunk m of
// 128 bits of message, it computes
//
-// h₊ = (h + m) * r mod 2¹³⁰ - 5
+// h₊ = (h + m) * r mod 2¹³⁰ - 5
//
// If the msg length is not a multiple of TagSize, it assumes the last
// incomplete chunk is the final one.
@@ -278,8 +278,7 @@
// finalize completes the modular reduction of h and computes
//
-// out = h + s mod 2¹²⁸
-//
+// out = h + s mod 2¹²⁸
func finalize(out *[TagSize]byte, h *[3]uint64, s *[2]uint64) {
h0, h1, h2 := h[0], h[1], h[2]
diff --git a/internal/poly1305/sum_s390x.go b/internal/poly1305/sum_s390x.go
index 62cc9f8..ec95966 100644
--- a/internal/poly1305/sum_s390x.go
+++ b/internal/poly1305/sum_s390x.go
@@ -14,6 +14,7 @@
// updateVX is an assembly implementation of Poly1305 that uses vector
// instructions. It must only be called if the vector facility (vx) is
// available.
+//
//go:noescape
func updateVX(state *macState, msg []byte)
diff --git a/openpgp/armor/armor.go b/openpgp/armor/armor.go
index ebc8787..be342ad 100644
--- a/openpgp/armor/armor.go
+++ b/openpgp/armor/armor.go
@@ -23,12 +23,14 @@
// A Block represents an OpenPGP armored structure.
//
// The encoded form is:
-// -----BEGIN Type-----
-// Headers
//
-// base64-encoded Bytes
-// '=' base64 encoded checksum
-// -----END Type-----
+// -----BEGIN Type-----
+// Headers
+//
+// base64-encoded Bytes
+// '=' base64 encoded checksum
+// -----END Type-----
+//
// where Headers is a possibly empty sequence of Key: Value lines.
//
// Since the armored data can be very large, this package presents a streaming
diff --git a/openpgp/armor/encode.go b/openpgp/armor/encode.go
index 6f07582..5b6e16c 100644
--- a/openpgp/armor/encode.go
+++ b/openpgp/armor/encode.go
@@ -96,7 +96,8 @@
// trailer.
//
// It's built into a stack of io.Writers:
-// encoding -> base64 encoder -> lineBreaker -> out
+//
+// encoding -> base64 encoder -> lineBreaker -> out
type encoding struct {
out io.Writer
breaker *lineBreaker
diff --git a/openpgp/elgamal/elgamal.go b/openpgp/elgamal/elgamal.go
index 84396a0..743b35a 100644
--- a/openpgp/elgamal/elgamal.go
+++ b/openpgp/elgamal/elgamal.go
@@ -77,8 +77,8 @@
// returns the plaintext of the message. An error can result only if the
// ciphertext is invalid. Users should keep in mind that this is a padding
// oracle and thus, if exposed to an adaptive chosen ciphertext attack, can
-// be used to break the cryptosystem. See ``Chosen Ciphertext Attacks
-// Against Protocols Based on the RSA Encryption Standard PKCS #1'', Daniel
+// be used to break the cryptosystem. See “Chosen Ciphertext Attacks
+// Against Protocols Based on the RSA Encryption Standard PKCS #1”, Daniel
// Bleichenbacher, Advances in Cryptology (Crypto '98),
func Decrypt(priv *PrivateKey, c1, c2 *big.Int) (msg []byte, err error) {
s := new(big.Int).Exp(c1, priv.X, priv.P)
diff --git a/openpgp/packet/signature_v3_test.go b/openpgp/packet/signature_v3_test.go
index ad7b62a..73b46ae 100644
--- a/openpgp/packet/signature_v3_test.go
+++ b/openpgp/packet/signature_v3_test.go
@@ -66,18 +66,23 @@
// keySigV3Armor is some V3 public key I found in an SKS dump.
// Old: Public Key Packet(tag 6)(141 bytes)
-// Ver 4 - new
-// Public key creation time - Fri Sep 16 17:13:54 CDT 1994
-// Pub alg - unknown(pub 0)
-// Unknown public key(pub 0)
+//
+// Ver 4 - new
+// Public key creation time - Fri Sep 16 17:13:54 CDT 1994
+// Pub alg - unknown(pub 0)
+// Unknown public key(pub 0)
+//
// Old: User ID Packet(tag 13)(39 bytes)
-// User ID - Armin M. Warda <warda@nephilim.ruhr.de>
+//
+// User ID - Armin M. Warda <warda@nephilim.ruhr.de>
+//
// Old: Signature Packet(tag 2)(149 bytes)
-// Ver 4 - new
-// Sig type - unknown(05)
-// Pub alg - ElGamal Encrypt-Only(pub 16)
-// Hash alg - unknown(hash 46)
-// Hashed Sub: unknown(sub 81, critical)(1988 bytes)
+//
+// Ver 4 - new
+// Sig type - unknown(05)
+// Pub alg - ElGamal Encrypt-Only(pub 16)
+// Hash alg - unknown(hash 46)
+// Hashed Sub: unknown(sub 81, critical)(1988 bytes)
const keySigV3Armor = `-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: SKS 1.0.10
diff --git a/pbkdf2/pbkdf2.go b/pbkdf2/pbkdf2.go
index 593f653..904b57e 100644
--- a/pbkdf2/pbkdf2.go
+++ b/pbkdf2/pbkdf2.go
@@ -32,7 +32,7 @@
// can get a derived key for e.g. AES-256 (which needs a 32-byte key) by
// doing:
//
-// dk := pbkdf2.Key([]byte("some password"), salt, 4096, 32, sha1.New)
+// dk := pbkdf2.Key([]byte("some password"), salt, 4096, 32, sha1.New)
//
// Remember to get a good random salt. At least 8 bytes is recommended by the
// RFC.
diff --git a/scrypt/scrypt.go b/scrypt/scrypt.go
index bbe4494..c971a99 100644
--- a/scrypt/scrypt.go
+++ b/scrypt/scrypt.go
@@ -186,7 +186,7 @@
// For example, you can get a derived key for e.g. AES-256 (which needs a
// 32-byte key) by doing:
//
-// dk, err := scrypt.Key([]byte("some password"), salt, 32768, 8, 1, 32)
+// dk, err := scrypt.Key([]byte("some password"), salt, 32768, 8, 1, 32)
//
// The recommended parameters for interactive logins as of 2017 are N=32768, r=8
// and p=1. The parameters N, r, and p should be increased as memory latency and
diff --git a/sha3/doc.go b/sha3/doc.go
index c2fef30..decd8cf 100644
--- a/sha3/doc.go
+++ b/sha3/doc.go
@@ -8,8 +8,7 @@
// Both types of hash function use the "sponge" construction and the Keccak
// permutation. For a detailed specification see http://keccak.noekeon.org/
//
-//
-// Guidance
+// # Guidance
//
// If you aren't sure what function you need, use SHAKE256 with at least 64
// bytes of output. The SHAKE instances are faster than the SHA3 instances;
@@ -19,8 +18,7 @@
// secret key to the input, hash with SHAKE256 and read at least 32 bytes of
// output.
//
-//
-// Security strengths
+// # Security strengths
//
// The SHA3-x (x equals 224, 256, 384, or 512) functions have a security
// strength against preimage attacks of x bits. Since they only produce "x"
@@ -31,8 +29,7 @@
// is used. Requesting more than 64 or 32 bytes of output, respectively, does
// not increase the collision-resistance of the SHAKE functions.
//
-//
-// The sponge construction
+// # The sponge construction
//
// A sponge builds a pseudo-random function from a public pseudo-random
// permutation, by applying the permutation to a state of "rate + capacity"
@@ -50,8 +47,7 @@
// Since the KeccakF-1600 permutation is 1600 bits (200 bytes) wide, this means
// that the security strength of a sponge instance is equal to (1600 - bitrate) / 2.
//
-//
-// Recommendations
+// # Recommendations
//
// The SHAKE functions are recommended for most new uses. They can produce
// output of arbitrary length. SHAKE256, with an output length of at least
diff --git a/sha3/sha3_s390x.go b/sha3/sha3_s390x.go
index 4fcfc92..63a3edb 100644
--- a/sha3/sha3_s390x.go
+++ b/sha3/sha3_s390x.go
@@ -34,11 +34,13 @@
// kimd is a wrapper for the 'compute intermediate message digest' instruction.
// src must be a multiple of the rate for the given function code.
+//
//go:noescape
func kimd(function code, chain *[200]byte, src []byte)
// klmd is a wrapper for the 'compute last message digest' instruction.
// src padding is handled by the instruction.
+//
//go:noescape
func klmd(function code, chain *[200]byte, dst, src []byte)
diff --git a/ssh/agent/client.go b/ssh/agent/client.go
index 3cfe723..dbc79d5 100644
--- a/ssh/agent/client.go
+++ b/ssh/agent/client.go
@@ -8,7 +8,8 @@
// ssh-agent process using the sample server.
//
// References:
-// [PROTOCOL.agent]: https://tools.ietf.org/html/draft-miller-ssh-agent-00
+//
+// [PROTOCOL.agent]: https://tools.ietf.org/html/draft-miller-ssh-agent-00
package agent // import "golang.org/x/crypto/ssh/agent"
import (
diff --git a/ssh/certs_test.go b/ssh/certs_test.go
index ba6dbca..e600483 100644
--- a/ssh/certs_test.go
+++ b/ssh/certs_test.go
@@ -49,14 +49,17 @@
// % ssh-keygen -s ca -I testcert -O source-address=192.168.1.0/24 -O force-command=/bin/sleep user.pub
// user.pub key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDACh1rt2DXfV3hk6fszSQcQ/rueMId0kVD9U7nl8cfEnFxqOCrNT92g4laQIGl2mn8lsGZfTLg8ksHq3gkvgO3oo/0wHy4v32JeBOHTsN5AL4gfHNEhWeWb50ev47hnTsRIt9P4dxogeUo/hTu7j9+s9lLpEQXCvq6xocXQt0j8MV9qZBBXFLXVT3cWIkSqOdwt/5ZBg+1GSrc7WfCXVWgTk4a20uPMuJPxU4RQwZW6X3+O8Pqo8C3cW0OzZRFP6gUYUKUsTI5WntlS+LAxgw1mZNsozFGdbiOPRnEryE3SRldh9vjDR3tin1fGpA5P7+CEB/bqaXtG3V+F2OkqaMN
// Critical Options:
-// force-command /bin/sleep
-// source-address 192.168.1.0/24
+//
+// force-command /bin/sleep
+// source-address 192.168.1.0/24
+//
// Extensions:
-// permit-X11-forwarding
-// permit-agent-forwarding
-// permit-port-forwarding
-// permit-pty
-// permit-user-rc
+//
+// permit-X11-forwarding
+// permit-agent-forwarding
+// permit-port-forwarding
+// permit-pty
+// permit-user-rc
const exampleSSHCertWithOptions = `ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgDyysCJY0XrO1n03EeRRoITnTPdjENFmWDs9X58PP3VUAAAADAQABAAABAQDACh1rt2DXfV3hk6fszSQcQ/rueMId0kVD9U7nl8cfEnFxqOCrNT92g4laQIGl2mn8lsGZfTLg8ksHq3gkvgO3oo/0wHy4v32JeBOHTsN5AL4gfHNEhWeWb50ev47hnTsRIt9P4dxogeUo/hTu7j9+s9lLpEQXCvq6xocXQt0j8MV9qZBBXFLXVT3cWIkSqOdwt/5ZBg+1GSrc7WfCXVWgTk4a20uPMuJPxU4RQwZW6X3+O8Pqo8C3cW0OzZRFP6gUYUKUsTI5WntlS+LAxgw1mZNsozFGdbiOPRnEryE3SRldh9vjDR3tin1fGpA5P7+CEB/bqaXtG3V+F2OkqaMNAAAAAAAAAAAAAAABAAAACHRlc3RjZXJ0AAAAAAAAAAAAAAAA//////////8AAABLAAAADWZvcmNlLWNvbW1hbmQAAAAOAAAACi9iaW4vc2xlZXAAAAAOc291cmNlLWFkZHJlc3MAAAASAAAADjE5Mi4xNjguMS4wLzI0AAAAggAAABVwZXJtaXQtWDExLWZvcndhcmRpbmcAAAAAAAAAF3Blcm1pdC1hZ2VudC1mb3J3YXJkaW5nAAAAAAAAABZwZXJtaXQtcG9ydC1mb3J3YXJkaW5nAAAAAAAAAApwZXJtaXQtcHR5AAAAAAAAAA5wZXJtaXQtdXNlci1yYwAAAAAAAAAAAAABFwAAAAdzc2gtcnNhAAAAAwEAAQAAAQEAwU+c5ui5A8+J/CFpjW8wCa52bEODA808WWQDCSuTG/eMXNf59v9Y8Pk0F1E9dGCosSNyVcB/hacUrc6He+i97+HJCyKavBsE6GDxrjRyxYqAlfcOXi/IVmaUGiO8OQ39d4GHrjToInKvExSUeleQyH4Y4/e27T/pILAqPFL3fyrvMLT5qU9QyIt6zIpa7GBP5+urouNavMprV3zsfIqNBbWypinOQAw823a5wN+zwXnhZrgQiHZ/USG09Y6k98y1dTVz8YHlQVR4D3lpTAsKDKJ5hCH9WU4fdf+lU8OyNGaJ/vz0XNqxcToe1l4numLTnaoSuH89pHryjqurB7lJKwAAAQ8AAAAHc3NoLXJzYQAAAQCaHvUIoPL1zWUHIXLvu96/HU1s/i4CAW2IIEuGgxCUCiFj6vyTyYtgxQxcmbfZf6eaITlS6XJZa7Qq4iaFZh75C1DXTX8labXhRSD4E2t//AIP9MC1rtQC5xo6FmbQ+BoKcDskr+mNACcbRSxs3IL3bwCfWDnIw2WbVox9ZdcthJKk4UoCW4ix4QwdHw7zlddlz++fGEEVhmTbll1SUkycGApPFBsAYRTMupUJcYPIeReBI/m8XfkoMk99bV8ZJQTAd7OekHY2/48Ff53jLmyDjP7kNw1F8OaPtkFs6dGJXta4krmaekPy87j+35In5hFj7yoOqvSbmYUkeX70/GGQ`
func TestParseCertWithOptions(t *testing.T) {
diff --git a/ssh/cipher.go b/ssh/cipher.go
index f8bdf49..770e8a6 100644
--- a/ssh/cipher.go
+++ b/ssh/cipher.go
@@ -640,7 +640,7 @@
// chacha20Poly1305Cipher implements the chacha20-poly1305@openssh.com
// AEAD, which is described here:
//
-// https://tools.ietf.org/html/draft-josefsson-ssh-chacha20-poly1305-openssh-00
+// https://tools.ietf.org/html/draft-josefsson-ssh-chacha20-poly1305-openssh-00
//
// the methods here also implement padding, which RFC4253 Section 6
// also requires of stream ciphers.
diff --git a/ssh/doc.go b/ssh/doc.go
index 67b7322..f6bff60 100644
--- a/ssh/doc.go
+++ b/ssh/doc.go
@@ -12,8 +12,9 @@
others.
References:
- [PROTOCOL.certkeys]: http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?rev=HEAD
- [SSH-PARAMETERS]: http://www.iana.org/assignments/ssh-parameters/ssh-parameters.xml#ssh-parameters-1
+
+ [PROTOCOL.certkeys]: http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?rev=HEAD
+ [SSH-PARAMETERS]: http://www.iana.org/assignments/ssh-parameters/ssh-parameters.xml#ssh-parameters-1
This package does not fall under the stability promise of the Go language itself,
so its API may be changed when pressing needs arise.
