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 svctoken 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
	Hostname       string    // optional hostname
	IPAddress      string    // optional I/P 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)

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 I/P address for the token (default=host I/P address)
	SetIPAddress(ip 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
}

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)

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