yubigo

README

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.

Documentation

Index

• Variables
• func ParseOTP(otp string) (prefix string, ciphertext string, err error)
• type YubiAuth
  • func NewYubiAuth(id string, key string) (auth *YubiAuth, err error)
  • func NewYubiAuthDebug(id string, key string, debug bool) (auth *YubiAuth, err error)
  • func (ya *YubiAuth) GetApiServerList() []string
  • func (ya *YubiAuth) HttpsVerifyCertificate(verifyCertificate bool)
  • func (ya *YubiAuth) SetApiServerList(urls ...string)
  • func (ya *YubiAuth) UseHttps(useHttps bool)
  • func (ya *YubiAuth) Verify(otp string) (yr *YubiResponse, ok bool, err error)
• type YubiResponse
  • func (yr *YubiResponse) GetRequestQuery() string
  • func (yr *YubiResponse) GetResultParameter(key string) (value string)
  • func (yr *YubiResponse) IsValidOTP() bool

Variables

var HTTPClient *http.Client = nil

Package variable used to override the http client used for communication with Yubico. If nil the standard http.Client will be used - if overriding you need to ensure the transport options are set.

Functions

func ParseOTP

func ParseOTP(otp string) (prefix string, ciphertext string, err error)

Parse and verify the given OTP string into prefix (identity) and ciphertext. Function returns a non-nil error when given OTP is not in valid format. NOTE: This function does NOT verify if the OTP is correct and unused/unique.

Types

type YubiAuth

type YubiAuth struct {
	// contains filtered or unexported fields
}

func NewYubiAuth

func NewYubiAuth(id string, key string) (auth *YubiAuth, err error)

Create a yubiAuth instance with given API-id and API-key. Returns an error when the key could not be base64 decoded. To use yubigo with the Yubico Web Service (default api servers), create an API id+key here: https://upgrade.yubico.com/getapikey/ Debugging is disabled. For debugging: use NewYubiAuthDebug(..)

func NewYubiAuthDebug

func NewYubiAuthDebug(id string, key string, debug bool) (auth *YubiAuth, err error)

Create a yubiAuth instance for given API-id and API-key. Has third parameter `debug`. When debug is true this YubiAuth instance will spam the console with logging messages. Returns an error when the key could not be base64 decoded. To use yubigo with the Yubico Web Service (default api servers), create an API id+key here: https://upgrade.yubico.com/getapikey/

func (*YubiAuth) GetApiServerList

func (ya *YubiAuth) GetApiServerList() []string

Retrieve the the ist of servers that are being used for verification.

func (*YubiAuth) HttpsVerifyCertificate

func (ya *YubiAuth) HttpsVerifyCertificate(verifyCertificate bool)

Enable or disable https certificate verification Disable this at your own risk.

func (*YubiAuth) SetApiServerList

func (ya *YubiAuth) SetApiServerList(urls ...string)

Use this method to specify a list of servers for verification. Each server string should contain host + path. Example: "api.yubico.com/wsapi/2.0/verify".

func (*YubiAuth) UseHttps

func (ya *YubiAuth) UseHttps(useHttps bool)

Enable or disable the use of https

func (*YubiAuth) Verify

func (ya *YubiAuth) Verify(otp string) (yr *YubiResponse, ok bool, err error)

The verify method calls the API with given OTP and returns if the OTP is valid or not. This method will return an error if something unexpected happens If no error was returned, the returned 'ok bool' indicates if the OTP is valid if the 'ok bool' is true, additional informtion can be found in the returned YubiResponse object

type YubiResponse

type YubiResponse struct {
	// contains filtered or unexported fields
}

Contains details about yubikey OTP verification.

func (*YubiResponse) GetRequestQuery

func (yr *YubiResponse) GetRequestQuery() string

Get the requestQuery that was used during verification.

func (*YubiResponse) GetResultParameter

func (yr *YubiResponse) GetResultParameter(key string) (value string)

Retrieve a parameter from the api's response

func (*YubiResponse) IsValidOTP

func (yr *YubiResponse) IsValidOTP() bool

Returns wether the verification was successful