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
¶
Overview ¶
Package dsig provides models for dealing with digital signatures.
Index ¶
- type Digest
- type DigestAlgorithm
- type Error
- type 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
- type Signature
- 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) Unsafe() []byte
- func (s *Signature) UnsafePayload(payload any) error
- func (s *Signature) Verify(key *PublicKey) ([]byte, error)
- func (s *Signature) VerifyPayload(key *PublicKey, payload any) error
- type SignerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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 ¶
Equals checks to ensure the current digest result matches that of the provided digest object. This will fail if the algorithms are different.
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.
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) 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) MarshalJSON ¶
MarshalJSON provides the JSON version of the key.
func (*PublicKey) Thumbprint ¶
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 ¶
UnmarshalJSON parses the JSON public key data. You should perform validation on the key to ensure it was provided correctly.
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 ¶
ParseSignature converts raw signature data into an object that can be used to extract and validate.
func (Signature) JSONSchema ¶ added in v0.17.0
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) MarshalJSON ¶
MarshalJSON provides the compact string signature ready to be using as a JSON string.
func (*Signature) UnmarshalJSON ¶
UnmarshalJSON parses the compact signature string.
func (*Signature) Unsafe ¶ added in v0.66.1
Unsafe provides the raw data that was signed, but will not check any of the signatures.
func (*Signature) UnsafePayload ¶
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.
type SignerOption ¶ added in v0.18.1
type SignerOption func(*signerOptions)
SignerOption defines the callback to be used to define one of the signer options.
func WithJKU ¶ added in v0.18.1
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.
Source Files