dsig

README

GoBL Digital Signatures

Introduction

Digital signatures are one of the fundamental features of GoBL as they bring the ability to be able to mathematically confirm using a public key that the person who owns the private key really did create the document.

This dsig package aims to bring together the functionality required to handle GoBL document digests and signatures in one place so they are easy and convenient to use.

Signatures in GoBL use the Javascript Object Signing and Encryption (JOSE) standards specifically around JSON Web Signatures (JWS) (RFC7515) and JSON Web Keys (JWK) (RFC7517).

Behind the scenes, GoBL uses the go-jose library to do all the heavy lifting and provides wrappers that make it easy to use sensible defaults. There should not be anything that cannot be implemented in another language, but helpers do make life easier and limit what is available to the use-cases of GoBL documents.

There are four key components to the dsig implementation:

• Private Key - Private JSON Web Keys (JWK), that can be used to create signatures. Currently, GoBL only supports ECDSA keys using a 256-bit curve. The private key is used to create a public counterpart and in addition to the JWK standards, every key must be identified with a UUID.
• Public Key - Public JSON Web Keys used to verify signatures. These can be shared freely and persisted or cached wherever they are to be used. Like the private key, they must include the same UUID assigned to the private counterpart.
• Signature - A JSON Web Signature which (JWS) is always serialized to JSON in compact form. The signature headers will always include the key's UUID to make it easier to find the public key used for validation.
• Digest - Defines the algorithm used to create a digest or hash of the GoBL document body and the resulting value in hexadecimal format. The digest is expected to be included in a document header and consequently in the signature payload. SHA256 digests are only supported at this time.

This package aims to make it easier to use digital signatures with GoBL documents, but it should be just as easy to use this library with any software, document, or message that could benefit from a simplified approach to dealing with JSON Web Signatures.

Documentation

Index

• type Digest
  • func NewSHA256Digest(data []byte) *Digest
  • func (d *Digest) Equals(d2 *Digest) error
  • func (d *Digest) String() string
  • func (d *Digest) Validate() error
• type DigestAlgorithm
• type Error
  • func (e Error) Error() string
• type PrivateKey
  • func NewES256Key() *PrivateKey
  • func (k *PrivateKey) ID() string
  • func (k *PrivateKey) MarshalJSON() ([]byte, error)
  • func (k *PrivateKey) Public() *PublicKey
  • func (k *PrivateKey) Sign(data interface{}) (*Signature, error)
  • func (k *PrivateKey) Thumbprint() string
  • func (k *PrivateKey) UnmarshalJSON(data []byte) error
  • func (k *PrivateKey) Validate() error
• type PublicKey
  • func (k *PublicKey) ID() string
  • func (k *PublicKey) MarshalJSON() ([]byte, error)
  • func (k *PublicKey) Thumbprint() string
  • func (k *PublicKey) UnmarshalJSON(data []byte) error
  • func (k *PublicKey) Validate() error
  • func (k *PublicKey) Verify(sig *Signature, payload interface{}) error
• type Signature
  • func NewSignature(key *PrivateKey, data interface{}, opts ...SignerOption) (*Signature, error)
  • func ParseSignature(data string) (*Signature, error)
  • func (s *Signature) JKU() string
  • func (Signature) JSONSchema() *jsonschema.Schema
  • func (s *Signature) JSONWebSignature() *jose.JSONWebSignature
  • func (s *Signature) KeyID() string
  • func (s *Signature) MarshalJSON() ([]byte, error)
  • func (s *Signature) String() string
  • func (s *Signature) UnmarshalJSON(data []byte) error
  • func (s *Signature) UnsafePayload(payload interface{}) error
  • func (s *Signature) VerifyPayload(key *PublicKey, payload interface{}) error
• type SignerOption
  • func WithJKU(jku string) SignerOption

Types

type Digest

type Digest struct {
	// Algorithm stores the algorithm key that was used to generate the value.
	Algorithm DigestAlgorithm `json:"alg" jsonschema:"title=Algorithm"`

	// Value contains the Hexadecimal representation of the resulting hash
	// generated by the algorithm.
	Value string `json:"val" jsonschema:"title=Value"`
}

Digest defines a structure to hold a digest value including the algorithm used to generate it.

func NewSHA256Digest

func NewSHA256Digest(data []byte) *Digest

NewSHA256Digest creates a SHA256 digest object from the provided byte array. We assume the data has already been through a canonicalization (c14n) process.

func (*Digest) Equals

func (d *Digest) Equals(d2 *Digest) error

Equals checks to ensure the current digest result matches that of the provided digest object. This will fail if the algorithms are different.

func (*Digest) String

func (d *Digest) String() string

String provides a compact string representation of the digest which may be useful for comparisons.

func (*Digest) Validate

func (d *Digest) Validate() error

Validate the contents of the digest

type DigestAlgorithm

type DigestAlgorithm string

DigestAlgorithm determines the name of the algorithm used to generate the digest's value.

const (
	DigestSHA256 DigestAlgorithm = "sha256"
)

