EdDSA JWT using Ed25519 in Golang

This package is deprecated in favor of go-jwt

Due to the issues this package has and it's limited scope I'd recommend to take a look at my improved JWT implementation go-jwt. It has more features, less bugs, is more secure and most importantly extensible. This project will no longer be maintained. Use at your own discretion.

This packages implements JSON Web Token as defined in RFC 7519 in Go using Ed25519.

I'd like to implement Ed448 at some point but there is currently no stable Go implementation to build upon.

Important: This package is not fully compliant with RFC 7519 (JWT) and RFC 7515 (JWS) due to not implementing default signature algorithms. It is able to decode all JWTs that adhere to the standard but can only validate tokens using EdDSA with Ed25519 keys.

Tokens that are created with a struct as content can ONLY be validated when they are alphabetically sorted. This also means that tokens generated by a third party that do contain content that is not alphabetically sorted cannot currently be validated. Since a fix would break backwards compatability I will probably only fix this when implementing Ed448 in a new repository. Please see #7 for details.

This package may now be considered stable. Any future changes will be made with backwards compatibility in mind and should never break anything.

Data structures

JWTs are stored as a struct with the following layout

type JWT struct {
	Header struct {
		Typ string // Type of the token, has to be a JWT.
		Alg string // Algorithm used to sign the token (this package signs using EdDSA).
		Kid string // Key ID of the key used to sign the token.
		Jku string // URL presenting public key necessary for validation.
	}
	Content interface{} // Should be either a map with strings as keys or a struct to adhere to the standard.
	Hash []byte // A byte slice containing the hash/signature of the token. Will only be set when decoding a token.
}

While all values are accessible, you most likely will only need to worry about the content. This package will take care of the other ones for you.

Usage

Generating a new JWT

Creating a JWT is quite easy. You just have to supply your content and this package will generate a JWT for you. New will return an error when an unsupported content type is used. Supported content types are structs and maps with strings as keys.

jwt.New(content interface{}) (JWT, error)

There are two additional functions, jwt.NewWithKeyID(content interface{}, keyID string) and jwt.NewWithKeyIDAndKeyURL(content interface{}, keyID, keyURL string) (keyURL has to be a https link). Use these if you want to set a key ID (kid) or a key URL (jku) upon creation of the token. I will release a package for securely managing keys in a environment with many nodes and distributing them internally as well as to third parties.

Encoding a JWT

To actually use a JWT you will have to encode it. This is done by simply calling Encode on the JWT you created. You will need to provide a private key using Setup beforehand.

jwt.Setup(key ed25519.PrivateKey)
yourjwt.Encode() (string, error)

Decoding a JWT

To validate a JWT you will first have to decode it. Just supply it to the Decode function.

jwt.Decode(yourencodedjwt) (JWT, error)

Validating the hash

When decoding a JWT, it is not automatically validated. You will have to call Validate on it manually.

yourjwt.Validate(key ed25519.PublicKey) (error)

Keep in mind that this function only validates the hash and checks if the token is valid at the current point in time if exp and/or nbf are set.

Tokens that are created with a struct as content can ONLY be validated when they are alphabetically sorted. This also means that tokens generated by a third party that do contain content that is not alphabetically sorted cannot currently be validated. Since a fix would break backwards compatability I will probably only fix this when implementing Ed448 in a new repository. Please see #7 for details.