The highest tagged major version is
Documentation
¶
Overview ¶
The challenge/response negotiation between the mapper server and clients is implemented in this package.
CLIENT-SIDE OPERATION ¶
A client wishing to authenticate should create an Authenticator as
a := NewClientAuthenticator(my_user_name, my_secret_value, my_program_name)
where my_secret_value is the shared secret (password) used by all clients to authenticate to the server, or the personal password assigned to the user with the name given by my_user_name, if one exists; my_program_name is a string describing what sort of client this is.
If my_user_name is empty, an attempt will be made to determine the local user name of the process, or will be "anonymous" if that cannot be accomplished. If the program name is empty, "unnamed" will be used.
These values are used to provide needed context for the user's session with the server, but just for the functioning of the methods documented here, the minimal client Authenticator necessary is simply
a := &Authenticator{Secret: my_secret_value}
The client then obtains a challenge from the server in the form of a base-64-encoded string, which is passes to the AcceptChallenge() method:
response, err := a.AcceptChallenge(server_challenge_string)
This provides the response to send back to the server in order to log in.
SERVER-SIDE OPERATION ¶
A server which accepts a client connection should create an Authenticator for each such client which will track that session's authentication state.
a := &Authenticator{Secret: common_password, GmSecret: gm_password}
where common_password is the password used by all clients to authenticate, and gm_password is the one used by privileged clients.
The server then generates a unique challenge for this client's session by calling
challenge, err := a.GenerateChallenge()
The generated challenge string is sent to the client, which will reply with a response string. The server validates the authenticity of the response by calling
ok, err := a.ValidateResponse(client_response)
which will return true if the response is correct for that challenge.
If the server has a personal password on file for a given user, it can place that value in the Secret member of Authenticator or may set it by calling
a.SetSecret(personal_secret)
before calling the GenerateChallenge() method.
Index ¶
- type Authenticator
- func (a *Authenticator) AcceptChallenge(challenge string) (string, error)
- func (a *Authenticator) CurrentChallenge() string
- func (a *Authenticator) GenerateChallenge() (string, error)
- func (a *Authenticator) Reset()
- func (a *Authenticator) SetSecret(secret []byte)
- func (a *Authenticator) ValidateResponse(response string) (bool, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
type Authenticator struct {
// unprivileged (player) authentication password (client or server)
Secret []byte
// privileged (GM) authentication password (server only)
GmSecret []byte
// current generated challenge or nil
Challenge []byte
// text description of client program/version
Client string
// name of user authenticating
Username string
// true if GM authentication succeeded (server only)
GmMode bool
}
An Authenticator object holds the authentication challenge/response context for a single client transaction.
func NewClientAuthenticator ¶
func NewClientAuthenticator(username string, secret []byte, client string) *Authenticator
Generate a new client-side Authenticator for a user with the given username, secret, and string description of the client program. If the username string is empty, an attempt will be made to determine the local username on the system, or the string "anonymous" will be used. If the client string is empty, "unnamed" will be used.
func (*Authenticator) AcceptChallenge ¶
func (a *Authenticator) AcceptChallenge(challenge string) (string, error)
Accept a server's challenge, store it internally, and generate an appropriate response to it.
func (*Authenticator) CurrentChallenge ¶
func (a *Authenticator) CurrentChallenge() string
Return the last-generated challenge created by GenerateChallenge(). This is returned as a base-64-encoded string suitable for transmitting directly to a client.
func (*Authenticator) GenerateChallenge ¶
func (a *Authenticator) GenerateChallenge() (string, error)
Generate an authentication challenge for this session. This is a 256-bit random nonce which is remembered for subsequent operations on this Authenticator instance.
The challenge is returned as a base-64-encoded string.
func (*Authenticator) Reset ¶
func (a *Authenticator) Reset()
Reset an Authenticator instance back to its pre-challenge state so that it may be used again for another authentication attempt. Existing secrets and user names are preserved.
func (*Authenticator) SetSecret ¶
func (a *Authenticator) SetSecret(secret []byte)
Change the secret (for when we know the username they are logging in as and that user has their own password). This disables GM logins. If the client's response is correct, they will be authenticated as a non-privileged user.
func (*Authenticator) ValidateResponse ¶
func (a *Authenticator) ValidateResponse(response string) (bool, error)
Given a base-64-endoded response string, verify that the value it encodes matches the expected response for the previously-generated challenge.
If the response is not correct for the expected user's secret, we try again against the GM's secret to see if the user is logging in as the GM role. If so, the GmMode member of the Authenticator is set to true.
Source Files