From 933c289fd11ae8491bffe91ab9a478ce5f5746b7 Mon Sep 17 00:00:00 2001 From: yuhan6665 <1588741+yuhan6665@users.noreply.github.com> Date: Mon, 16 Oct 2023 21:25:40 -0400 Subject: [PATCH] crypto: add available godoc link Change-Id: Ifc669399dde7d6229c6ccdbe29611ed1f8698fb1 Reviewed-on: https://go-review.googlesource.com/c/go/+/534778 Reviewed-by: Dmitri Shuralyov Reviewed-by: Ian Lance Taylor Run-TryBot: shuang cui TryBot-Result: Gopher Robot Auto-Submit: Ian Lance Taylor --- cipher_suites.go | 4 ++-- common.go | 12 ++++++------ conn.go | 32 ++++++++++++++++---------------- quic.go | 12 ++++++------ ticket.go | 2 +- tls.go | 12 ++++++------ 6 files changed, 37 insertions(+), 37 deletions(-) diff --git a/cipher_suites.go b/cipher_suites.go index 87a6446..35bf09f 100644 --- a/cipher_suites.go +++ b/cipher_suites.go @@ -44,7 +44,7 @@ var ( // CipherSuites returns a list of cipher suites currently implemented by this // package, excluding those with security issues, which are returned by -// InsecureCipherSuites. +// [InsecureCipherSuites]. // // The list is sorted by ID. Note that the default cipher suites selected by // this package might depend on logic that can't be captured by a static list, @@ -77,7 +77,7 @@ func CipherSuites() []*CipherSuite { // this package and which have security issues. // // Most applications should not use the cipher suites in this list, and should -// only use those returned by CipherSuites. +// only use those returned by [CipherSuites]. func InsecureCipherSuites() []*CipherSuite { // This list includes RC4, CBC_SHA256, and 3DES cipher suites. See // cipherSuitesPreferenceOrder for details. diff --git a/common.go b/common.go index 211fa39..e7dd94b 100644 --- a/common.go +++ b/common.go @@ -836,7 +836,7 @@ func (c *Config) ticketKeyFromBytes(b [32]byte) (key ticketKey) { // ticket, and the lifetime we set for all tickets we send. const maxSessionTicketLifetime = 7 * 24 * time.Hour -// Clone returns a shallow clone of c or nil if c is nil. It is safe to clone a Config that is +// Clone returns a shallow clone of c or nil if c is nil. It is safe to clone a [Config] that is // being used concurrently by a TLS client or server. func (c *Config) Clone() *Config { if c == nil { @@ -1182,9 +1182,9 @@ func (c *Config) getCertificate(clientHello *ClientHelloInfo) (*Certificate, err // the client that sent the ClientHello. Otherwise, it returns an error // describing the reason for the incompatibility. // -// If this ClientHelloInfo was passed to a GetConfigForClient or GetCertificate -// callback, this method will take into account the associated Config. Note that -// if GetConfigForClient returns a different Config, the change can't be +// If this [ClientHelloInfo] was passed to a GetConfigForClient or GetCertificate +// callback, this method will take into account the associated [Config]. Note that +// if GetConfigForClient returns a different [Config], the change can't be // accounted for by this method. // // This function will call x509.ParseCertificate unless c.Leaf is set, which can @@ -1475,7 +1475,7 @@ type lruSessionCacheEntry struct { state *ClientSessionState } -// NewLRUClientSessionCache returns a ClientSessionCache with the given +// NewLRUClientSessionCache returns a [ClientSessionCache] with the given // capacity that uses an LRU strategy. If capacity is < 1, a default capacity // is used instead. func NewLRUClientSessionCache(capacity int) ClientSessionCache { @@ -1524,7 +1524,7 @@ func (c *lruSessionCache) Put(sessionKey string, cs *ClientSessionState) { c.m[sessionKey] = elem } -// Get returns the ClientSessionState value associated with a given key. It +// Get returns the [ClientSessionState] value associated with a given key. It // returns (nil, false) if no value is found. func (c *lruSessionCache) Get(sessionKey string) (*ClientSessionState, bool) { c.Lock() diff --git a/conn.go b/conn.go index a12d495..6668e32 100644 --- a/conn.go +++ b/conn.go @@ -141,21 +141,21 @@ func (c *Conn) RemoteAddr() net.Addr { } // SetDeadline sets the read and write deadlines associated with the connection. -// A zero value for t means Read and Write will not time out. +// A zero value for t means [Conn.Read] and [Conn.Write] will not time out. // After a Write has timed out, the TLS state is corrupt and all future writes will return the same error. func (c *Conn) SetDeadline(t time.Time) error { return c.conn.SetDeadline(t) } // SetReadDeadline sets the read deadline on the underlying connection. -// A zero value for t means Read will not time out. +// A zero value for t means [Conn.Read] will not time out. func (c *Conn) SetReadDeadline(t time.Time) error { return c.conn.SetReadDeadline(t) } // SetWriteDeadline sets the write deadline on the underlying connection. -// A zero value for t means Write will not time out. -// After a Write has timed out, the TLS state is corrupt and all future writes will return the same error. +// A zero value for t means [Conn.Write] will not time out. +// After a [Conn.Write] has timed out, the TLS state is corrupt and all future writes will return the same error. func (c *Conn) SetWriteDeadline(t time.Time) error { return c.conn.SetWriteDeadline(t) } @@ -1237,10 +1237,10 @@ var ( // Write writes data to the connection. // -// As Write calls Handshake, in order to prevent indefinite blocking a deadline -// must be set for both Read and Write before Write is called when the handshake -// has not yet completed. See SetDeadline, SetReadDeadline, and -// SetWriteDeadline. +// As Write calls [Conn.Handshake], in order to prevent indefinite blocking a deadline +// must be set for both [Conn.Read] and Write before Write is called when the handshake +// has not yet completed. See [Conn.SetDeadline], [Conn.SetReadDeadline], and +// [Conn.SetWriteDeadline]. func (c *Conn) Write(b []byte) (int, error) { // interlock with Close below for { @@ -1412,10 +1412,10 @@ func (c *Conn) handleKeyUpdate(keyUpdate *keyUpdateMsg) error { // Read reads data from the connection. // -// As Read calls Handshake, in order to prevent indefinite blocking a deadline -// must be set for both Read and Write before Read is called when the handshake -// has not yet completed. See SetDeadline, SetReadDeadline, and -// SetWriteDeadline. +// As Read calls [Conn.Handshake], in order to prevent indefinite blocking a deadline +// must be set for both Read and [Conn.Write] before Read is called when the handshake +// has not yet completed. See [Conn.SetDeadline], [Conn.SetReadDeadline], and +// [Conn.SetWriteDeadline]. func (c *Conn) Read(b []byte) (int, error) { if err := c.Handshake(); err != nil { return 0, err @@ -1499,7 +1499,7 @@ var errEarlyCloseWrite = errors.New("tls: CloseWrite called before handshake com // CloseWrite shuts down the writing side of the connection. It should only be // called once the handshake has completed and does not call CloseWrite on the -// underlying connection. Most callers should just use Close. +// underlying connection. Most callers should just use [Conn.Close]. func (c *Conn) CloseWrite() error { if !c.isHandshakeComplete.Load() { return errEarlyCloseWrite @@ -1527,10 +1527,10 @@ func (c *Conn) closeNotify() error { // protocol if it has not yet been run. // // Most uses of this package need not call Handshake explicitly: the -// first Read or Write will call it automatically. +// first [Conn.Read] or [Conn.Write] will call it automatically. // // For control over canceling or setting a timeout on a handshake, use -// HandshakeContext or the Dialer's DialContext method instead. +// [Conn.HandshakeContext] or the [Dialer]'s DialContext method instead. // // In order to avoid denial of service attacks, the maximum RSA key size allowed // in certificates sent by either the TLS server or client is limited to 8192 @@ -1549,7 +1549,7 @@ func (c *Conn) Handshake() error { // connection. // // Most uses of this package need not call HandshakeContext explicitly: the -// first Read or Write will call it automatically. +// first [Conn.Read] or [Conn.Write] will call it automatically. func (c *Conn) HandshakeContext(ctx context.Context) error { // Delegate to unexported method for named return // without confusing documented signature. diff --git a/quic.go b/quic.go index baaad01..ed046bc 100644 --- a/quic.go +++ b/quic.go @@ -46,7 +46,7 @@ type QUICConn struct { sessionTicketSent bool } -// A QUICConfig configures a QUICConn. +// A QUICConfig configures a [QUICConn]. type QUICConfig struct { TLSConfig *Config } @@ -164,7 +164,7 @@ func newQUICConn(conn *Conn) *QUICConn { } // Start starts the client or server handshake protocol. -// It may produce connection events, which may be read with NextEvent. +// It may produce connection events, which may be read with [QUICConn.NextEvent]. // // Start must be called at most once. func (q *QUICConn) Start(ctx context.Context) error { @@ -183,7 +183,7 @@ func (q *QUICConn) Start(ctx context.Context) error { } // NextEvent returns the next event occurring on the connection. -// It returns an event with a Kind of QUICNoEvent when no events are available. +// It returns an event with a Kind of [QUICNoEvent] when no events are available. func (q *QUICConn) NextEvent() QUICEvent { qs := q.conn.quic if last := qs.nextEvent - 1; last >= 0 && len(qs.events[last].Data) > 0 { @@ -215,7 +215,7 @@ func (q *QUICConn) Close() error { } // HandleData handles handshake bytes received from the peer. -// It may produce connection events, which may be read with NextEvent. +// It may produce connection events, which may be read with [QUICConn.NextEvent]. func (q *QUICConn) HandleData(level QUICEncryptionLevel, data []byte) error { c := q.conn if c.in.level != level { @@ -259,7 +259,7 @@ type QUICSessionTicketOptions struct { } // SendSessionTicket sends a session ticket to the client. -// It produces connection events, which may be read with NextEvent. +// It produces connection events, which may be read with [QUICConn.NextEvent]. // Currently, it can only be called once. func (q *QUICConn) SendSessionTicket(opts QUICSessionTicketOptions) error { c := q.conn @@ -284,7 +284,7 @@ func (q *QUICConn) ConnectionState() ConnectionState { // SetTransportParameters sets the transport parameters to send to the peer. // // Server connections may delay setting the transport parameters until after -// receiving the client's transport parameters. See QUICTransportParametersRequired. +// receiving the client's transport parameters. See [QUICTransportParametersRequired]. func (q *QUICConn) SetTransportParameters(params []byte) { if params == nil { params = []byte{} diff --git a/ticket.go b/ticket.go index 5a51eeb..cc9e68d 100644 --- a/ticket.go +++ b/ticket.go @@ -305,7 +305,7 @@ func (c *Conn) sessionState() (*SessionState, error) { }, nil } -// EncryptTicket encrypts a ticket with the Config's configured (or default) +// EncryptTicket encrypts a ticket with the [Config]'s configured (or default) // session ticket keys. It can be used as a [Config.WrapSession] implementation. func (c *Config) EncryptTicket(cs ConnectionState, ss *SessionState) ([]byte, error) { ticketKeys := c.ticketKeys(nil) diff --git a/tls.go b/tls.go index 4603082..b0c23d7 100644 --- a/tls.go +++ b/tls.go @@ -395,7 +395,7 @@ func (l *listener) Accept() (net.Conn, error) { } // NewListener creates a Listener which accepts connections from an inner -// Listener and wraps each connection with Server. +// Listener and wraps each connection with [Server]. // The configuration config must be non-nil and must include // at least one certificate or else set GetCertificate. func NewListener(inner net.Listener, config *Config) net.Listener { @@ -453,10 +453,10 @@ func (timeoutError) Temporary() bool { return true } // handshake as a whole. // // DialWithDialer interprets a nil configuration as equivalent to the zero -// configuration; see the documentation of Config for the defaults. +// configuration; see the documentation of [Config] for the defaults. // // DialWithDialer uses context.Background internally; to specify the context, -// use Dialer.DialContext with NetDialer set to the desired dialer. +// use [Dialer.DialContext] with NetDialer set to the desired dialer. func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error) { return dial(context.Background(), dialer, network, addr, config) } @@ -533,10 +533,10 @@ type Dialer struct { // Dial connects to the given network address and initiates a TLS // handshake, returning the resulting TLS connection. // -// The returned Conn, if any, will always be of type *Conn. +// The returned [Conn], if any, will always be of type *[Conn]. // // Dial uses context.Background internally; to specify the context, -// use DialContext. +// use [Dialer.DialContext]. func (d *Dialer) Dial(network, addr string) (net.Conn, error) { return d.DialContext(context.Background(), network, addr) } @@ -556,7 +556,7 @@ func (d *Dialer) netDialer() *net.Dialer { // connected, any expiration of the context will not affect the // connection. // -// The returned Conn, if any, will always be of type *Conn. +// The returned [Conn], if any, will always be of type *[Conn]. func (d *Dialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error) { c, err := dial(ctx, d.netDialer(), network, addr, d.Config) if err != nil {