From b37629b885a82de70794262c31733a8fe813346f Mon Sep 17 00:00:00 2001 From: fangdingjun Date: Fri, 6 Jul 2018 13:55:52 +0800 Subject: [PATCH] update doc --- certificate.go | 11 ++++++----- doc.go | 15 ++++++++++----- hash.go | 24 ++++++++++++++---------- tls.go | 45 ++++++++++++++++++++++++++++----------------- 4 files changed, 58 insertions(+), 37 deletions(-) diff --git a/certificate.go b/certificate.go index c066e14..5550330 100644 --- a/certificate.go +++ b/certificate.go @@ -60,7 +60,8 @@ func (c *Certificate) buildNames() { } } -// CommonName get CN field in subject +// CommonName get CN field in subject, +// // example: subject C=xx,ST=bbb,CN=abc will return abc func (c *Certificate) CommonName() string { return c.commonName(0) @@ -102,7 +103,7 @@ func (c *Certificate) getAltName(index int, nameindex int) string { return string(name) } -//GetCertString get cert info string +//GetCertString return certificate info string in one line func (c *Certificate) GetCertString() string { return c.getCertString(0, 1) } @@ -119,7 +120,7 @@ func (c *Certificate) getCertString(index int, flag int) string { return string(s) } -// GetDN get the subject like O=st,C=aa,CN=localhost +// GetDN get the certificate subject, like O=st,C=aa,CN=localhost func (c *Certificate) GetDN() string { return c.getDN(0) } @@ -136,7 +137,7 @@ func (c *Certificate) getDN(index int) string { return string(s) } -// GetIssuerDN get the issuer's subject like O=st,C=ac,CN=localhost +// GetIssuerDN get the certificate issuer's subject, like O=st,C=ac,CN=localhost func (c *Certificate) GetIssuerDN() string { return c.getIssuerDN(0) } @@ -154,7 +155,7 @@ func (c *Certificate) getIssuerDN(index int) string { } // LoadX509KeyPair load certificate pair, -// the return Certifciate must be freed by call Free() +// the return Certifciate must be freed by call Free(), func LoadX509KeyPair(certfile, keyfile string) (*Certificate, error) { _certfile := C.CString(certfile) _keyfile := C.CString(keyfile) diff --git a/doc.go b/doc.go index 0aaeb66..25a7c13 100644 --- a/doc.go +++ b/doc.go @@ -24,11 +24,14 @@ TLS client example: } TLS Server example: - + cert, err := gnutls.LoadX509KeyPair("testdata/server/crt", "testdata/server.key") + if err != nil{ + // handle error + } l, err := gnults.Listen("tcp", "127.0.0.1:9443", &gnutls.Config{ - CrtFile: "testdata/server.crt", KeyFile: "testdata/server.key"}) + Certificates: []*gnutls.Certificate{cert}}) if err != nil { - t.Fatal("gnutls listen ", err) + // handle error } defer l.Close() for { @@ -78,13 +81,15 @@ AES encrypt/decrypt example: } // encrypt - cdata, err := c.Encrypt(data) + dst := make([]byte, len(data)) + err := c.Encrypt(dst, data) if err != nil { t.Fatal("encrypt failed", err) } // decrypt - data1, err := c1.Decrypt(cdata) + data1 := make([]byte, len(data)) + err := c1.Decrypt(data1, cdata) if err != nil { t.Fatal("decrypt failed", err) } diff --git a/hash.go b/hash.go index 849d358..65776ea 100644 --- a/hash.go +++ b/hash.go @@ -9,25 +9,28 @@ import ( "fmt" ) +// HashType hash type +type HashType int + const ( - GNUTLS_HASH_MD5 = 2 - GNUTLS_HASH_SHA1 = 3 - GNUTLS_HASH_MD2 = 5 - GNUTLS_HASH_SHA256 = 6 - GNUTLS_HASH_SHA384 = 7 - GNUTLS_HASH_SHA512 = 8 - GNUTLS_HASH_SHA224 = 9 + GNUTLS_HASH_MD5 HashType = 2 + GNUTLS_HASH_SHA1 HashType = 3 + GNUTLS_HASH_MD2 HashType = 5 + GNUTLS_HASH_SHA256 HashType = 6 + GNUTLS_HASH_SHA384 HashType = 7 + GNUTLS_HASH_SHA512 HashType = 8 + GNUTLS_HASH_SHA224 HashType = 9 ) // Hash hash struct type Hash struct { hash C.gnutls_hash_hd_t - t int + t HashType hashLen C.int } // NewHash new hash struct -func NewHash(t int) *Hash { +func NewHash(t HashType) *Hash { h := C.new_hash(C.int(t)) hashOutLen := GetHashOutputLen(t) return &Hash{h, t, C.int(hashOutLen)} @@ -70,7 +73,8 @@ func (h *Hash) Close() error { } // GetHashOutputLen get the hash algorithm output length +// // example GNUTLS_MD5 is 16 -func GetHashOutputLen(t int) int { +func GetHashOutputLen(t HashType) int { return int(C.gnutls_hash_get_len(C.gnutls_digest_algorithm_t(t))) } diff --git a/tls.go b/tls.go index ce35209..627a212 100644 --- a/tls.go +++ b/tls.go @@ -20,7 +20,8 @@ const ( GNUTLS_ALPN_SERVER_PRECEDENCE = 1 << 1 ) -// Conn tls connection for client +// Conn gnutls TLS connection, +// use Listen, Dial, NewServerConn or NewClientConn create this object type Conn struct { c net.Conn handshake bool @@ -30,7 +31,7 @@ type Conn struct { cfg *Config } -// Config tls configure +// Config gnutls TLS configure, type Config struct { ServerName string Certificates []*Certificate @@ -38,7 +39,7 @@ type Config struct { NextProtos []string } -// ConnectionState connection state +// ConnectionState gnutls TLS connection state type ConnectionState struct { // SNI name client send ServerName string @@ -48,7 +49,8 @@ type ConnectionState struct { // TLS version number, ex: 0x303 Version uint16 // TLS version number, ex: TLS1.0 - VersionName string + VersionName string + // peer's certificate PeerCertificate *Certificate } @@ -76,7 +78,7 @@ func (l *listener) Addr() net.Addr { return l.l.Addr() } -// Dial create a new connection +// Dial dial to (network, addr) and create a gnutls Conn func Dial(network, addr string, cfg *Config) (*Conn, error) { c, err := net.Dial(network, addr) if err != nil { @@ -85,7 +87,7 @@ func Dial(network, addr string, cfg *Config) (*Conn, error) { return NewClientConn(c, cfg) } -// Listen create a listener +// Listen create a gnutls listener on (network, addr), func Listen(network, addr string, cfg *Config) (net.Listener, error) { if cfg == nil { return nil, fmt.Errorf("config is need") @@ -97,7 +99,7 @@ func Listen(network, addr string, cfg *Config) (net.Listener, error) { return &listener{l, cfg}, nil } -// NewServerConn create a server Conn +// NewServerConn create a server TLS Conn on c func NewServerConn(c net.Conn, cfg *Config) (*Conn, error) { var sess = C.init_server_session() conn := &Conn{c: c, sess: sess, cfg: cfg} @@ -114,7 +116,7 @@ func NewServerConn(c net.Conn, cfg *Config) (*Conn, error) { return conn, nil } -// NewClientConn create a new gnutls connection +// NewClientConn create a client TLS Conn on c func NewClientConn(c net.Conn, cfg *Config) (*Conn, error) { var sess = C.init_client_session() conn := &Conn{c: c, sess: sess, cfg: cfg} @@ -167,7 +169,8 @@ func setAlpnProtocols(sess *C.struct_session, cfg *Config) error { } -// Handshake handshake tls +// Handshake call handshake for TLS Conn, +// this function will call automatic on Read/Write, if not handshake yet func (c *Conn) Handshake() error { if c.handshake { return nil @@ -181,7 +184,7 @@ func (c *Conn) Handshake() error { return nil } -// Read read data from tls connection +// Read read application data from TLS connection func (c *Conn) Read(buf []byte) (n int, err error) { if !c.handshake { err = c.Handshake() @@ -211,7 +214,7 @@ func (c *Conn) Read(buf []byte) (n int, err error) { return n, nil } -// Write write data to tls connection +// Write write application data to TLS connection func (c *Conn) Write(buf []byte) (n int, err error) { if !c.handshake { err = c.Handshake() @@ -238,7 +241,7 @@ func (c *Conn) Write(buf []byte) (n int, err error) { return n, nil } -// Close close the conn and destroy the tls context +// Close close the TLS conn and destroy the tls context func (c *Conn) Close() error { C.gnutls_record_send(c.sess.session, nil, 0) C.session_destroy(c.sess) @@ -278,7 +281,7 @@ func (c *Conn) SetDeadline(t time.Time) error { return c.c.SetDeadline(t) } -// ConnectionState report connection state +// ConnectionState get TLS connection state func (c *Conn) ConnectionState() *ConnectionState { if c.state != nil { return c.state @@ -338,7 +341,8 @@ func (c *Conn) getServerName() string { return name } -// OnDataReadCallback c callback function for data read +// OnDataReadCallback callback function for gnutls library want to read data from network +// //export OnDataReadCallback func OnDataReadCallback(d unsafe.Pointer, cbuf *C.char, bufLen C.int) C.int { //log.Println("read addr ", uintptr(d)) @@ -356,7 +360,8 @@ func OnDataReadCallback(d unsafe.Pointer, cbuf *C.char, bufLen C.int) C.int { return C.int(n) } -// OnDataWriteCallback c callback function for data write +// OnDataWriteCallback callback function for gnutls library want to send data to network +// //export OnDataWriteCallback func OnDataWriteCallback(d unsafe.Pointer, cbuf *C.char, bufLen C.int) C.int { //log.Println("write addr ", uintptr(d), int(_l)) @@ -370,14 +375,20 @@ func OnDataWriteCallback(d unsafe.Pointer, cbuf *C.char, bufLen C.int) C.int { return C.int(n) } -// OnDataTimeoutRead c callback function for timeout read +// OnDataTimeoutRead callback function for timeout read +// //export OnDataTimeoutRead func OnDataTimeoutRead(d unsafe.Pointer, delay C.int) C.int { log.Println("timeout pull function") return 0 } -// OnCertSelectCallback callback function for ceritificate select +// OnCertSelectCallback callback function for ceritificate select, +// this function select certificate from Config.Certificates field, +// +// on server side, this function select the certificate depend on SNI what client send, +// if client not send SNI, select the Config.Certificates[0] +// //export OnCertSelectCallback func OnCertSelectCallback(ptr unsafe.Pointer, hostname *C.char, namelen C.int, pcertLength *C.int, cert **C.gnutls_pcert_st, privkey *C.gnutls_privkey_t) C.int {