scram

Documentation

Overview

Package scram implements the SCRAM-SHA-* SASL authentication mechanism, RFC 7677 and RFC 5802.

SCRAM-SHA-256 and SCRAM-SHA-1 allow a client to authenticate to a server using a password without handing plaintext password over to the server. The client also verifies the server knows (a derivative of) the password.

Index

• Variables
• func HMAC(h func() hash.Hash, key []byte, msg string) []byte
• func MakeRandom() []byte
• func SaltPassword(h func() hash.Hash, password string, salt []byte, iterations int) []byte
• type Client
  • func NewClient(h func() hash.Hash, authc, authz string) *Client
  • func (c *Client) ClientFirst() (clientFirst string, rerr error)
  • func (c *Client) ServerFinal(serverFinal []byte) (rerr error)
  • func (c *Client) ServerFirst(serverFirst []byte, password string) (clientFinal string, rerr error)
• type Error
  • func (e Error) Error() string
• type Server
  • func NewServer(h func() hash.Hash, clientFirst []byte) (server *Server, rerr error)
  • func (s *Server) Finish(clientFinal []byte, saltedPassword []byte) (serverFinal string, rerr error)
  • func (s *Server) FinishError(err Error) string
  • func (s *Server) ServerFirst(iterations int, salt []byte) (string, error)

Variables

var (
	ErrNorm     = errors.New("parameter not unicode normalized") // E.g. if client sends non-normalized username or authzid.
	ErrUnsafe   = errors.New("unsafe parameter")                 // E.g. salt, nonce too short, or too few iterations.
	ErrProtocol = errors.New("protocol error")                   // E.g. server responded with a nonce not prefixed by the client nonce.
)

Functions

func HMAC

func HMAC(h func() hash.Hash, key []byte, msg string) []byte

HMAC returns the hmac with key over msg.

func MakeRandom

func MakeRandom() []byte

MakeRandom returns a cryptographically random buffer for use as salt or as nonce.

func SaltPassword

func SaltPassword(h func() hash.Hash, password string, salt []byte, iterations int) []byte

SaltPassword returns a salted password.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents the client-side of a SCRAM-SHA-* authentication.

func NewClient

func NewClient(h func() hash.Hash, authc, authz string) *Client

NewClient returns a client for authentication authc, optionally for authorization with role authz, for the hash (sha1.New or sha256.New).

The sequence for data and calls on a client:

• ClientFirst, write result to server.
• Read response from server, feed to ServerFirst, write response to server.
• Read response from server, feed to ServerFinal.

func (*Client) ClientFirst

func (c *Client) ClientFirst() (clientFirst string, rerr error)

ClientFirst returns the first client message to write to the server. No channel binding is done/supported. A random nonce is generated.

func (*Client) ServerFinal

func (c *Client) ServerFinal(serverFinal []byte) (rerr error)

ServerFinal processes the final message from the server, verifying that the server knows the password.

func (*Client) ServerFirst

func (c *Client) ServerFirst(serverFirst []byte, password string) (clientFinal string, rerr error)

ServerFirst processes the first response message from the server. The provided nonce, salt and iterations are checked. If valid, a final client message is calculated and returned. This message must be written to the server. It includes proof that the client knows the password.

type Error

type Error string

var (
	ErrInvalidEncoding                 Error = "invalid-encoding"
	ErrExtensionsNotSupported          Error = "extensions-not-supported"
	ErrInvalidProof                    Error = "invalid-proof"
	ErrChannelBindingsDontMatch        Error = "channel-bindings-dont-match"
	ErrServerDoesSupportChannelBinding Error = "server-does-support-channel-binding"
	ErrChannelBindingNotSupported      Error = "channel-binding-not-supported"
	ErrUnsupportedChannelBindingType   Error = "unsupported-channel-binding-type"
	ErrUnknownUser                     Error = "unknown-user"
	ErrNoResources                     Error = "no-resources"
	ErrOtherError                      Error = "other-error"
)

Errors at scram protocol level. Can be exchanged between client and server.

func (Error) Error

func (e Error) Error() string

type Server

type Server struct {
	Authentication string // Username for authentication, "authc". Always set and non-empty.
	Authorization  string // If set, role of user to assume after authentication, "authz".
	// contains filtered or unexported fields
}

Server represents the server-side of a SCRAM-SHA-* authentication.

func NewServer

func NewServer(h func() hash.Hash, clientFirst []byte) (server *Server, rerr error)

NewServer returns a server given the first SCRAM message from a client.

The sequence for data and calls on a server:

• Read initial data from client, call NewServer (this call), then ServerFirst and write to the client.
• Read response from client, call Finish or FinishFinal and write the resulting string.

func (*Server) Finish

func (s *Server) Finish(clientFinal []byte, saltedPassword []byte) (serverFinal string, rerr error)

Finish takes the final client message, and the salted password (probably from server storage), verifies the client, and returns a message to return to the client. If err is nil, authentication was successful. If the authorization requested is not acceptable, the server should call FinishError instead.

func (*Server) FinishError

func (s *Server) FinishError(err Error) string

FinishError returns an error message to write to the client for the final server message.

func (*Server) ServerFirst

func (s *Server) ServerFirst(iterations int, salt []byte) (string, error)

ServerFirst returns the string to send back to the client. To be called after NewServer.