signedtoken

README

Signed Token

Golang library to created signed tokens for whatever use case you may think off. Some of the potential use cases are

• Authorization tokens using public/private key.
• File integrity checking for each individual.
• Creating revision information and signing them to prevent tampering.
• and so many other ideas ...

Signing and verifying messages

ECDSA signing and verification

// generate public and private ECDSA key

// convert an ECDSA private key to this library's `JWK` format before using.
privateECJWK, err := signedtoken.New(privateKey)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

// sign the input. input **MUST** be hashed message, ECDSA can accept any hashed input, SHA2 or SHA3 preferred
// for signing we use the ECDSA private key
sigECDSA, err := signedtoken.Sign(privateECJWK, hashed1[:])
if nil != err {
    log.Println(err)
    os.Exit(1)
}
fmt.Println(sigECDSA)


// convert an ECDSA public key to this library's `JWK` format before using.
publicECJWK, err := signedtoken.New(&privateKey.PublicKey)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

// verify a signature given the recipient's public key and hashed input (as used for signing)
err = signedtoken.Verify(publicECJWK, hashed1[:], sigECDSA)
if nil != err {
    log.Println(err)
    os.Exit(1)
} else {
    fmt.Println("ECDSA signature matches")
}

RSA signing and verification

// generate public and private RSA key

// convert an RSA private key to this library's `JWK` format before using.
privateRSAJWK, err := New(privateKey)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

// sign the input. input **MUST** be hashed message, RSADSA can accept any hashed input, SHA2 or SHA3 preferred
// for signing we use the RSADSA private key
sigEC, err := Sign(privateRSAJWK, hashed1[:]) // result is in PKCS1 format in bytes
if nil != err {
    log.Println(err)
    os.Exit(1)
}
fmt.Println(sigEC)


// convert an RSADSA public key to this library's `JWK` format before using.
publicRSAJWK, err := New(&privateKey.PublicKey) // result is in ASN.1 encoding for the values of `R` and `S` in bytes
if nil != err {
    log.Println(err)
    os.Exit(1)
}

// verify a signature given the rRSAipient's public key and hashed input (as used for signing)
err = Verify(publicRSAJWK, hashed1[:], sigEC)
if nil != err {
    log.Println(err)
    os.Exit(1)
} else {
    fmt.Println("RSADSA signature matches")
}

Creating and verifying JSON Web Signature (JWS)

Creating and verifying ECDSA JWS

// generate public and private ECDSA key

// convert an ECDSA private key to this library's `JWK` format before using.
privateECJWK, err := signedtoken.New(privateKey)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

type input struct {
    Subject   string `json:"sub,omitempty"`
    Audience  string `json:"aud,omitempty"`
    IssuedAt  int64  `json:"iat,omitempty"`
    NotBefore int64  `json:"nbf,omitempty"`
    Expire    int64  `json:"exp,omitempty"`
}

i := new(input)

i.IssuedAt = time.Now().UTC().Unix()
i.NotBefore = i.IssuedAt
i.Expire = time.Now().AddDate(1, 0, 0).UTC().Unix()
i.Audience = "me"
i.Subject = "supersubject"

iBytes, _ := json.Marshal(i)

jwtBytes, err := GenerateJWSWithAlg(privateECJWK, iBytes)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

payload, err := VerifyJWS(privateECJWK, jwtBytes)
if nil != err {
    log.Println(err)
    os.Exit(1)
}
fmt.Println(string(payload))

Creating and verifying RSA JWS

// generate public and private ECDSA key

// convert an RSA private key to this library's `JWK` format before using.
privateRSAJWK, err := New(privateKey)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

type input struct {
    Subject   string `json:"sub,omitempty"`
    Audience  string `json:"aud,omitempty"`
    IssuedAt  int64  `json:"iat,omitempty"`
    NotBefore int64  `json:"nbf,omitempty"`
    Expire    int64  `json:"exp,omitempty"`
}

i := new(input)

i.IssuedAt = time.Now().UTC().Unix()
i.NotBefore = i.IssuedAt
i.Expire = time.Now().AddDate(1, 0, 0).UTC().Unix()
i.Audience = "me"
i.Subject = "supersubject"

iBytes, _ := json.Marshal(i)

jwtBytes, err := GenerateJWSWithAlg(privateRSAJWK, iBytes)
if nil != err {
    log.Println(err)
    os.Exit(1)
}

payload, err := VerifyJWS(privateRSAJWK, jwtBytes)
if nil != err {
    log.Println(err)
    os.Exit(1)
}
fmt.Println(string(payload))

Documentation

Index

