Documentation ¶
Index ¶
- Constants
- func AlertCN(code uint8) string
- func CipherSuiteName(id uint16) string
- func HandshakeMessageTypeName(id uint8) string
- func Listen(network, laddr string, config *Config) (net.Listener, error)
- func NewListener(inner net.Listener, config *Config) net.Listener
- type Certificate
- type CertificateRequestInfo
- type CertificateVerificationError
- type CipherSuite
- type ClientAuthType
- type ClientHelloInfo
- type Config
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) CloseWrite() error
- func (c *Conn) ConnectionState() ConnectionState
- func (c *Conn) Handshake() error
- func (c *Conn) HandshakeContext(ctx context.Context) error
- func (c *Conn) IsClient() bool
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) NetConn() net.Conn
- func (c *Conn) PeerCertificates() []*x509.Certificate
- func (c *Conn) Read(b []byte) (int, error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) VerifyHostname(host string) error
- func (c *Conn) Write(b []byte) (int, error)
- type ConnectionState
- type CurveID
- type Dialer
- type RecordHeaderError
- type SM2KeyAgreement
- type SessionCache
- type SessionState
- type SignatureAlgorithm
Constants ¶
const ( TLCP_ECDHE_SM4_CBC_SM3 uint16 = 0xe011 TLCP_ECDHE_SM4_GCM_SM3 uint16 = 0xe051 TLCP_ECC_SM4_CBC_SM3 uint16 = 0xe013 TLCP_ECC_SM4_GCM_SM3 uint16 = 0xe053 TLCP_IBSDH_SM4_CBC_SM3 uint16 = 0xe015 TLCP_IBSDH_SM4_GCM_SM3 uint16 = 0xe055 TLCP_IBC_SM4_CBC_SM3 uint16 = 0xe017 TLCP_IBC_SM4_GCM_SM3 uint16 = 0xe057 TLCP_RSA_SM4_CBC_SM3 uint16 = 0xe019 TLCP_RSA_SM4_GCM_SM3 uint16 = 0xe059 TLCP_RSA_SM4_CBC_SHA256 uint16 = 0xe01e TLCP_RSA_SM4_GCM_SHA256 uint16 = 0xe05a // // 常量命名与 GBT 38636-2020 6.4.5.2.1 保持一致 // ECDHE_SM4_CBC_SM3 uint16 = 0xe011 ECDHE_SM4_GCM_SM3 uint16 = 0xe051 ECC_SM4_CBC_SM3 uint16 = 0xe013 ECC_SM4_GCM_SM3 uint16 = 0xe053 IBSDH_SM4_CBC_SM3 uint16 = 0xe015 IBSDH_SM4_GCM_SM3 uint16 = 0xe055 IBC_SM4_CBC_SM3 uint16 = 0xe017 IBC_SM4_GCM_SM3 uint16 = 0xe057 RSA_SM4_CBC_SM3 uint16 = 0xe019 RSA_SM4_GCM_SM3 uint16 = 0xe059 RSA_SM4_CBC_SHA256 uint16 = 0xe01e RSA_SM4_GCM_SHA256 uint16 = 0xe05a )
密码套件ID,见 GB/T 38636-2016 6.4.5.2.1 表 2 密码套件列表
const (
VersionTLCP = 0x0101 // GM/T 38636-2016
)
Variables ¶
This section is empty.
Functions ¶
func CipherSuiteName ¶
CipherSuiteName 通过密码套件ID返还密码套件的标准名称。 (如: "ECC_SM4_CBC_SM3")
func HandshakeMessageTypeName ¶ added in v1.2.4
Types ¶
type Certificate ¶
type Certificate struct { // Certificate DER编码的X.509数字证书,在TLCP协议中该数组只会存在1张证书。(无证书链) // Certificate 中的元素可以使用 smx509.ParseCertificate 方法解析为 *smx509.Certificate Certificate [][]byte // PrivateKey 私钥实现,根据密钥用法的不同 // 签名密钥对需要实现 crypto.Signer 接口 // 加密密钥对需要实现 crypto.Decrypter 接口 PrivateKey crypto.PrivateKey // Leaf 握手x509证书对象,默认为空 // // 可以通过 smx509.ParseCertificate 解析 Certificate.Certificate 中的第一个元素解析设置, // 通过该种方式可以减少在握手环节的证书解析的时间。 Leaf *x509.Certificate }
Certificate 密钥对以及相关的数字证书
func LoadX509KeyPair ¶
func LoadX509KeyPair(certFile, keyFile string) (Certificate, error)
LoadX509KeyPair 从文件中读取证书和密钥对,并解析 PEM编码的数字证书、公私钥对。
func X509KeyPair ¶
func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (Certificate, error)
X509KeyPair 解析 PEM编码的数字证书、公私钥对。
type CertificateRequestInfo ¶
type CertificateRequestInfo struct { // AcceptableCAs 包含0或多个的 DER编码的 X.509 DN名称 // 这些DN名称来自于服务端信任的根证书列表,客户端应根据这些DN名称选择合适的数字证书 AcceptableCAs [][]byte // Version TLCP协议版本 Version uint16 // contains filtered or unexported fields }
CertificateRequestInfo 服务端的证书请求信息
func (*CertificateRequestInfo) Context ¶
func (c *CertificateRequestInfo) Context() context.Context
Context 返回握手过程中的上下文
func (*CertificateRequestInfo) SupportsCertificate ¶
func (cri *CertificateRequestInfo) SupportsCertificate(c *Certificate) error
SupportsCertificate returns nil if the provided certificate is supported by the server that sent the CertificateRequest. Otherwise, it returns an error describing the reason for the incompatibility.
type CertificateVerificationError ¶ added in v1.2.6
type CertificateVerificationError struct { // UnverifiedCertificates and its contents should not be modified. UnverifiedCertificates []*x509.Certificate Err error }
CertificateVerificationError is returned when certificate verification fails during the handshake.
func (*CertificateVerificationError) Error ¶ added in v1.2.6
func (e *CertificateVerificationError) Error() string
func (*CertificateVerificationError) Unwrap ¶ added in v1.2.6
func (e *CertificateVerificationError) Unwrap() error
type CipherSuite ¶
type CipherSuite struct { ID uint16 Name string // 该套件支持的TLCP协议版本 SupportedVersions []uint16 // Insecure 为true表示该套件是已经具有安全问题的密码套件 Insecure bool }
CipherSuite 密码套件
在该程序库中大部分方法都只接受密码套件的ID而不是该对象
func InsecureCipherSuites ¶
func InsecureCipherSuites() []*CipherSuite
InsecureCipherSuites 已知的不安全的密码套件列表
type ClientAuthType ¶
type ClientAuthType int
ClientAuthType 服务端对客户单的认证策略,用于客户端身份认证配置
const ( // NoClientCert indicates that no client certificate should be requested // during the handshake, and if any certificates are sent they will not // be verified. NoClientCert ClientAuthType = iota // RequestClientCert indicates that a client certificate should be requested // during the handshake, but does not require that the client send any // certificates. RequestClientCert // RequireAnyClientCert indicates that a client certificate should be requested // during the handshake, and that at least one certificate is required to be // sent by the client, but that certificate is not required to be valid. RequireAnyClientCert // VerifyClientCertIfGiven indicates that a client certificate should be requested // during the handshake, but does not require that the client sends a // certificate. If the client does send a certificate it is required to be // valid. VerifyClientCertIfGiven // RequireAndVerifyClientCert indicates that a client certificate should be requested // during the handshake, and that at least one valid certificate is required // to be sent by the client. RequireAndVerifyClientCert // RequireAndVerifyAnyKeyUsageClientCert 要求客户端提供客户端数字证书,并且验证数字证书,但是忽略客户端数字证书的密钥用法。 RequireAndVerifyAnyKeyUsageClientCert )
type ClientHelloInfo ¶
type ClientHelloInfo struct { // CipherSuites 客户端支持的密码套件ID列表 CipherSuites []uint16 // ServerName indicates the name of the server requested by the client // in order to support virtual hosting. ServerName is only set if the // client is using SNI (see RFC 4366, Section 3.1). ServerName string // SupportedVersions 客户端支持的TLCP版本,目前只有 0x0101 SupportedVersions []uint16 // Conn 底层连接对象,请不要读写该对象,否则会导致TLCP连接异常 Conn net.Conn // contains filtered or unexported fields }
ClientHelloInfo contains information from a ClientHello message in order to guide application logic in the GetCertificate and GetConfigForClient callbacks.
func (*ClientHelloInfo) Context ¶
func (c *ClientHelloInfo) Context() context.Context
Context 返回握手过程中的上下文
type Config ¶
type Config struct { // Rand 外部随机源,若不配置则默认使用 crypto/rand 作为随机源 // 随机源必须线程安全,能够被多goroutines访问。 Rand io.Reader // Time 外部时间源,返回当前的时间 Time func() time.Time // Certificates TLCP握手过程中的证书密钥对,数组中每一个元素表示一对密钥以及一张证书 // // TLCP协议中服务端需要2对密钥对,1对签名密钥对和签名证书、1对加密密钥对和加密证书, // TLCP协议中客户端在需要身份认证的场景下也需要1对签名密钥对和签名证书。 // // 服务端:至少2对密钥对和证书,按照顺序[签名密钥对, 加密密钥对] // 客户端:若不需要客户端身份认证则可以为空,否则至少1对密钥对。 // // 特别的也可以使用动态方法获取证书,使该参数为空 // 服务端需实现: GetCertificate GetKECertificate // 客户端需实现: GetClientCertificate Certificates []Certificate // GetCertificate 仅在 Certificates 为空时, // 基于客户端Hello消息返还密钥对和证书 GetCertificate func(*ClientHelloInfo) (*Certificate, error) // GetKECertificate 获取密钥交换证书(加密证书) // 这个方法只有在使用Config中Certificates为空或长度小于2时,才会被调用。 // 如果该方法为空,则默认从证书列表中 Certificates 取出第二个位置的证书,也就是加密证书。 // 该方法只有TLCP流程中才会调用。 GetKECertificate func(*ClientHelloInfo) (*Certificate, error) // GetClientCertificate 根据服务端的证书请求消息,返回客户端用于认证的密钥和证书 // // 如果 GetClientCertificate 返回空那么连接将会被中断,因此即便没有证书和密钥对 // 也需要返回一个空的 Certificate 对象,这样客户端可以发送一个空的证书消息给服务端。 GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error) // GetClientKECertificate 根据服务端的证书请求消息,返回客户端用于密钥交换的密钥和证书 // 如果客户端想要支持ECDHE,就必须要同时提供签名和加密证书。 GetClientKECertificate func(*CertificateRequestInfo) (*Certificate, error) // GetConfigForClient 【可选】 根据客户端Hello消息,生成TLCP配置对象 // 如果该方法不为空,将会在接受到客户端的 ClientHello 消息后调用。 // // 通过该方法你可以在针对该次连接生成自定义的配置对象来完成特殊的应用需要。 GetConfigForClient func(*ClientHelloInfo) (*Config, error) // VerifyPeerCertificate 【可选】 验证对端证书 // 若改参数不为空,将会在客户端或服务端的证书验证结束阶段后被调用。 // // 该方法接收 rawCerts 对端发来的 原始的 ASN.1(DER) 的证书序列 // 以及 verifiedChains 验证该证书相关的根证书链序列 // // InsecureSkipVerify 与 ClientAuth 参数不会影响该函数运行。 VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error // VerifyConnection 【可选】如果该方法不会空,那么将会在证书验证完成后, // 如果 VerifyPeerCertificate 存在则会在其后运行 // 在该方法中您可以对连接上下文中的相关参数进行校验 如提取对端数字证书信息、所使用的密码套件等。 // // 如果该方法返回值不为空,将会终止握手。 // // InsecureSkipVerify 与 ClientAuth 的设置不会影响该方法的运行。 VerifyConnection func(ConnectionState) error // RootCAs 根证书列表,客户端使用该列表的证书验证服务端证书是否有效 // 如果这个字段为空,则使用主机上的根证书集合(从操作系统中加载) RootCAs *x509.CertPool // ServerName 【可选】如果不为空,则强制校验证书中的DNS或IP是否存在。 // 用于验证主机名与数字证书中的主机名是否匹配 // 如果 InsecureSkipVerify 为 true 则跳过该验证 ServerName string // ClientAuth 服务端对客户端身份认证策略 // 默认值为 NoClientCert 不验证客户端身份 ClientAuth ClientAuthType // ClientCAs 服务端侧根证书列表,这些根证书将用于验证客户端证书消息中的证书 // 客户端证书的验证策略由 ClientAuth 参数配置。 ClientCAs *x509.CertPool // InsecureSkipVerify 用于控制客户端是否跳过 服务端的证书有效性 和 证书与主机名 的匹配。 // // 如果 InsecureSkipVerify 参数为 true,那么客户端不对服务端证书做任何验证,注意在这种模式下 // TLCP容易受到中间人攻击,这个配置仅用于测试。 // // 若您配置了 VerifyConnection 或 VerifyPeerCertificate 可以根据情况设置该参数为 true InsecureSkipVerify bool // CipherSuites 密码套件ID列表,用于手动指定在握手过程中的密码套件 // 数组约靠前的密码套件优先级越高。 // // 如果 CipherSuites 为 nil,那么使用默认的算法套件列表进行握手。 CipherSuites []uint16 // SessionCache 会话状态缓存,用于连接重用 // // 若需要开启服务端或客户端的重用握手流程,则请配置该参数。 // 若无特殊缓存需要可采用默认的 NewLRUSessionCache 实现会话缓存 SessionCache SessionCache // MinVersion 最低支持的TLCP协议版本,目前TLCP只有一个版本 MinVersion uint16 // MaxVersion 最高支持的TLCP协议版本,目前TLCP只有一个版本 MaxVersion uint16 // DynamicRecordSizingDisabled disables adaptive sizing of TLS records. // When true, the largest possible TLS record size is always used. When // false, the size of TLS records may be adjusted in an attempt to // improve latency. DynamicRecordSizingDisabled bool // OnAlert 在发生报警时回调该方法,在该方法内请不要执行耗时操作! OnAlert func(code uint8, conn *Conn) // EnableDebug, 是否打开debug EnableDebug bool // ClientECDHEParamAsVector, 把ClientECDHEParams当作structure还是变长向量。 // 这个配置用于客户端使用ECDHE密码套件时与其他实现进行兼容,如果你在进行ECDHE密码套件的集成测试时失败,可以尝试配置这个变量。 // 默认当作structure,起始无两字节长度。 ClientECDHEParamsAsVector bool // contains filtered or unexported fields }
Config TLCP配置对象,用于配置TLCP客户端或服务端,一旦该参数被TLCP使用,那么 该参数内部的值不应在改变。
Config 根据情况可以复用。
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn 表示一个TLCP连接,实现了 net.Conn 接口
func DialWithDialer ¶
DialWithDialer 使用提供的 net.Dialer 对象,实现TLCP客户端握手,建立TLCP连接。
DialWithDialer 内使用 context.Background 上下文,若您需要指定自定义的上下文。 请在构造 Dialer 然后调用 Dialer.DialContext 方法设置。
func Server ¶
Server 使用现有连接对象构造一个新的TLCP服务端连接对象 配置参数对象 config 不能为空,且至少提供签名密钥对和加密密钥以及签名证书和加密证书 当然也可以通过 Config.GetCertificate与 Config.GetKECertificate以动态的方式获取相应密钥对于证书。
func (*Conn) CloseWrite ¶
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.
func (*Conn) ConnectionState ¶
func (c *Conn) ConnectionState() ConnectionState
ConnectionState returns basic TLS details about the connection.
func (*Conn) Handshake ¶
Handshake runs the client or server handshake 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.
For control over canceling or setting a timeout on a handshake, use HandshakeContext or the Dialer's DialContext method instead.
func (*Conn) HandshakeContext ¶
HandshakeContext runs the client or server handshake protocol if it has not yet been run.
The provided Context must be non-nil. If the context is canceled before the handshake is complete, the handshake is interrupted and an error is returned. Once the handshake has completed, cancellation of the context will not affect the connection.
Most uses of this package need not call HandshakeContext explicitly: the first Read or Write will call it automatically.
func (*Conn) PeerCertificates ¶ added in v1.3.2
func (c *Conn) PeerCertificates() []*x509.Certificate
PeerCertificates 对端证书列表
func (*Conn) Read ¶
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.
func (*Conn) SetDeadline ¶
SetDeadline 设置对连接 读取或写入 终止时间。 若 t 为0表示不会超时。 在超时后将会导致TLCP中断,后续的写入都将会返回同样的错误。
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the read deadline on the underlying connection. A zero value for t means Read will not time out.
func (*Conn) SetWriteDeadline ¶
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.
func (*Conn) VerifyHostname ¶
VerifyHostname checks that the peer certificate chain is valid for connecting to host. If so, it returns nil; if not, it returns an error describing the problem.
type ConnectionState ¶
type ConnectionState struct { // Version 连接的TLCP协议版本号 Version uint16 // HandshakeComplete true 表示完成握手 HandshakeComplete bool // DidResume true 表示这个连接是从之前的会话中重用了会话密钥 DidResume bool // CipherSuite 该连接所使用的密码套件ID CipherSuite uint16 // ServerName 服务端端名称 ServerName string // PeerCertificates 对端数字证书对象 // // 在客户端侧,改参数不会为空,表示服务端的签名证书和加密证书 // 在服务端侧,若 Config.ClientAuth 不为 RequireAnyClientCert 或 RequireAndVerifyClientCert 那么则可能为空。 PeerCertificates []*x509.Certificate // VerifiedChains 验证对端证书的证书链 // // 在客户端侧证书链中的证书来自于 Config.RootCAs // 在服务端侧证书链中的证书来自于 Config.ClientCAs // // 若启用了 Config.InsecureSkipVerify 参数则不会存在改参数。 VerifiedChains [][]*x509.Certificate }
ConnectionState 关于TLCP连接的详细信息
type CurveID ¶
type CurveID uint16
CurveID 命名曲线ID,ID由 IANA分配,详见 https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8.
const ( // CurveSM2 命名曲线ID 见 RFC 8998 第2章 // https://www.rfc-editor.org/rfc/rfc8998.html CurveSM2 CurveID = 41 )
type Dialer ¶
type Dialer struct { // NetDialer 可选择 可靠连接的拨号器,用于创建承载TLCP协议的底层连接对象。 // 若 NetDialer 为空,使用默认的 new(et.Dialer) 创建拨号器 NetDialer *net.Dialer // Config TLCP 配置信息,若为空则使用 空值的 Config{} Config *Config }
Dialer 通过所给的 net.Dialer 和 Config 配置信息,实现TLCP客户端握手的Dialer对象。
type RecordHeaderError ¶
type RecordHeaderError struct { // Msg 包含了人可读的错误描述信息 Msg string // RecordHeader 包含导致了该错误的 TLCP记录层头 5字节(byte) RecordHeader [5]byte // Conn 底层的连接对象 // 若已经有过一次握手或发送了报警消息,那么该参数可能为空。 Conn net.Conn }
RecordHeaderError 当TLCP记录层协议(record)的头非法时返回该错误。
func (RecordHeaderError) Error ¶
func (e RecordHeaderError) Error() string
type SM2KeyAgreement ¶
type SM2KeyAgreement interface { // GenerateAgreementData 发起方生成临时公钥,接口设计参考 GB/T 36322-2018 6.3.15 GenerateAgreementData(sponsorId []byte, keyLen int) (sponsorPubKey, sponsorTmpPubKey *ecdh.PublicKey, err error) // GenerateKey 发起方计算会话密钥,接口设计参考 GB/T 36322-2018 6.3.16 GenerateKey(responseId []byte, responsePubKey, responseTmpPubKey *ecdh.PublicKey) ([]byte, error) // GenerateAgreementDataAndKey 响应方计算会话密钥并返回临时公钥,接口设计参考 GB/T 36322-2018 6.3.17 GenerateAgreementDataAndKey(responseId, sponsorId []byte, sponsorPubKey, sponsorTmpPubKey *ecdh.PublicKey, keyLen int) (*ecdh.PublicKey, []byte, error) }
SM2KeyAgreement SM2密钥交换接口,接口设计参考 GB/T 36322-2018
type SessionCache ¶
type SessionCache interface { // Get 缓存中 sessionKey 的 SessionState,若不存在则 返回 ok false // // 特殊的若 sessionKey 为 "" 空串时,返回最近一个会话 Get(sessionKey string) (session *SessionState, ok bool) // Put 添加一个会话对象到缓存中 Put(sessionKey string, cs *SessionState) }
SessionCache 会话缓存器,用于缓存TLCP连接建立后的会话信息 SessionState 用于在 TLCP 协议的握手重用过程中提供会话相关的信息。
会话缓存器的实现应该考虑到多 goroutines 并发访问的问题。
func NewLRUSessionCache ¶
func NewLRUSessionCache(capacity int) SessionCache
NewLRUSessionCache 返回一个指定容量的 最近最少使用缓存(LRU)对象。 在缓存空间不足时,优先淘汰最近最少使用的缓存部分。
当 capacity 小于1时,使用默认容量 64
type SessionState ¶
type SessionState struct {
// contains filtered or unexported fields
}
SessionState 包含了TLCP会话相关的密码参数,用于会话重用
type SignatureAlgorithm ¶
type SignatureAlgorithm uint16
SignatureAlgorithm 签名算法 见 GB/T 38636-2016 6.4.5.9 Certificate Verify 消息
const ( NONE SignatureAlgorithm = 0 RSA_SHA256 SignatureAlgorithm = 1 RSA_SM3 SignatureAlgorithm = 2 ECC_SM3 SignatureAlgorithm = 3 IBS_SM3 SignatureAlgorithm = 4 )