Name

OpenXPKI::Service::Default - basic service implementation

Description

This is the common Service implementation to be used by most interactive clients. It supports PKI realm selection, user authentication and session handling.

Protocol Definition

Connection startup

You can send two messages at the beginning of a connection. You can ask to continue an old session or you start a new session. The answer is always the same - the session ID or an error message.

Session init

--> {SERVICE_MSG => "NEW_SESSION",
LANGUAGE => $lang}

<-- {SESSION_ID => $ID}

--> {SERVICE_MSG => "SESSION_ID_ACCEPTED"}

<-- {SERVICE_MSG => "GET_PKI_REALM",
PARAMS => {
PKI_REALM => {
"0" => {
NAME => "Root Realm",
DESCRIPTION => "This is an example root realm."
}
}
}
}
}

--> {SERVICE_MSG => "GET_PKI_REALM",
PARAMS => {
PKI_REALM => $realm,
}
}

<-- {SERVICE_MSG => "GET_AUTHENTICATION_STACK",
PARAMS => {
AUTHENTICATION_STACKS => {
"0" => {
NAME => "Basic Root Auth Stack",
DESCRIPTION => "This is the basic root authentication stack."
}
}
}
}

--> {SERVICE_MSG => "GET_AUTHENTICATION_STACK",
PARAMS => {
AUTHENTICATION_STACK => "0"
}
} Example 1: Anonymous Login

<-- {SERVICE_MSG => "SERVICE_READY"}

Answer is the first command.

Example 2: Password Login

<-- {SERVICE_MSG => "GET_PASSWD_LOGIN",
PARAMS => {
NAME => "XYZ",
DESCRIPTION => "bla bla ..."
}
}

--> {LOGIN => "John Doe",
PASSWD => "12345678"}

on success ... <-- {SERVICE_MSG => "SERVICE_READY"}

on failure ... <-- {ERROR => "some already translated message"}

Session continue

--> {SERVICE_MSG => "CONTINUE_SESSION",
SESSION_ID => $ID}

<-- {SESSION_ID => $ID}

--> {SERVICE_MSG => "SESSION_ID_ACCEPTED}

<-- {SERVICE_MSG => "SERVICE_READY"}

Functions

The functions does nothing else than to support the test stuff with a working user interface dummy.

START
init
Receives messages, checks them for validity in the given state and passes them of to __handle_message if they are valid. Runs until it reaches the state 'MAIN_LOOP', which means that session initialization, PKI realm selection and login are done.
run
Receives messages, checks them for validity in the given state (MAIN_LOOP) and passes them to __handle_message if they are valid. Runs until a LOGOUT command is received.
__is_valid_message
Checks whether a given message is a valid message in the current state. Currently, this checks the message name ('SERVICE_MSG') only, could be used to validate the input as well later.
__handle_message
Handles a message by passing it off to a handler named using the service message name.
__handle_NEW_SESSION
Handles the NEW_SESSION message by creating a new session, saving it in the context and sending back the session ID. Changes the state to 'SESSION_ID_ACCEPTED'
__handle_CONTINUE_SESSION
Handles the CONTINUE_SESSION message.
__handle_PING
Handles the PING message by sending back an empty response.
__handle_SESSION_ID_ACCEPTED
Handles the 'SESSION_ID_ACCEPTED' message. It looks whether there are multiple PKI realms defined. If so, it sends back the list and changes to state 'WAITING_FOR_PKI_REALM'. If not, it looks whether an authentication stack is present. If not, it sends the list of possible stacks and changes the state to 'WAITING_FOR_AUTHENTICATION_STACK'.
__handle_GET_PKI_REALM
Handles the GET_PKI_REALM message by checking whether the received realm is valid and setting it in the context if so.
__handle_GET_AUTHENTICATION_STACK
Handles the GET_AUTHENTICATION_STACK message by checking whether the received stack is valid and setting the corresponding attribute if it is
__handle_GET_PASSWD_LOGIN
Handles the GET_PASSWD_LOGIN message by passing on the credentials to the Authentication modules 'login_step' method.
__handle_DETACH
Removes the current session from this worker but does not delete the session. The worker is now free to handle requests for other sessions.
__handle_LOGOUT
Handles the LOGOUT message by deleting the session from the backend.
__handle_STATUS
Handles the STATUS message by sending back role and user information.
__handle_COMMAND
Handles the COMMAND message by calling the corresponding API command if the user is authorized.
__pki_realm_choice_available
Checks whether more than one PKI realm is configured.
__list_authentication_stacks
Returns a list of configured authentication stacks.
__is_valid_auth_stack
Checks whether a given stack is a valid one.
__is_valid_pki_realm
Checks whether a given realm is a valid one.
__change_state
Changes the internal state.
__send_error
Sends an error message to the user.