Capturing a suggested interface update from @jlhawn here

I recently wrote a library that I could use for simple JWS things. docker/libtrust has gotten a little dated and I didn't have time to formalize a proposal to change it but here's what I've come up with around an interface for JWS/JWA:

// SignatureAlgorithm holds info about a JWS signing algorithm.
type SignatureAlgorithm interface {
    // Name returns the "alg" (Algorithm) header parameter value for a JSON
    // Web Signature as defined in
    // https://tools.ietf.org/html/rfc7518#section-3.1
    Name() string
    // KeyType returns the "kty" (Key Type) parameter value for a JSON Web
    // Key as defined in https://tools.ietf.org/html/rfc7518#section-6.1
    KeyType() string
    // Hash returns a cryptographic hash function identifier that is used
    // with the signature algorithm as detailed in
    // https://tools.ietf.org/html/rfc7518#section-3.1
    Hash() crypto.Hash
}

// Signer is the interface used for generating a JWS signature.
type Signer interface {
    // SignatureAlgorithm is the signature algorithm used with this signer
    // as detailed in https://tools.ietf.org/html/rfc7518#section-3
    SignatureAlgorithm
    // Sign reads the given data and generates a signature of the content
    // using the specified SignatureAlgorithm as detailed in
    // https://tools.ietf.org/html/rfc7515#section-5.1
    Sign(data io.Reader) (signature string, err error)
}

// Verifier is the interface used for verifying a JWS signature.
type Verifier interface {
    // SignatureAlgorithm is the signature algorithm used with this
    // verifier as detailed in
    // https://tools.ietf.org/html/rfc7518#section-3
    SignatureAlgorithm
    // Verify reads the given data and checks it against the given
    // base64url-encoded signature using the specified SignatureAlgorithm
    // as detailed in https://tools.ietf.org/html/rfc7515#section-5.2
    Verify(data io.Reader, signature string) error
}

I then have a couple of struct types for asymmetric keys, though I suppose I could also easily have an implementation for symmetric keys for the HMAC signature types. The PublicKey and PrivateKey types have methods which return a Verifier and Signer respectively:

// Verifier creates a verifier using this Public Key JWK. The returned
// Verifier will use the hash function designated by given alg to verify a
// signature. The given alg value should correspond to the name of one of this
// JWK's supported SignatureAlgs otherwise an error is returned indicating so.
func (k *PublicKey) Verifier(alg string) (Verifier, error) { ... }

// Signer creates a Signer using this Private Key JWK. If no algorithm name is
// specified, a default signing algorithm is used: the first in this key's list
// of supported signing algorithms. If one or more algorithm names is
// specified, the first matching compatible signing algorithm is used. If no
// signing algorithms are available then an error is returned indicating so.
// The returned Signer will use the hash function designated by the selected
// algorithm to sign data.
func (k *PrivateKey) Signer(algs ...string) (Signer, error) { ... }

This interface makes is a lot easier to create or verify JSON Web Signature because you have to specify what signature algorithm you want to use to instantiate a verifier and it will error if the key does not support that signing algorithm. For signing, you don't even have to be explicit about it: the key can decide which algorithm to use if you do not specify any. The output of the Sign() method is also already base64url-encoded per the JOSE spec. The JWT signer in this app could then look something like this:

signer, err := privateKey.Signer()
if err != nil {
    return err
}

joseHeader["alg"] = signer.Name()

jwtPayload := encode(joseHeader, claimSet)

signature, err := signer.Sign(strings.NewReader(jwtPayload))
if err != nil {
    return err
}

token := jwtPayload + "." + signature

libtrust code migration #1820

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions