zmssvctoken

README

zmssvctoken

Go library to generate/validate Athenz NTokens given private/public keys.

Mirrors the functionality of the Java token signer. It supports RSA and ECDSA keys

See the zms-svctoken utility source for example use.

License

Copyright 2016 Yahoo Inc.

Licensed under the Apache License, Version 2.0

Documentation

Overview

Package zmssvctoken generates/validates Athenz NTokens given private/public keys.

Package zmssvctoken produces and validates ntokens given appropriate keys. It can only produce service tokens but can validate any principal token.

Index

• type NToken
  • func (n *NToken) IsExpired() bool
  • func (n *NToken) PrincipalName() string
  • func (n *NToken) String() string
• type Signer
  • func NewSigner(privateKeyPEM []byte) (Signer, error)
• type Token
• type TokenBuilder
  • func NewTokenBuilder(domain, name string, privateKeyPEM []byte, keyVersion string) (TokenBuilder, error)
• type TokenValidator
  • func NewPubKeyTokenValidator(publicKeyPEM []byte) (TokenValidator, error)
  • func NewTokenValidator(config ...ValidationConfig) TokenValidator
• type ValidationConfig
• type Verifier
  • func NewVerifier(publicKeyPEM []byte) (Verifier, error)
• type YBase64
  • func (lb *YBase64) DecodeString(s string) ([]byte, error)
  • func (lb *YBase64) EncodeToString(b []byte) string

Types

type NToken

type NToken struct {
	Version        string    // the token version e.g. S1, U1
	Domain         string    // domain for which token is valid
	Name           string    // local principal name
	KeyVersion     string    // key version as registered in Athenz
	KeyService     string    // optional key service
	Hostname       string    // optional hostname
	IPAddress      string    // optional IP address
	GenerationTime time.Time // time token was generated
	ExpiryTime     time.Time // time token expires
}

NToken provides access to useful fields in an ntoken.

func (*NToken) IsExpired

func (n *NToken) IsExpired() bool

IsExpired is a convenience function to check token expiry.

func (*NToken) PrincipalName

func (n *NToken) PrincipalName() string

PrincipalName returns the fully qualified principal name for the token.

func (*NToken) String

func (n *NToken) String() string

type Signer

type Signer interface {
	Sign(input string) (string, error)
}

Signer signs a string and returns the signature.

func NewSigner

func NewSigner(privateKeyPEM []byte) (Signer, error)

NewSigner creates an instance of Signer using the given private key (ECDSA or RSA).

type Token

type Token interface {
	// Value returns the value of the current token or
	// an error if it couldn't be generated for any reason.
	Value() (string, error)
}

Token is a mechanism to get an ntoken as a string. It guarantees that the returned token has not expired.

type TokenBuilder

type TokenBuilder interface {
	// SetExpiration sets the duration for which the token is valid (default=1h).
	SetExpiration(t time.Duration)
	// SetHostname sets the hostname for the token (default=current hostname).
	SetHostname(h string)
	// SetIPAddress sets the IP address for the token (default=host IP address).
	SetIPAddress(ip string)
	// SetKeyService sets the key service for the token
	SetKeyService(keyService string)
	// Token returns a Token instance with the fields correctly set for
	// the current token. Multiple calls to Token will return the same implementation.
	// If you change optional attributes between calls to Token, these will have no effect.
	Token() Token
}

TokenBuilder provides a mechanism to set optional ntoken attributes and a means to get the token value with efficient auto-refresh.

func NewTokenBuilder

func NewTokenBuilder(domain, name string, privateKeyPEM []byte, keyVersion string) (TokenBuilder, error)

NewTokenBuilder returns a TokenBuilder implementation for the specified domain/name, with a private key (PEM format) and its key-version. The key-version should be the same string that was used to register the key with Athenz.

type TokenValidator

type TokenValidator interface {
	// Validate returns an unexpired NToken object from its
	// string representation.
	Validate(token string) (*NToken, error)
}

TokenValidator provides a mechanism to validate tokens.

func NewPubKeyTokenValidator

func NewPubKeyTokenValidator(publicKeyPEM []byte) (TokenValidator, error)

NewPubKeyTokenValidator returns NToken objects from signed token strings given a public key to verify signatures.

func NewTokenValidator

func NewTokenValidator(config ...ValidationConfig) TokenValidator

NewTokenValidator returns NToken objects from signed token strings. It automatically fetches the required public key for validation from ZTS based on the token contents. You can optionally pass in a validation config object to change runtime parameters from the default values.

type ValidationConfig

type ValidationConfig struct {
	ZTSBaseUrl            string        // the ZTS base url including the /zts/v1 version path, default
	PublicKeyFetchTimeout time.Duration // timeout for fetching the public key from ZTS, default: 5s
	CacheTTL              time.Duration // TTL for cached public keys, default: 10 minutes
	// contains filtered or unexported fields
}

ValidationConfig contains data to change runtime parameters from the default values.

type Verifier

type Verifier interface {
	Verify(input, signature string) error
}

Verifier verifies the signature for a string.

func NewVerifier

func NewVerifier(publicKeyPEM []byte) (Verifier, error)

NewVerifier creates an instance of Verifier using the given public key.

type YBase64

type YBase64 struct {
}

YBase64 is a variant of the std base64 encoding with URL safe characters, used by Yahoo circa web 1.0. It uses '.' and '_' as replacements for '+' and '/' and uses '-' instead of '=' as the padding character.

func (*YBase64) DecodeString

func (lb *YBase64) DecodeString(s string) ([]byte, error)

DecodeString decodes a string encoded using EncodeToString.

func (*YBase64) EncodeToString

func (lb *YBase64) EncodeToString(b []byte) string

EncodeToString encodes an array of bytes to a string.