authentication-2 - based authentication
#include <rad/client/2/authentication.h> cc [ flag... ] file... -lauthentication2_client [ library... ] interface Session const char * username ; (rw) const char ** roles ; (ro) const char * token ; (ro) authentication2_AuthState_t * state ; (rw) unsigned long long timeout ; (ro) rc_err_t authentication2_Session__rad_create(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); rc_err_t authentication2_Session__rad_delete(rc_instance_t *inst); interface Authentication const char * username ; (ro) const char ** roles ; (ro) const rc_instance_t * session ; (ro) unsigned long long timeout ; (ro) rc_err_t authentication2_Authentication_authenticate(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, rc_instance_t **result, authentication2_AuthState_t **error); rc_err_t authentication2_Authentication_redeem(rc_instance_t *inst, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); Enumerated Types enum PAMMsgStyle typedef enum authentication2_PAMMsgStyle { A2PAMMS_PROMPT_ECHO_OFF = 0, A2PAMMS_PROMPT_ECHO_ON = 1, A2PAMMS_ERROR_MSG = 2, A2PAMMS_TEXT_INFO = 3, } authentication2_PAMMsgStyle_t; enum PAMState typedef enum authentication2_PAMState { A2PAMS_CONTINUE = 0, A2PAMS_SUCCESS = 1, A2PAMS_ERROR = 2, } authentication2_PAMState_t; enum AuthScheme typedef enum authentication2_AuthScheme { A2AS_PAM = 0, } authentication2_AuthScheme_t; Structured Types struct PAMMessage typedef struct authentication2_PAMMessage authentication2_PAMMessage_t; struct authentication2_PAMMessage { authentication2_PAMMsgStyle_t apamm_style; char *apamm_message; }; void authentication2_PAMMessage_free(authentication2_PAMMessage_t *in); struct PAMAuthState typedef struct authentication2_PAMAuthState authentication2_PAMAuthState_t; struct authentication2_PAMAuthState { authentication2_PAMState_t *apamas_state; authentication2_PAMMessage_t **apamas_messages; int apamas_messages_count; char **apamas_responses; int apamas_responses_count; }; void authentication2_PAMAuthState_free(authentication2_PAMAuthState_t *in); struct AuthState typedef struct authentication2_AuthState authentication2_AuthState_t; struct authentication2_AuthState { authentication2_AuthScheme_t *aas_scheme; authentication2_PAMAuthState_t *aas_pam; char *aas_error; int aas_generation; }; void authentication2_AuthState_free(authentication2_AuthState_t *in);
AUTHENTICATION-2(3rad) RAD Module Definitions AUTHENTICATION-2(3rad) NAME authentication - API for token-based authentication SYNOPSIS #include <rad/client/2/authentication.h> cc [ flag... ] file... -lauthentication2_client [ library... ] interface Session const char * username ; (rw) const char ** roles ; (ro) const char * token ; (ro) authentication2_AuthState_t * state ; (rw) unsigned long long timeout ; (ro) rc_err_t authentication2_Session__rad_create(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); rc_err_t authentication2_Session__rad_delete(rc_instance_t *inst); interface Authentication const char * username ; (ro) const char ** roles ; (ro) const rc_instance_t * session ; (ro) unsigned long long timeout ; (ro) rc_err_t authentication2_Authentication_authenticate(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, rc_instance_t **result, authentication2_AuthState_t **error); rc_err_t authentication2_Authentication_redeem(rc_instance_t *inst, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); Enumerated Types enum PAMMsgStyle typedef enum authentication2_PAMMsgStyle { A2PAMMS_PROMPT_ECHO_OFF = 0, A2PAMMS_PROMPT_ECHO_ON = 1, A2PAMMS_ERROR_MSG = 2, A2PAMMS_TEXT_INFO = 3, } authentication2_PAMMsgStyle_t; enum PAMState typedef enum authentication2_PAMState { A2PAMS_CONTINUE = 0, A2PAMS_SUCCESS = 1, A2PAMS_ERROR = 2, } authentication2_PAMState_t; enum AuthScheme typedef enum authentication2_AuthScheme { A2AS_PAM = 0, } authentication2_AuthScheme_t; Structured Types struct PAMMessage typedef struct authentication2_PAMMessage authentication2_PAMMessage_t; struct authentication2_PAMMessage { authentication2_PAMMsgStyle_t apamm_style; char *apamm_message; }; void authentication2_PAMMessage_free(authentication2_PAMMessage_t *in); struct PAMAuthState typedef struct authentication2_PAMAuthState authentication2_PAMAuthState_t; struct authentication2_PAMAuthState { authentication2_PAMState_t *apamas_state; authentication2_PAMMessage_t **apamas_messages; int apamas_messages_count; char **apamas_responses; int apamas_responses_count; }; void authentication2_PAMAuthState_free(authentication2_PAMAuthState_t *in); struct AuthState typedef struct authentication2_AuthState authentication2_AuthState_t; struct authentication2_AuthState { authentication2_AuthScheme_t *aas_scheme; authentication2_PAMAuthState_t *aas_pam; char *aas_error; int aas_generation; }; void authentication2_AuthState_free(authentication2_AuthState_t *in); DESCRIPTION API com.oracle.solaris.rad.authentication [1] This API provides functions for authentication using PAM and session management through the use of secure tokens. INTERFACES interface Session Represents a session within RAD. Clients should interact with this interface to: o authenticate and obtain access to RAD o retrieve and redeem authentication tokens o obtain information about existing sessions o delete sessions o obtain session specific data, user, roles. Session Properties const char * username (read-write, nullable) -- Name of currently authenticated user. When read, this property will hold a name of the authenticated user, if any (NULL will be presented if no user has authenticated yet). When written to, and given the session was already successfully authenticated (i.e. reading the property returns non-NULL result), the re-authentication (or role assumption) process will be started. NULL value will be ignored as if no input was provided. rc_err_t authentication2_Session_get_username(rc_instance_t *inst, char **result, authentication2_AuthState_t **error); Get property value. Arguments: inst -- RAD instance result -- Property value returned error -- Can contain PAM specific error in 'pam' or generic error in 'error'. If the session hasn't been authenticated yet (i.e. reading the property returns NULL), writing to the property will result in an 'insufficient privileges' error. rc_err_t authentication2_Session_set_username(rc_instance_t *inst, const char *username, authentication2_AuthState_t **error); Set property value. Arguments: inst -- RAD instance username -- Property value written error -- Can contain PAM specific error in 'pam' or generic error in 'error'. If the session hasn't been authenticated yet (i.e. reading the property returns NULL), writing to the property will result in an 'insufficient privileges' error. Write Error: authentication2_AuthState_t ** -- Can contain PAM specific error in 'pam' or generic error in 'error'. If the session hasn't been authenticated yet (i.e. reading the property returns NULL), writing to the property will result in an 'insufficient privileges' error. const char ** roles (read-only) -- list of roles available to the authenticated user Empty list will be returned if no roles are available. Please note that this module supports role assumption too - see username property. rc_err_t authentication2_Session_get_roles(rc_instance_t *inst, char ***result, int *result_cnt); Get property value. Arguments: inst -- RAD instance result -- Property value returned result_cnt -- Number of items in result array const char * token (read-only, nullable) -- session token HTTP/REST clients usually don't have to read this one explicitly as the framework will send it to them in an HTTP cookie. RPC clients will need to read it before they disconnect from the connection on which they created the new session using authenticate() method of the Authentication interface. Will be NULL if no token has been associated with the session, i.e. the client didn't request the session to be preserved when creating it. If a client tries to read the 'token' property from a Session instance that it didn't create or didn't successfully reconnect to (through token redemption), a string "(hidden)" will be returned instead. rc_err_t authentication2_Session_get_token(rc_instance_t *inst, char **result); Get property value. Arguments: inst -- RAD instance result -- Property value returned authentication2_AuthState_t * state (read-write) -- State of the authentication session This is the core of the authentication conversation between clients (both HTTP/REST and RPC). When read, it will reflect the state of the session, i.e. either whether the authentication is in progress, has failed or succeeded. In the future, this API will be able to support various underlying authentication mechanisms if needed, but currently PAM is the only supported one. The clients need to pay attention to the 'pam' substructure. If 'state' equals "SUCCESS", the authentication went fine and the 'username' property will contain the name of the user or role that's authenticated. If 'state' equals "ERROR", the authentication failed. If 'state' equals "CONTINUE", then PAM either wants the client to display a piece of information or error to the user or gather user input. In this case the 'messages' array will be populated with messages that have 'style' and 'message' filled in. The possible 'style' values and required client action are as follows (see more in pam_start(3PAM)): o PROMPT_ECHO_OFF - Prompt user, disabling echoing of response. o PROMPT_ECHO_ON - Prompt user, enabling echoing of response. o ERROR_MSG - Print error message. o TEXT_INFO - Print general text information. The first two require user input to be gathered by the client program and sent back to the server. The latter two are to be just displayed to the user, no input has to be collected. The collected input from the user is to be sent to the server by writing to the 'state' property of the session, specifically by filling in the 'responses' list in the 'pam' sub-structure (the server disregards any other information in the state structure sent by the client). There must be exactly as many responses as there were messages from the server of the PROMPT_ECHO_ON or PROMPT_ECHO_OFF style. rc_err_t authentication2_Session_get_state(rc_instance_t *inst, authentication2_AuthState_t **result, authentication2_AuthState_t **error); Get property value. Arguments: inst -- RAD instance result -- Property value returned error -- Can contain PAM specific error in 'pam' or generic error in 'error'. rc_err_t authentication2_Session_set_state(rc_instance_t *inst, authentication2_AuthState_t *state, authentication2_AuthState_t **error); Set property value. Arguments: inst -- RAD instance state -- Property value written error -- Can contain PAM specific error in 'pam' or generic error in 'error'. Read-Write Error: authentication2_AuthState_t ** -- Can contain PAM specific error in 'pam' or generic error in 'error'. unsigned long long timeout (read-only) -- The number of seconds for a preserved authenticated session to stay alive waiting to be re-connected to (through the token redemption). rc_err_t authentication2_Session_get_timeout(rc_instance_t *inst, unsigned long long *result); Get property value. Arguments: inst -- RAD instance result -- Property value returned Session Create rc_err_t authentication2_Session__rad_create(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); Create a new Session instance, commencing the authentication process. For HTTP/REST clients, a secure token is returned in the HTTP cookie, the RPC clients (who preferably started the authentication process using Authentication`authenticate()) will need to read the token explicitly from the 'token' property if they need to be able to re-connect to the session later. Upon creation, the session (and the associated token) will be good for a default of 180 seconds (configurable through rad(8) -e command line option or through config/timeout SMF property), i.e. client has (a default of) 180 seconds to authenticate. Once the session has been properly authenticated, the lifetime will be reset to the value specified in 'timeout' argument. Arguments: inst -- RAD instance username (nullable) -- Name of the user account the client wants to authenticate as. Only normal user account could be used for direct login. Please see 'username' property for details about role assumption and re-authentication. If NULL, PAM will ask for the username later. scheme (nullable) -- Sets the authentication scheme. Currently only PAM is supported. If NULL, PAM is the default. timeout (nullable) -- The number of seconds for a preserved authenticated session to stay alive waiting to be re-connected to (through the token redemption). If not specified (NULL), the default timeout is 3600 seconds. The default timeout can be changed in SMF through 'config/session_timeout' property (see rad(8) manpage). preserve (nullable) -- Whether to keep the session alive after the disconnect. Controls whether the session will be preserved after the connection has been closed in which case the token will be sent in the cookie to the HTTP/REST client. RPC clients need to read the token from the 'token' property before they disconnected. If NULL, default is TRUE, i.e. preserve the session. token (nullable) -- Token to redeem. If NULL, new authentication session will be started. If not NULL, no other arguments are looked at and we'll try to redeem the token, i.e. connect the caller to existing session if the token matches. Upon successful token redemption, the session's remaining time to live (specified in seconds) is reset to the original value (either defined system wide in SMF property 'config/session_timeout or specified by a client when the session was created.) In HTTP/REST interaction, and provided that properly working HTTP client that can handle HTTP cookies is used, this argument does not have to ever be used as the RAD authentication framework handles HTTP cookies (and hence the token stored in one) automatically. result -- New Session instance error -- Only the generic 'error' will be filled in in this case. Session Retrieve rc_err_t authentication2_Session__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a Session object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t authentication2_Session__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a Session instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t authentication2_Session__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available Session instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key Session Delete rc_err_t authentication2_Session__rad_delete(rc_instance_t *inst); Delete and disconnect session. Arguments: inst -- RAD instance interface Authentication Singleton interface for RPC interaction. Authentication Properties const char * username (read-only, nullable) -- Name of an authenticated user. NULL if no user has authenticated yet. rc_err_t authentication2_Authentication_get_username(rc_instance_t *inst, char **result); Get property value. Arguments: inst -- RAD instance result -- Property value returned const char ** roles (read-only) -- List of roles available to the authenticated user. Empty list if no roles are available. rc_err_t authentication2_Authentication_get_roles(rc_instance_t *inst, char ***result, int *result_cnt); Get property value. Arguments: inst -- RAD instance result -- Property value returned result_cnt -- Number of items in result array const rc_instance_t * session (read-only) -- This is a private interface to access the connection's current Session instance that the RPC client authentication code code needs to use. rc_err_t authentication2_Authentication_get_session(rc_instance_t *inst, rc_instance_t **result); Get property value. Arguments: inst -- RAD instance result -- Property value returned unsigned long long timeout (read-only) -- The PAM conversation timeout, in seconds. rc_err_t authentication2_Authentication_get_timeout(rc_instance_t *inst, unsigned long long *result); Get property value. Arguments: inst -- RAD instance result -- Property value returned Authentication Methods rc_err_t authentication2_Authentication_authenticate(rc_instance_t *inst, const char *username, authentication2_AuthScheme_t *scheme, unsigned long long *timeout, boolean_t *preserve, rc_instance_t **result, authentication2_AuthState_t **error); Commence the authentication process. This internally creates an instance of Session interface and returns it to the caller. Once the initial authentication succeeded (only normal user can authenticate directly) we can proceed with role assumption. Arguments: inst -- RAD instance username (nullable) -- See 'username' in Session`create() method. scheme (nullable) -- See 'scheme' in Session`create() method. timeout (nullable) -- See 'timeout' in Session`create() method. preserve (nullable) -- See 'preserve' in Session`create() method. The nature of the RPC clients is such that they keep a connection open for the whole duration of their interaction and therefore this argument defaults to FALSE. Changed from TRUE to FALSE in 2.1. result -- Reference to a newly created Session instance. error -- Can contain PAM specific error in 'pam' or generic error in 'error'. rc_err_t authentication2_Authentication_redeem(rc_instance_t *inst, const char *token, rc_instance_t **result, authentication2_AuthState_t **error); Redeem a token that was acquired from earlier. Client can reconnect to an existing Session that's either already authenticated (or where authentication failed) or where authentication is still in progress. Timeouts need to be observed. The following example shows the use the RPC API. The exercise to implement load_token() (and complementary store_token()) is left to the consumer of this API. Arguments: inst -- RAD instance token -- See 'token' in Session`create() method. result -- Reference to a Session instance corresponding to given token. error -- Only the generic 'error' will be filled in this case. Authentication Retrieve rc_err_t authentication2_Authentication__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a Authentication object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t authentication2_Authentication__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a Authentication instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t authentication2_Authentication__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available Authentication instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key ENUMERATED TYPES enum PAMMsgStyle -- Style of a PAM message. typedef enum authentication2_PAMMsgStyle { A2PAMMS_PROMPT_ECHO_OFF = 0, A2PAMMS_PROMPT_ECHO_ON = 1, A2PAMMS_ERROR_MSG = 2, A2PAMMS_TEXT_INFO = 3, } authentication2_PAMMsgStyle_t; A2PAMMS_PROMPT_ECHO_OFF (0) -- A request for non-sensitive information, such as a username. Client must respond. Corresponds to PAM_PROMPT_ECHO_OFF in pam_start(3PAM). A2PAMMS_PROMPT_ECHO_ON (1) -- A request for secure/sensitive information, such as a password or passphrase. Client must send a response. Corresponds to PAM_PROMPT_ECHO_ON in pam_start(3PAM). A2PAMMS_ERROR_MSG (2) -- An error message to display to the user attempting authentication. Client mustn't respond to this one. Corresponds to PAM_ERROR_MSG in pam_start(3PAM). A2PAMMS_TEXT_INFO (3) -- An informational message to display to the user attempting authentication. Client mustn't respond to this one. Corresponds to PAM_TEXT_INFO in pam_start(3PAM). enum PAMState -- State of the PAM authentication process. typedef enum authentication2_PAMState { A2PAMS_CONTINUE = 0, A2PAMS_SUCCESS = 1, A2PAMS_ERROR = 2, } authentication2_PAMState_t; A2PAMS_CONTINUE (0) -- Authenticating session in progress. Typically the PAM invoked conversation function in order to send message(s) to the client to display to the user and/or to request input from the user that the client needs to collect and send back to the server. A2PAMS_SUCCESS (1) -- Authentication has succeeded. A2PAMS_ERROR (2) -- Authentication has failed. enum AuthScheme -- Type of authentication. PAM is the only one supported at the moment. typedef enum authentication2_AuthScheme { A2AS_PAM = 0, } authentication2_AuthScheme_t; A2AS_PAM (0) STRUCTURED TYPES struct PAMMessage -- Individual PAM message. typedef struct authentication2_PAMMessage authentication2_PAMMessage_t; struct authentication2_PAMMessage { authentication2_PAMMsgStyle_t apamm_style; char *apamm_message; }; void authentication2_PAMMessage_free(authentication2_PAMMessage_t *in); Fields: apamm_style apamm_message struct PAMAuthState -- Describes state of the PAM authentication. typedef struct authentication2_PAMAuthState authentication2_PAMAuthState_t; struct authentication2_PAMAuthState { authentication2_PAMState_t *apamas_state; authentication2_PAMMessage_t **apamas_messages; int apamas_messages_count; char **apamas_responses; int apamas_responses_count; }; void authentication2_PAMAuthState_free(authentication2_PAMAuthState_t *in); The state is described in the 'state' field. The structure then holds messages (and/or input requests) that PAM would like the client to act upon (the 'messages' field). Finally, there's 'responses' field in the structure through which client is expected to supply PAM conversation responses to the server (see writable 'state' property in the Session interface). All fields are nullable here because we want to use the same structure for writing to the 'state' property as well and don't want to require the client to specify anything but 'responses' in that case. Fields: apamas_state apamas_messages -- PAM's messages and/or questions for the client. See PAMMessage for details. apamas_messages_count apamas_responses -- Client's responses to the user input collection requests (i.e. PROMPT_ECHO_ON, PROMPT_ECHO_OFF). apamas_responses_count struct AuthState -- Represents a state of the authentication either in progress or finished (successfully or not). typedef struct authentication2_AuthState authentication2_AuthState_t; struct authentication2_AuthState { authentication2_AuthScheme_t *aas_scheme; authentication2_PAMAuthState_t *aas_pam; char *aas_error; int aas_generation; }; void authentication2_AuthState_free(authentication2_AuthState_t *in); Please see the note about nullable fields in PAMAuthState as the same principle applies here for writing to the 'state' property. This applies to 'scheme' and 'error' (for writing). Fields: aas_scheme aas_pam If NULL when read, no PAM specific state was relevant. This will mostly happen when this structure is returned in error payload and non-PAM error message is returned in 'error' field. aas_error -- Non-PAM related error. This field can be filled in when the structure is returned from a method (or property accessor) in case of error. NULL if there was no error or PAM related one was returned. aas_generation -- Generation number used for optimistic locking when the 'state' property in Session is being updated by the client. The value the client sends back must be equal to what it read from the 'state' property the last time it inspected it. VERSION 2.1 ATTRIBUTES See attributes(7) for descriptions of the following attributes: +--------------------+-----------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------------+ |Availability | system/management/rad | +--------------------+-----------------------+ |Interface Stability | Private | +--------------------+-----------------------+ SEE ALSO rad(8) NOTES 1. Accessing Python documentation for this module: $ pydoc rad.bindings.com.oracle.solaris.rad.authentication_2 Solaris 11.4 2017-02-01 AUTHENTICATION-2(3rad)