README
¶
Go - PoP Token Builder Library
Implementation Details
The T-Mobile PoP Token Builder library follows the following logic for creating the PoP token.
- Sets up the edts (external data to sign) / ehts (external headers to sign) claims in the PoP token using the headers in a provided HTTP request, joining repeated headers according to the algorithm described in section 5.3 of RFC 9110. The library uses SHA256 for calculating the edts and then the final edts value is encoded using Base64 URL encoding.
- Signs the PoP token using the specified RSA private key.
- Creates the PoP token with, by default, 2 minutes of validity.
- The PoP Token builder object is created by calling
New, passing in options using the Go idiom of interface-based options; practically, a minimal call to generate this object looks like:poptoken.New(poptoken.PrivateKey(privRSAKey)). Several options exist for customizing the operation. - The PoP Token builder object can also be used to validate a received token; a minimal call to generate the object for this purpose looks like:
poptoken.New(poptoken.PublicKey(pubRSAKey)).
Note: by default, all headers of an HTTP request are included when computing the PoP token for the request. If some headers should not be protected, ensure that those headers are set after calling PoPToken.Sign.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoKeys = errors.New("At least one of a public key or a private key must be provided") ErrInvalidKeys = errors.New("Public key does not belong to private key") ErrNoPrivateKey = errors.New("No private key provided") ErrNoPoPToken = errors.New("No PoP token set in request") // Invalid token errors; always wrapped in an InvalidToken ErrParsedInvalid = errors.New("Token marked as invalid by JWT library") ErrBadClaims = errors.New("Token claims not interpretable") ErrNoEHTSClaim = errors.New("EHTS claim not available or not a string") ErrNoEDTSClaim = errors.New("EDTS claim not available or not a string") ErrEDTSMismatch = errors.New("Computed EDTS does not match claimed EDTS") )
Errors that may be returned by the PoP token library.
var Debug = DebugOption(true)
Debug is an option that enables debugging output on the PoPToken object.
Functions ¶
func FullError ¶
FullError is a helper that reports the full error message of an error originating from the PoPToken.Verify method. This ensures that the underlying cause of the verification error can be retrieved without accidentally leaking any data back to the client.
Types ¶
type HashConstructorOption ¶
type HashConstructorOption struct {
// contains filtered or unexported fields
}
HashConstructorOption is the implementation of the option returned by the HashConstructor constructor.
func HashConstructor ¶
func HashConstructor(hc HashFactory) *HashConstructorOption
HashConstructor is used to provide a hash.Hash constructor for use by PoPToken. This option allows using a different hash algorithm than the default of SHA256.
type HashFactory ¶
HashFactory is a type describing a function that constructs and returns a hash.Hash. It can be used with the HashConstructor option to alter the hash algorithm used when constructing the EDTS string.
type InvalidToken ¶
type InvalidToken struct {
Err error // Wrapped error
}
InvalidToken is an error that optionally wraps another error and which indicates that a token is not valid.
func (InvalidToken) Error ¶
func (e InvalidToken) Error() string
Error implements the error interface and returns the error string.
func (InvalidToken) FullError ¶
func (e InvalidToken) FullError() string
FullError returns the full error, including the embedded error. This is implemented as a non-standard error function to avoid leaking too much data to the client which originated the invalid token.
func (InvalidToken) Unwrap ¶
func (e InvalidToken) Unwrap() error
Unwrap implements the error unwrapping interface.
type Logger ¶
type Logger interface {
// Printf formats a log message and sends it to the appropriate
// log stream.
Printf(format string, v ...interface{})
}
Logger is an interface used to control how logs generated within the library get reported. Any object that implements a Printf function matching this signature can be used as a logger.
type LoggerOption ¶
type LoggerOption struct {
// contains filtered or unexported fields
}
LoggerOption is the implementation of the option returned by the SetLogger constructor.
func SetLogger ¶
func SetLogger(logger Logger) *LoggerOption
SetLogger is used to specify an alternative logger for use by PoPToken.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option represents an option for the New function. This controls how PoPToken performs its tasks, including providing the private and public keys for generating and validating PoP tokens (respectively).
type PoPToken ¶
type PoPToken struct {
// contains filtered or unexported fields
}
PoPToken is the type that implements the operations necessary to generate or validate a PoP token. This structure contains the RSA keys, time-to-live option for the generated token, the logger, etc. Use the New function to generate a new PoPToken instance; PoPToken.Build and PoPToken.Sign are used for building tokens from http.Request; and PoPToken.Verify verifies a PoP token included in an http.Request.
func New ¶
New creates a new PoPToken instance from options passed in. Use PrivateKey and PublicKey to set the private and/or public RSA keys; HashConstructor for setting the hash algorithm; TTL for altering the time-to-live of the resultant token from its 2 minute default; and SetLogger to provide an alternate logger from the default, which utilizes the standard log package. Finally, the Debug option can be provided to enable debugging output. At least one of the keys must be provided, or New will return ErrNoKeys. Further, if a private key is provided, the public key, if not provided, will be derived from it; or if the public key is provided, it will be validated to be associated with the private key and ErrInvalidKeys returned if that is not the case.
func (*PoPToken) Build ¶
Build constructs and returns a PoP token for a given request. If no private key has been provided, ErrNoPrivateKey will be returned.
func (*PoPToken) Sign ¶
Sign signs the request, setting the X-Authorization header to a valid PoP token value. If no private key has been provided, ErrNoPrivateKey will be returned.
func (*PoPToken) Verify ¶
Verify verifies that a request contains a valid, signed PoP token. It will return no error if the request is valid. In the event the request contains no PoP token, it will return ErrNoPoPToken. Any other validation error will return an instance of the InvalidToken type, wrapping the underlying error. (The use of InvalidToken is a security safety measure, intended to prevent leaking information to the request source about the cause of the error.)
type PrivateKeyOption ¶
type PrivateKeyOption struct {
// contains filtered or unexported fields
}
PrivateKeyOption is the implementation of the option returned by the PrivateKey constructor.
func PrivateKey ¶
func PrivateKey(pk *rsa.PrivateKey) *PrivateKeyOption
PrivateKey is used to provide a private key for use by PoPToken. This option must be passed in order for the PoPToken.Build and PoPToken.Sign operations to function.
type PublicKeyOption ¶
type PublicKeyOption struct {
// contains filtered or unexported fields
}
PublicKeyOption is the implementation of the option returned by the PublicKey constructor.
Source Files