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>
2022-04-11 22:02:26 +00:00
parent 5352b09029
commit 7b82a4e95d
22 changed files with 82 additions and 70 deletions
@@ -77,12 +77,11 @@ const (
 // 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.
@@ -20,7 +20,7 @@ import (
 //
 // 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
@@ -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.
@@ -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 @@ const (
 // 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 @@ func Key(password, salt []byte, time, memory uint32, threads uint8, keyLen uint3
 // 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
@@ -15,6 +15,7 @@ const bufSize = 256

 // 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)

@@ -106,13 +106,13 @@ func (b *Builder) AddBytes(v []byte) {
 // 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
@@ -77,11 +77,11 @@ func checkAliasingTwoArgs(f func(v, x, y *Element) *Element) func(v, x, y Elemen
 // 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) {
@@ -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)
@@ -136,7 +136,7 @@ func shiftRightBy2(a uint128) uint128 {
 // 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 @@ const (

 // 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]

@@ -14,6 +14,7 @@ import (
 // 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)

@@ -23,12 +23,14 @@ import (
 // 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
@@ -96,7 +96,8 @@ func (l *lineBreaker) Close() (err error) {
 // 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
@@ -77,8 +77,8 @@ func Encrypt(random io.Reader, pub *PublicKey, msg []byte) (c1, c2 *big.Int, err
 // 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)
@@ -66,18 +66,23 @@ func v3KeyReader(t *testing.T) io.Reader {

 // 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

@@ -32,7 +32,7 @@ import (
 // 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.
@@ -186,7 +186,7 @@ func smix(b []byte, r, N int, v, xy []uint32) {
 // 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
@@ -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
@@ -34,11 +34,13 @@ const (

 // 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)

@@ -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 (
@@ -49,14 +49,17 @@ func TestParseCert(t *testing.T) {
 // % 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) {
@@ -640,7 +640,7 @@ const chacha20Poly1305ID = "chacha20-poly1305@openssh.com"
 // 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.
@@ -12,8 +12,9 @@ the multiplexed nature of SSH is exposed to users that wish to support
 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.