yubigo

Yubigo is a Yubikey client API library that provides an easy way to integrate the Yubikey into any Go application.

Installation

Installation is simple. Use go get: go get github.com/GeertJohan/yubigo

Usage

Make sure to import the library: import "github.com/GeertJohan/yubigo"

For use with the default Yubico servers, make sure you have an API key. Request a key.

Basic OTP checking usage:

// create a new yubiAuth instance with id and key
yubiAuth, err := yubigo.NewYubiAuth("1234", "fdsaffqaf4vrc2q3cds=")
if err != nil {
	// probably an invalid key was given
	log.Fatalln(err)
}

// verify an OTP string
result, ok, err := yubiAuth.Verify("ccccccbetgjevivbklihljgtbenbfrefccveiglnjfbc")
if err != nil {
	log.Fatalln(err)
}

if ok {
	// succes!! The OTP is valid!
	log.Printf("Used query was: %s\n", result.GetRequestQuery()) // this query string includes the url of the api-server that responded first.
} else {
	// fail! The OTP is invalid or has been used before.
	log.Println("The given OTP is invalid!!!")
}

Use your own HTTP Client with fine-tuned config: While the library works out of the box, it's not recommended to use the default http client. It is better to configure your own http client with useful timeouts.

For example:

yubigo.HTTPClient = &http.Client{
    Timeout: time.Second * 15,
    Transport: &http.Transport{
        MaxConnsPerHost:     20,
        MaxIdleConnsPerHost: 5,
        DialContext: (&net.Dialer{
            Timeout:   30 * time.Second,
            KeepAlive: 60 * time.Second,
        }).DialContext,
        TLSHandshakeTimeout:   10 * time.Second,
        ResponseHeaderTimeout: 10 * time.Second,
        ExpectContinueTimeout: 1 * time.Second,
    },
}

Do not verify HTTPS certificate:

// Disable HTTPS cert verification. Use true to enable again.
yubiAuth.HttpsVerifyCertificate(false)

HTTP instead of HTTPS:

// Disable HTTPS. Use true to enable again.
yubiAuth.UseHttps(false)

Custom API server:

// Set a list of n servers, each server as host + path. 
// Do not prepend with protocol
yubiAuth.SetApiServerList("api0.server.com/api/verify", "api1.server.com/api/verify", "otherserver.com/api/verify")

Licence

This project is licensed under a Simplified BSD license. Please read the LICENSE file.

Todo

• Test files
• More documentation
• Getters/Setters for some options on the YubiAuth object.

Protocol & Package documentation

This project is implementing a pure-Go Yubico OTP Validation Client and is following the Yubico Validation Protocol Version 2.0.

You will find "go doc"-like package documentation at go.pkgdoc.org.