update doc

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)

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

hash.go

@@ -9,25 +9,28 @@ import (
 	"fmt"
 )
 
+// HashType hash type
+type HashType int
+
 const (
-	GNUTLS_HASH_MD5    = 2
+	GNUTLS_HASH_MD5    HashType = 2
-	GNUTLS_HASH_SHA1   = 3
+	GNUTLS_HASH_SHA1   HashType = 3
-	GNUTLS_HASH_MD2    = 5
+	GNUTLS_HASH_MD2    HashType = 5
-	GNUTLS_HASH_SHA256 = 6
+	GNUTLS_HASH_SHA256 HashType = 6
-	GNUTLS_HASH_SHA384 = 7
+	GNUTLS_HASH_SHA384 HashType = 7
-	GNUTLS_HASH_SHA512 = 8
+	GNUTLS_HASH_SHA512 HashType = 8
-	GNUTLS_HASH_SHA224 = 9
+	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)))
 }

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 {