Categorygithub.com/invopop/gobldsig
package
0.200.1
Repository: https://github.com/invopop/gobl.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
14
Dependents
8
Files
354 SLOC

# 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.

# Functions

NewES256Key provides a new ECDSA 256 bit private key and assigns it an ID.
NewSHA256Digest creates a SHA256 digest object from the provided byte array.
NewSignature instantiates a new Signature object by signing the provided data using the private key.
ParseSignature converts raw signature data into an object that can be used to extract and validate.
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.

# Constants

Known list of digest algorithms supported.
Standard error messages.
Standard error messages.
Standard error messages.
Standard error messages.

# Structs

Digest defines a structure to hold a digest value including the algorithm used to generate it.
PrivateKey makes it easy to deal with private keys used to sign data and created signatures.
PublicKey is generated from the private key and can be shared freely as it cannot be used to create signatures.
Signature represents a stored JSON Web Signature and provides helper methods to be able to extract and verify contents.

# Type aliases

DigestAlgorithm determines the name of the algorithm used to generate the digest's value.
Error defines the standard error messages supported by this JWS library.
SignerOption defines the callback to be used to define one of the signer options.