This document defines which functions have to be implemented by modules to be usable with this package.
NewProvider(algorithm int) (Provider, error)NewProvider has to create a new Provider taking in the algorithm ID as an integer.
It has to generate new secure keys for signing and verification.
A key ID must also be generated for every new key and included with the public keys.
NewProviderWithKeyURL(algorithm int, keyURL string) (Provider, error)NewProviderWithKeyURL has to work the same as NewProvider but must also add the key URL so that is is available to the Header function of the provider.
LoadProvider(settings SignatureSettings, algorithm int) (Provider, error)LoadProvider may be provided to enable users to load keys.
The function must take SignatureSettings and an integer indicating the desired algorithm ID.
type Provider interface {
Sign([]byte) ([]byte, error)
Verify([]byte, []byte, Header) error
Header(*Header)
AddPublicKey(publickey.PublicKey) error
RemovePublicKey(string) error
CurrentKey() publickey.PublicKey
}A Provider has to implement the following functionality:
Sign(data []byte) (signature []byte, err error) has to return the (not base64-encoded) signature the algorithm generates for the data provided as the input and an error to indicate whether signing was successful.
Verify(data, signature []byte, h Header) (err error) has to return an error indicating whether the signature could be validated. The header can be accessed for additional data. The error may present information about an internal issue with validating like a missing key but an invalid signature must be indicated only by returning errors.New("signature invalid"). This is for security purposes as a developer may want to forward this error to the user and too much information about the verification process could cause issues.
Header(h *Header) has to set the necessary header parameters to indicate the used algorithm. It must also set the key ID and key URL in case the key designated for signing has any.
In case additional fields in the header are necessary, please open an issue on GitHub to discuss possible solutions.
AddPublicKey(key publickey.PublicKey) error adds a public key that the provider can use to validate signatures generated by other applications or instances. It returns an error if the key cannot be parsed or already exists.
RemovePublicKey(keyid string) removes a public key by key ID from the verification set. This can be used to remove compromised keys. It is a noop for the public key belonging to the private key used for signing.
CurrentKey() publickey.PublicKey returns the public key belonging to the private key used for signing. The key should be properly encoded so it can easily be encoded to PEM or transferred in binary with the least possible overhead.
SignatureSettings are only necessary when supporting LoadProvider and have to implement the following functionality:
func NewSettings(key []byte, keyid string) (SignatureSettings, error)NewSettigns parses the key and returns SignatureSettings with the key and key ID set and an error indicating whether parsing was successful
func NewSettingsWithKeyURL(key []byte, keyid string, keyurl string) (SignatureSettings, error)NewSettingsWithKeyURL parses the key and returns SignatureSettings with the key, key ID and key URL set and an error indicating whether parsing was successful
func Validate(content []byte) errorA validation provider consists of a single function taking a byte slice containing the JSON-encoded body of the token and returns an error indication whether the token is valid. It has to unmarshal the JSON and perform all necessary checks to determine the validity of the claims.