cbeff

README

go-cbeff

CBEFF, or the Common Biometric Exchange Formats Framework, is a propriatary standard used to store and sign biometric information. This is used most commonly with FIPS 201 PIV smartcards. This implements the out-of-date CBEFF spec that's used by Federal smartcards. This format is a legay and highly complex storage format, and it's main purpose is to extract information to common and interchangeable formats where possible.

Documentation

Overview

Package cbeff contains helpers to process CBEFF (Common Biometric Exchange Formats Framework) data. CBEFF is a set of ISO standards defining an approach to facilitate serialisation and sharing of biometric data in an implementation agnostic manner. This is achieved through use of a data structure which both describes, and contains, biometric data.

This format is most notibly used as part of the US Government's FIPS 201 PIV II smartcard.

Currently, only Facial support has been partially implemented, due to the paywalled documetation on large swaths of this encoding. This package has been implemented only based on freely avalible US Government provided examples of PIV II data and documentation. As such this may be incomplete or slightly wrong in some aspects. Please submit pull requests as issues are triaged.

Index

• Variables
• type BiographicalInformation
  • func (b BiographicalInformation) String() string
• type BiographicalInformationEyeColor
  • func (b BiographicalInformationEyeColor) String() string
• type BiographicalInformationGender
  • func (b BiographicalInformationGender) String() string
• type BiographicalInformationHairColor
  • func (b BiographicalInformationHairColor) String() string
• type BiometricType
  • func (b BiometricType) Equal(o BiometricType) bool
• type CBEFF
  • func Parse(in io.Reader) (*CBEFF, error)
  • func (c CBEFF) Close() error
  • func (c CBEFF) Facial() (*Facial, error)
• type Facial
• type FacialFeature
• type FacialHeader
  • func (fh FacialHeader) Validate() error
• type FacialInformation
  • func (fi FacialInformation) Validate() error
• type Header
  • func (h Header) ParseFASC() (*fasc.FASC, error)
  • func (h Header) Validate() error
• type Image
• type ImageInformation
  • func (ii ImageInformation) Validate() error
• type Time
  • func (t Time) Time() (time.Time, error)

Variables

var (
	// BiometricTypeFingerprint indicates the CBEFF file contains fingerprint
	// information. This may either be an enrollment or minutiae.
	BiometricTypeFingerprint = BiometricType{0x00, 0x00, 0x08}

	// BiometricTypeFacial indicates the CBEFF file contains the facial photos
	// to be used for visual confirmation of the individual.
	BiometricTypeFacial = BiometricType{0x00, 0x00, 0x02}
)

Types

type BiographicalInformation

type BiographicalInformation struct {
	Gender     BiographicalInformationGender
	EyeColor   BiographicalInformationEyeColor
	HairColor  BiographicalInformationHairColor
	Properties [3]byte
}

BiographicalInformation contains information about the individual who is the subject of the Image. This is not frequently used, and likely should not be relied on.

func (BiographicalInformation) String

func (b BiographicalInformation) String() string

String will return a human readable string.

type BiographicalInformationEyeColor

type BiographicalInformationEyeColor uint8

BiographicalInformationEyeColor will return the eye color of the subject of the Image.

func (BiographicalInformationEyeColor) String

func (b BiographicalInformationEyeColor) String() string

String will return a human readable string.

type BiographicalInformationGender

type BiographicalInformationGender uint8

BiographicalInformationGender contains inforamtion on the subject of the Image's "Gender". Whatever this could possibly mean, it's not something to be used if it's avoidable.

func (BiographicalInformationGender) String

func (b BiographicalInformationGender) String() string

String will return a human readable string.

type BiographicalInformationHairColor

type BiographicalInformationHairColor uint8

BiographicalInformationHairColor will return the hair color of the subject of the Image.

func (BiographicalInformationHairColor) String

func (b BiographicalInformationHairColor) String() string

String will return a human readable string.

type BiometricType

type BiometricType [3]byte

BiometricType indicates the type of biometric stored in the CBEFF, such as Face photos, or Fingerprints.

func (BiometricType) Equal

func (b BiometricType) Equal(o BiometricType) bool