• Constants
• func GenerateJWS(j *JWK, payload []byte) (jwsBytes []byte, err error)
• func GenerateJWSWithAlg(j *JWK, payload []byte) (jwsBytes []byte, err error)
• func Sign(j *JWK, hashed []byte) (sig []byte, err error)
• func Verify(j *JWK, hashed, sig []byte) (err error)
• func VerifyJWS(j *JWK, jwsBytes []byte) (payload []byte, err error)
• type Header
  • func GetJWSHeader(jwsBytes []byte) (header *Header, err error)
• type JWK
  • func New(key interface{}) (j *JWK, err error)
  • func ToJWK(bytes []byte) (j *JWK, err error)
  • func (j *JWK) Bytes() (bytes []byte)
  • func (j *JWK) String() (str string)
  • func (j *JWK) ToKey() (key interface{}, err error)

Constants

const (
	ES256       jwa.SignatureAlgorithm = jwa.ES256
	ES256K      jwa.SignatureAlgorithm = jwa.ES256K
	ES384       jwa.SignatureAlgorithm = jwa.ES384
	ES512       jwa.SignatureAlgorithm = jwa.ES512
	EdDSA       jwa.SignatureAlgorithm = jwa.EdDSA
	HS256       jwa.SignatureAlgorithm = jwa.HS256
	HS384       jwa.SignatureAlgorithm = jwa.HS384
	HS512       jwa.SignatureAlgorithm = jwa.HS512
	NoSignature jwa.SignatureAlgorithm = jwa.NoSignature
	PS256       jwa.SignatureAlgorithm = jwa.PS256
	PS384       jwa.SignatureAlgorithm = jwa.PS384
	PS512       jwa.SignatureAlgorithm = jwa.PS512
	RS256       jwa.SignatureAlgorithm = jwa.RS256
	RS384       jwa.SignatureAlgorithm = jwa.RS384
	RS512       jwa.SignatureAlgorithm = jwa.RS512
)

Functions

func GenerateJWS

func GenerateJWS(j *JWK, payload []byte) (jwsBytes []byte, err error)

GenerateJWS - generates a new JWS from the given input

func GenerateJWSWithAlg

func GenerateJWSWithAlg(j *JWK, payload []byte) (jwsBytes []byte, err error)

GenerateJWSWithAlg - generates a new JWS from the given input using the given algorithm

func Sign

func Sign(j *JWK, hashed []byte) (sig []byte, err error)

Sign - signs the given input with the given JWK RSA or ECDSA private key

func Verify

func Verify(j *JWK, hashed, sig []byte) (err error)

Verify - verifies a given signature using the recipient's JWK RSA or ECDSA public key

func VerifyJWS

func VerifyJWS(j *JWK, jwsBytes []byte) (payload []byte, err error)

VerifyJWS - verifies a given JWS input

Types

type Header

type Header struct {
	Alg   string `json:"alg,omitempty"`
	KeyID string `json:"kid,omitempty"`
}

Header - header for JWS

func GetJWSHeader

func GetJWSHeader(jwsBytes []byte) (header *Header, err error)

GetJWSHeader - gets the JWS header

type JWK

type JWK struct {
	Kty string `yaml:"kty,omitempty" json:"kty,omitempty"`
	Crv string `yaml:"crv,omitempty" json:"crv,omitempty"`
	N   string `yaml:"n,omitempty" json:"n,omitempty"`
	E   string `yaml:"e,omitempty" json:"e,omitempty"`
	G   string `yaml:"g,omitempty" json:"g,omitempty"`
	P   string `yaml:"p,omitempty" json:"p,omitempty"`
	Q   string `yaml:"q,omitempty" json:"q,omitempty"`
	X   string `yaml:"x,omitempty" json:"x,omitempty"`
	Y   string `yaml:"y,omitempty" json:"y,omitempty"`
	D   string `yaml:"d,omitempty" json:"d,omitempty"`
	DP  string `yaml:"dp,omitempty" json:"dp,omitempty"`
	DQ  string `yaml:"dq,omitempty" json:"dq,omitempty"`
	QI  string `yaml:"qi,omitempty" json:"qi,omitempty"`
	Kid string `yaml:"kid,omitempty" json:"kid,omitempty"`
}

JWK - RSA & EC keys is in JWK format

func New

func New(key interface{}) (j *JWK, err error)

New - creates a new instance of JWK from a given key

func ToJWK

func ToJWK(bytes []byte) (j *JWK, err error)

ToJWK - creates a new `JWK` istance from a given JWK string bytes

func (*JWK) Bytes

func (j *JWK) Bytes() (bytes []byte)

Bytes - returns a JSON bytes of this JWK instance

func (*JWK) String

func (j *JWK) String() (str string)

String - returns a JSON string of this JWK instance

func (*JWK) ToKey

func (j *JWK) ToKey() (key interface{}, err error)