openkey

README

This is a Go wrapper for the libopenkey. The wrapper ships its own copy of
the libopenkey that is based on the state of 2013-05-22. The code in this
wrapper is untested. Please use with caution.

The current release of this wrapper is release 0.2. Successive releases will be
placed in different subfolders as to not change the semantics of code that links
against a specific version of this wrapper. The general folder structure is

    github.com/fuzxxl/openkey/<version>/openkey

The following versions are special:

* latest always points to the latest version
* dev is the version that is currently under development

Copyright (c) 2014, Robert Clausecker <fuzxxl@gmail.com>

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

This project contains code from the libopenkey project. Its copyright notice
is reproduced below.

Copyright (C) 2013, Henryk Plötz
    
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>

Documentation

Overview

Go bindings for the libopenkey. These bindings use the libfreefare bindings from package github.com/clausecker/freefare. Please notice that these bindings ship their own copy of the libopenkey.

Index

• Constants
• func Kdf(masterKey []byte, aid uint32, keyNo byte, data, derivedKey []byte) error
• func Pbkdf(masterKey []byte, aid uint32, keyNo byte, data, pw []byte, iterations int, ...) error
• type Context
  • func New() Context
  • func (c Context) AddRole(role int, privateBasePath string) error
  • func (c Context) AuthenticateCard(tag freefare.DESFireTag, pw []byte) (cardId string, err error)
  • func (c Context) BootstrapManager(preferredSlot int) (bool, error)
  • func (c Context) BootstrapProducer() (bool, error)
  • func (c Context) Close() error
  • func (c Context) IsManagerBootstrapped() bool
  • func (c Context) IsProducerBootstrapped() bool
  • func (c Context) ManagerOwnCard(tag freefare.DESFireTag, slot int, keyFile string, pw []byte) error
  • func (c Context) PrepareAuthenticator() bool
  • func (c Context) ProducerCardCreate(tag freefare.DESFireTag, cardName string) error
  • func (c Context) ProducerCardRecreate(tag freefare.DESFireTag, cardName, oldId string) error
• type Error
  • func (e Error) Error() string

Constants

const (
	CardProducer = iota
	LockManager
	CardAuthenticator
)

Roles

Functions

func Kdf

func Kdf(masterKey []byte, aid uint32, keyNo byte, data, derivedKey []byte) error

This function wraps the function openkey_kdf(). As a side-effect, this function intializes the libgrypt as some of its functions are needed for this function.

func Pbkdf

func Pbkdf(
	masterKey []byte,
	aid uint32, keyNo byte,
	data, pw []byte,
	iterations int,
	derivedKey []byte,
) error

This function wraps the function openkey_pbkdf(). As a side-effect, this function intializes the libgcrypt as some of its functions are needed for this function.

Types

type Context

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

An openkey context. This type wraps openkey_context_t. Allocate an object of this type using the New() function.

func New

func New() Context

Create a new openkey context. This function wraps openkey_context_init(). If initialization of the context fails, this function panics. A context allocated with New() must be released after use with Close().

func (Context) AddRole

func (c Context) AddRole(role int, privateBasePath string) error

Add a role to an openkey context. For a description of the possible errors, have a look at libopenkey.c. There is no documentation but you can possibly figure out where your error came from if you look long enough.

func (Context) AuthenticateCard

func (c Context) AuthenticateCard(tag freefare.DESFireTag, pw []byte) (cardId string, err error)

Use a card for authentication. This function fails if no authenticator role has been added to the context. This function wraps openkey_authenticator_authenticate_pw(). To get the functionality of openkey_authenticator_authenticate(), pass nil for pw. This function may either return an Error object or any of the error objects freefare.Tag.TranslateError() may return; the wrapper automatically translates error codes to a freefare.Error if it finds that the error was produced by the libfreefare.

func (Context) BootstrapManager

func (c Context) BootstrapManager(preferredSlot int) (bool, error)

Bootstrap a manager role. This function returns true if the producer role of c had already been bootstrapped before.

func (Context) BootstrapProducer

func (c Context) BootstrapProducer() (bool, error)

Bootstrap a producer role. This function returns true if the producer role of c had already been bootstrapped before.

func (Context) Close

func (c Context) Close() error

Release an openkey context. This function wraps openkey_context_fini(). This function fails with an error iff the context has already been closed. It is save to ignore any errors coming from this function.

Usage of a context after Close() results in an error.

func (Context) IsManagerBootstrapped

func (c Context) IsManagerBootstrapped() bool

Has a manager role been bootstrapped? This function also returns false if c has already been closed.

func (Context) IsProducerBootstrapped

func (c Context) IsProducerBootstrapped() bool

Has a producer role been bootstrapped? This function also returns false if c has already been closed.

func (Context) ManagerOwnCard

func (c Context) ManagerOwnCard(tag freefare.DESFireTag, slot int, keyFile string, pw []byte) error

Own a card. This function wraps openkey_manager_card_own_pw(). To own a card without a password (as with openkey_manager_card_own()), pass nil for pw. This function may either return an Error object or any of the error objects freefare.Tag.TranslateError() may return; the wrapper automatically translates error codes to a freefare.Error if it finds that the error was produced by the libfreefare.

func (Context) PrepareAuthenticator

func (c Context) PrepareAuthenticator() bool

Figure out if a card has an authenticator role added. This function also returns false if c has already been closed. The name of this function is a bit strange and has been taken verbatim from the C code.

func (Context) ProducerCardCreate

func (c Context) ProducerCardCreate(tag freefare.DESFireTag, cardName string) error

Create an openkey card. This function may either return an Error object or any of the error objects freefare.Tag.TranslateError() may return; the wrapper automatically translates error codes to a freefare.Error if it finds that the error was produced by the libfreefare.

func (Context) ProducerCardRecreate

func (c Context) ProducerCardRecreate(tag freefare.DESFireTag, cardName, oldId string) error

Recreate an openkey card. This function may either return an Error object or any of the error objects freefare.Tag.TranslateError() may return; the wrapper automatically translates error codes for this function. Notice that since the implementation of openkey_producer_card_recreate() does not distinguish between different errors, the translation is a little bit inexact. Specifically, the translation routine looks for errno and translates the error code if errno is set. Since versions of the libfreefare up to 0.4.0 do not set errno on authentication failure, error reporting might be wrong.

type Error

type Error int

An error code caused by the libopenkey. This is usually the negated return value.

func (Error) Error

func (e Error) Error() string

Returns a human-readable string describing the error. The strings returned by this function are not guaranteed to remain stable.