Known list of digest algorithms supported.

type Error

type Error string

Error defines the standard error messages supported by this JWS library.

const (
	ErrKeyPublic    Error = "cannot sign with public key"
	ErrKeyInvalid   Error = "key is not valid"
	ErrKeyMismatch  Error = "key mismatch"
	ErrVerifyFailed Error = "verification failed"
)

Standard error messages

func (Error) Error

func (e Error) Error() string

Error provides the standard error response text.

type PrivateKey

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

PrivateKey makes it easy to deal with private keys used to sign data and created signatures. These should obviously be kept secure and be used to generate the public keys.

func NewES256Key

func NewES256Key() *PrivateKey

NewES256Key provides a new ECDSA 256 bit private key and assigns it an ID.

func (*PrivateKey) ID

func (k *PrivateKey) ID() string

ID provides the private key's UUID

func (*PrivateKey) MarshalJSON

func (k *PrivateKey) MarshalJSON() ([]byte, error)

MarshalJSON provides the JSON version of the key.

func (*PrivateKey) Public

func (k *PrivateKey) Public() *PublicKey

Public provides the public counterpart of a private key, ready to be used to be persisted in a key store and verify signatures.

func (*PrivateKey) Sign

func (k *PrivateKey) Sign(data interface{}) (*Signature, error)

Sign is a helper method that will generate a signature using the private key.

func (*PrivateKey) Thumbprint

func (k *PrivateKey) Thumbprint() string

Thumbprint returns the SHA256 hex string of the private key's thumbprint. Extremely useful for quickly checking that two keys, either public or private, are the same.

func (*PrivateKey) UnmarshalJSON

func (k *PrivateKey) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the JSON private key data. You should perform validation on the key to ensure it was provided correctly.

func (*PrivateKey) Validate

func (k *PrivateKey) Validate() error

Validate let's us know if the private key was generated or parsed correctly.

type PublicKey

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

PublicKey is generated from the private key and can be shared freely as it cannot be used to create signatures.

func (*PublicKey) ID

func (k *PublicKey) ID() string

ID provides the public key's UUID

func (*PublicKey) MarshalJSON

func (k *PublicKey) MarshalJSON() ([]byte, error)

MarshalJSON provides the JSON version of the key.

func (*PublicKey) Thumbprint

func (k *PublicKey) Thumbprint() string

Thumbprint returns the SHA256 hex string of the public key's thumbprint. Extremely useful for quickly checking that two keys are the same.

func (*PublicKey) UnmarshalJSON

func (k *PublicKey) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the JSON public key data. You should perform validation on the key to ensure it was provided correctly.

func (*PublicKey) Validate

func (k *PublicKey) Validate() error

Validate let's us know if the public key was parsed correctly.

func (*PublicKey) Verify

func (k *PublicKey) Verify(sig *Signature, payload interface{}) error

Verify is a wrapper around the signature's VerifyPayload method for the sake of convenience.

type Signature

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

Signature represents a stored JSON Web Signature and provides helper methods to be able to extract and verify contents.

func NewSignature

func NewSignature(key *PrivateKey, data interface{}, opts ...SignerOption) (*Signature, error)

NewSignature instantiates a new Signature object by signing the provided data using the private key. The signature will use the same algorithm as defined by the key.

func ParseSignature

func ParseSignature(data string) (*Signature, error)

ParseSignature converts raw signature data into an object that can be used to extract and validate.

func (*Signature) JKU

func (s *Signature) JKU() string

JKU returns the signatures JKU header property value.

func (Signature) JSONSchema

func (Signature) JSONSchema() *jsonschema.Schema

JSONSchema returns the json schema type.

func (*Signature) JSONWebSignature

func (s *Signature) JSONWebSignature() *jose.JSONWebSignature

JSONWebSignature provides underlying JOSE object.

func (*Signature) KeyID

func (s *Signature) KeyID() string

KeyID extracts the ID used to generate the signature from the headers.

func (*Signature) MarshalJSON

func (s *Signature) MarshalJSON() ([]byte, error)

MarshalJSON provides the compact string signature ready to be using as a JSON string.

func (*Signature) String

func (s *Signature) String() string

String provides the compact form signature.

func (*Signature) UnmarshalJSON

func (s *Signature) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the compact signature string.

func (*Signature) UnsafePayload

func (s *Signature) UnsafePayload(payload interface{}) error

UnsafePayload will extract the payload data into the provided object but will not perform any signature checking. Only recommended for specific use cases when the original key is not available or has already been confirmed elsewhere.

func (*Signature) VerifyPayload

func (s *Signature) VerifyPayload(key *PublicKey, payload interface{}) error

VerifyPayload verifies that the provided key was indeed used to sign the original payload and will parse the data ready to use.

type SignerOption

type SignerOption func(*signerOptions)

SignerOption defines the callback to be used to define one of the signer options.

func WithJKU

func WithJKU(jku string) SignerOption

WithJKU adds the "jku" header field to the signature, useful for identifying a URL that can be used to lookup and validate the public key that was used during signing.