Equal will check to see if the two BiometricTypes are the same.

type CBEFF

type CBEFF struct {
	// CBEFF file metadata, such as what kind of file this is, sizes of the
	// various payloads, and information such as creator, who the metric is of,
	// and validity time.
	Header Header

	// io.Reader over this CBEFF entry. This reader must be fully read before
	// moving onto any other files on the same Reader.
	Reader io.Reader
}

CBEFF is an ecapsulation of a CBEFF serialized file. This will allow you to dispatch based on the Header.BiometricType, and extract the information depending on what type of CBEFF entry it is.

func Parse

func Parse(in io.Reader) (*CBEFF, error)

Parse will read the CBEFF data from the io.Reader, parse the CBEFF header, and construct he CBEFF file encapsulation.

func (CBEFF) Close

func (c CBEFF) Close() error

Close the file.

func (CBEFF) Facial

func (c CBEFF) Facial() (*Facial, error)

Facial will parse the Facial record contained in the CBEFF entry. If the CBEFF header is not of type BiometricTypeFacial, this function will return an error and fail to parse the Facial data.

type Facial

type Facial struct {
	Header FacialHeader
	Images []Image
	Reader io.Reader
}

Facial contains a series of images and annotations.

type FacialFeature

type FacialFeature struct {
	Type       uint8
	MajorPoint uint8
	MinorPoint uint8
	X          uint16
	Y          uint16
	Reserved   uint8
}

FacialFeature contains an annotation on the attached Image.

type FacialHeader

type FacialHeader struct {
	FormatID     [4]byte
	VersionID    [4]byte
	RecordLength uint32
	NumberFaces  uint16
}

FacialHeader contains information about the Facial record to follow.

func (FacialHeader) Validate

func (fh FacialHeader) Validate() error

Validate will ensure that the FacialHeader is well formatted and understood by this library.

type FacialInformation

type FacialInformation struct {
	Length                  uint32
	NumberOfPoints          uint16
	BiographicalInformation BiographicalInformation
	Expression              [2]byte
	Pose                    [3]byte
	PoseUncertainty         [3]byte
}

FacialInformation contains information regarding the Image this is attached to.

func (FacialInformation) Validate

func (fi FacialInformation) Validate() error

Validate will ensure that this library understands and can properly process this data.

type Header

type Header struct {
	PatronHeaderVersion   uint8
	SBHSecurityOptions    uint8
	BDBLength             uint32
	SBLength              uint16
	BDBFormatOwner        uint16
	BDBFormatType         uint16
	BiometricCreationDate Time
	ValidityNotBefore     Time
	ValidityNotAfter      Time
	BiometricType         BiometricType
	BiometricDataType     uint8
	BiometricDataQuality  uint8
	Creator               [18]byte
	FASC                  [25]byte
	Reserved              [4]byte
}

Header contains information regarding the CBEFF data contained within the data stream.

func (Header) ParseFASC

func (h Header) ParseFASC() (*fasc.FASC, error)

ParseFASC will read the FASC bytes, and return a parsed pault.ag/go/fasc.Fasc struct.

func (Header) Validate

func (h Header) Validate() error

Validate will ensure that the header is understood by this library.

type Image

type Image struct {
	FacialInformation FacialInformation
	ImageInformation  ImageInformation
	Features          []FacialFeature
	Data              []byte
}

Image represents annotations and metadata attached to the image contained within.

type ImageInformation

type ImageInformation struct {
	Type       uint8
	DataType   uint8
	Width      uint16
	Height     uint16
	ColorSpace uint8
	SourceType uint8
	DeviceType uint16
	Quality    uint16
}

ImageInformation contains metadata regarding the format of the image data.

func (ImageInformation) Validate

func (ii ImageInformation) Validate() error

Validate will ensure that this library understands and can properly process this data.

type Time

type Time [8]byte

Time represents CBEFF Time as an 8 octet array, in the format of Y Y M D h m s Z, where Z is a literal ASCII 'Z', and the other values being the uint8 value for that position.

func (Time) Time

func (t Time) Time() (time.Time, error)

Time will return CBEFF Time into a Golang time.Time.