Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ././../../../../../../usr/man/man3rad/authentication-2.3rad
Real path: /usr/share/man/man3rad/authentication-2.3rad
Zurück

'\" t .\" Title: authentication-2 .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> .\" Date: 2017-02-01 .\" Manual: RAD Module Definitions .\" Source: Solaris 11.4 .\" Language: English .\" .TH "AUTHENTICATION\-2" "3rad" "2017\-02\-01" "Solaris 11.4" "RAD Module Definitions" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" authentication \- API for token\-based authentication .SH "SYNOPSIS" .nf #include <rad/client/2/authentication\&.h> cc [ flag\&.\&.\&. ] file\&.\&.\&. \fB\-lauthentication2_client\fR [ library\&.\&.\&. ] .fi .SS "interface Session" .nf const char *\ \&username\ \&; (rw) .fi .nf const char **\ \&roles\ \&; (ro) .fi .nf const char *\ \&token\ \&; (ro) .fi .nf authentication2_AuthState_t *\ \&state\ \&; (rw) .fi .nf unsigned long long\ \&timeout\ \&; (ro) .fi .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_create\fR('u .R rc_err_t \fBauthentication2_Session__rad_create\fR(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); .RS .RE .fi .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_delete\fR('u .R rc_err_t \fBauthentication2_Session__rad_delete\fR(rc_instance_t\ *inst); .RS .RE .fi .SS "interface Authentication" .nf const char *\ \&username\ \&; (ro) .fi .nf const char **\ \&roles\ \&; (ro) .fi .nf const rc_instance_t *\ \&session\ \&; (ro) .fi .nf unsigned long long\ \&timeout\ \&; (ro) .fi .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_authenticate\fR('u .R rc_err_t \fBauthentication2_Authentication_authenticate\fR(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); .RS .RE .fi .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_redeem\fR('u .R rc_err_t \fBauthentication2_Authentication_redeem\fR(rc_instance_t\ *inst, . const\ char\ *token, . rc_instance_t\ **result, . authentication2_AuthState_t\ **error); .RS .RE .fi .SS "Enumerated Types" .PP \fBenum PAMMsgStyle\fR .\" blockquote { .RS 4 .PP .nf 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; .fi .RE .\" } blockquote .PP \fBenum PAMState\fR .\" blockquote { .RS 4 .PP .nf typedef enum authentication2_PAMState { A2PAMS_CONTINUE = 0, A2PAMS_SUCCESS = 1, A2PAMS_ERROR = 2, } authentication2_PAMState_t; .fi .RE .\" } blockquote .PP \fBenum AuthScheme\fR .\" blockquote { .RS 4 .PP .nf typedef enum authentication2_AuthScheme { A2AS_PAM = 0, } authentication2_AuthScheme_t; .fi .RE .\" } blockquote .SS "Structured Types" .PP \fBstruct PAMMessage\fR .\" blockquote { .RS 4 .PP typedef struct authentication2_PAMMessage authentication2_PAMMessage_t; .PP .nf struct authentication2_PAMMessage { authentication2_PAMMsgStyle_t apamm_style; char *apamm_message; }; .fi .nf .HP \w'void\ \fBauthentication2_PAMMessage_free\fR('u .R void \fBauthentication2_PAMMessage_free\fR(authentication2_PAMMessage_t\ *in); .RS .RE .fi .RE .\" } blockquote .PP \fBstruct PAMAuthState\fR .\" blockquote { .RS 4 .PP typedef struct authentication2_PAMAuthState authentication2_PAMAuthState_t; .PP .nf struct authentication2_PAMAuthState { authentication2_PAMState_t *apamas_state; authentication2_PAMMessage_t **apamas_messages; int apamas_messages_count; char **apamas_responses; int apamas_responses_count; }; .fi .nf .HP \w'void\ \fBauthentication2_PAMAuthState_free\fR('u .R void \fBauthentication2_PAMAuthState_free\fR(authentication2_PAMAuthState_t\ *in); .RS .RE .fi .RE .\" } blockquote .PP \fBstruct AuthState\fR .\" blockquote { .RS 4 .PP typedef struct authentication2_AuthState authentication2_AuthState_t; .PP .nf struct authentication2_AuthState { authentication2_AuthScheme_t *aas_scheme; authentication2_PAMAuthState_t *aas_pam; char *aas_error; int aas_generation; }; .fi .nf .HP \w'void\ \fBauthentication2_AuthState_free\fR('u .R void \fBauthentication2_AuthState_free\fR(authentication2_AuthState_t\ *in); .RS .RE .fi .RE .\" } blockquote .SH "DESCRIPTION" .PP \fBAPI com\&.oracle\&.solaris\&.rad\&.authentication \fR\fB\&\s-2\u[1]\d\s+2\fR .PP This API provides functions for authentication using PAM and session management through the use of secure tokens\&. .SH "INTERFACES" .SS "interface Session" .PP Represents a session within RAD\&. .PP Clients should interact with this interface to: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} authenticate and obtain access to RAD .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} retrieve and redeem authentication tokens .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} obtain information about existing sessions .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} delete sessions .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} obtain session specific data, user, roles\&. .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSession Properties\fR .RS 4 .PP \fB\fIconst char *\fR\fR\ \&\fBusername\fR (\fIread\-write\fR, \fInullable\fR) \(em Name of currently authenticated user\&. .\" blockquote { .RS 4 .PP When read, this property will hold a name of the authenticated user, if any (NULL will be presented if no user has authenticated yet)\&. .PP 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\&. .PP NULL value will be ignored as if no input was provided\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session_get_username\fR('u .R rc_err_t \fBauthentication2_Session_get_username\fR(rc_instance_t\ *inst, . char\ **result, . authentication2_AuthState_t\ **error); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .PP \fIerror\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .\" blockquote { .RS 4 .PP 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\&. .RE .\" } blockquote .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Session_set_username\fR('u .R rc_err_t \fBauthentication2_Session_set_username\fR(rc_instance_t\ *inst, . const\ char\ *username, . authentication2_AuthState_t\ **error); .RS .RE .fi .\" blockquote { .RS 4 .PP Set property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIusername\fR \(em Property value written .PP \fIerror\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .\" blockquote { .RS 4 .PP 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\&. .RE .\" } blockquote .RE .\" } blockquote .RE .\" } blockquote .\" blockquote { .RS 4 .PP \fBWrite Error:\fR \fB\fIauthentication2_AuthState_t **\fR\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .\" blockquote { .RS 4 .PP 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\&. .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIconst char **\fR\fR\ \&\fBroles\fR (\fIread\-only\fR) \(em list of roles available to the authenticated user .\" blockquote { .RS 4 .PP Empty list will be returned if no roles are available\&. Please note that this module supports role assumption too \- see username property\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session_get_roles\fR('u .R rc_err_t \fBauthentication2_Session_get_roles\fR(rc_instance_t\ *inst, . char\ ***result, . int\ *result_cnt); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .PP \fIresult_cnt\fR \(em Number of items in result array .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIconst char *\fR\fR\ \&\fBtoken\fR (\fIread\-only\fR, \fInullable\fR) \(em session token .\" blockquote { .RS 4 .PP 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\&. .PP 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\&. .PP 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\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session_get_token\fR('u .R rc_err_t \fBauthentication2_Session_get_token\fR(rc_instance_t\ *inst, . char\ **result); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIauthentication2_AuthState_t *\fR\fR\ \&\fBstate\fR (\fIread\-write\fR) \(em State of the authentication session .\" blockquote { .RS 4 .PP This is the core of the authentication conversation between clients (both HTTP/REST and RPC)\&. .PP 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\&. .PP The clients need to pay attention to the \'pam\' substructure\&. .PP If \'state\' equals "SUCCESS", the authentication went fine and the \'username\' property will contain the name of the user or role that\'s authenticated\&. .PP If \'state\' equals "ERROR", the authentication failed\&. .PP 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)): .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} PROMPT_ECHO_OFF \- Prompt user, disabling echoing of response\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} PROMPT_ECHO_ON \- Prompt user, enabling echoing of response\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} ERROR_MSG \- Print error message\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} TEXT_INFO \- Print general text information\&. .RE .PP The first two require user input to be gathered by the client program and sent back to the server\&. .PP The latter two are to be just displayed to the user, no input has to be collected\&. .PP 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\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session_get_state\fR('u .R rc_err_t \fBauthentication2_Session_get_state\fR(rc_instance_t\ *inst, . authentication2_AuthState_t\ **result, . authentication2_AuthState_t\ **error); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .PP \fIerror\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Session_set_state\fR('u .R rc_err_t \fBauthentication2_Session_set_state\fR(rc_instance_t\ *inst, . authentication2_AuthState_t\ *state, . authentication2_AuthState_t\ **error); .RS .RE .fi .\" blockquote { .RS 4 .PP Set property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIstate\fR \(em Property value written .PP \fIerror\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .RE .\" } blockquote .RE .\" } blockquote .\" blockquote { .RS 4 .PP \fBRead\-Write Error:\fR \fB\fIauthentication2_AuthState_t **\fR\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .RE .\" } blockquote .PP \fB\fIunsigned long long\fR\fR\ \&\fBtimeout\fR (\fIread\-only\fR) \(em The number of seconds for a preserved authenticated session to stay alive waiting to be re\-connected to (through the token redemption)\&. .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session_get_timeout\fR('u .R rc_err_t \fBauthentication2_Session_get_timeout\fR(rc_instance_t\ *inst, . unsigned\ long\ long\ *result); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .RE .\" } blockquote .RE .\" } blockquote .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSession Create\fR .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_create\fR('u .R rc_err_t \fBauthentication2_Session__rad_create\fR(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); .RS .RE .fi .\" blockquote { .RS 4 .PP Create a new Session instance, commencing the authentication process\&. .PP 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\&. .PP 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\&. .PP Once the session has been properly authenticated, the lifetime will be reset to the value specified in \'timeout\' argument\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIusername\fR (\fInullable\fR) \(em Name of the user account the client wants to authenticate as\&. .\" blockquote { .RS 4 .PP Only normal user account could be used for direct login\&. Please see \'username\' property for details about role assumption and re\-authentication\&. .PP If NULL, PAM will ask for the username later\&. .RE .\" } blockquote .PP \fIscheme\fR (\fInullable\fR) \(em Sets the authentication scheme\&. Currently only PAM is supported\&. .\" blockquote { .RS 4 .PP If NULL, PAM is the default\&. .RE .\" } blockquote .PP \fItimeout\fR (\fInullable\fR) \(em The number of seconds for a preserved authenticated session to stay alive waiting to be re\-connected to (through the token redemption)\&. .\" blockquote { .RS 4 .PP 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)\&. .RE .\" } blockquote .PP \fIpreserve\fR (\fInullable\fR) \(em Whether to keep the session alive after the disconnect\&. .\" blockquote { .RS 4 .PP 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\&. .PP If NULL, default is TRUE, i\&.e\&. preserve the session\&. .RE .\" } blockquote .PP \fItoken\fR (\fInullable\fR) \(em Token to redeem\&. .\" blockquote { .RS 4 .PP If NULL, new authentication session will be started\&. .PP 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\&. .PP 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\&.) .PP 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\&. .RE .\" } blockquote .PP \fIresult\fR \(em New Session instance .PP \fIerror\fR \(em Only the generic \'error\' will be filled in in this case\&. .RE .\" } blockquote .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSession Retrieve\fR .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_get_name\fR('u .R rc_err_t \fBauthentication2_Session__rad_get_name\fR(adr_name_t\ **result, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP Obtain RAD name of a Session object\&. .PP \fBArguments:\fR .PP \fIresult\fR \(em RAD name .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_lookup\fR('u .R rc_err_t \fBauthentication2_Session__rad_lookup\fR(rc_conn_t\ *c, . boolean_t\ strict, . rc_instance_t\ **result, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP Lookup a Session instance\&. .PP 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\&. .PP \fBArguments:\fR .PP \fIc\fR \(em RAD connection handle .PP \fIstrict\fR \(em Strict (B_TRUE) or relaxed (B_FALSE) versioning .PP \fIresult\fR \(em RAD instance .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_list\fR('u .R rc_err_t \fBauthentication2_Session__rad_list\fR(rc_conn_t\ *c, . boolean_t\ strict, . adr_pattern_scheme_t\ scheme, . adr_name_t\ ***result, . int\ *result_count, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP List RAD names of a available Session instances\&. .PP Returns an array and array size of matching object names\&. .PP \fBArguments:\fR .PP \fIc\fR \(em RAD connection handle .PP \fIstrict\fR \(em Strict (B_TRUE) or relaxed (B_FALSE) versioning .PP \fIscheme\fR \(em Apply glob (NS_GLOB) or regex (NS_REGEX) matching .PP \fIresult\fR \(em Array of RAD names .PP \fIresult_count\fR \(em Number of names in result array .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSession Delete\fR .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Session__rad_delete\fR('u .R rc_err_t \fBauthentication2_Session__rad_delete\fR(rc_instance_t\ *inst); .RS .RE .fi .\" blockquote { .RS 4 .PP Delete and disconnect session\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .RE .\" } blockquote .RE .SS "interface Authentication" .PP Singleton interface for RPC interaction\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBAuthentication Properties\fR .RS 4 .PP \fB\fIconst char *\fR\fR\ \&\fBusername\fR (\fIread\-only\fR, \fInullable\fR) \(em Name of an authenticated user\&. .\" blockquote { .RS 4 .PP NULL if no user has authenticated yet\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_get_username\fR('u .R rc_err_t \fBauthentication2_Authentication_get_username\fR(rc_instance_t\ *inst, . char\ **result); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIconst char **\fR\fR\ \&\fBroles\fR (\fIread\-only\fR) \(em List of roles available to the authenticated user\&. .\" blockquote { .RS 4 .PP Empty list if no roles are available\&. .RE .\" } blockquote .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_get_roles\fR('u .R rc_err_t \fBauthentication2_Authentication_get_roles\fR(rc_instance_t\ *inst, . char\ ***result, . int\ *result_cnt); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .PP \fIresult_cnt\fR \(em Number of items in result array .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIconst rc_instance_t *\fR\fR\ \&\fBsession\fR (\fIread\-only\fR) \(em This is a private interface to access the connection\'s current Session instance that the RPC client authentication code code needs to use\&. .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_get_session\fR('u .R rc_err_t \fBauthentication2_Authentication_get_session\fR(rc_instance_t\ *inst, . rc_instance_t\ **result); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .RE .\" } blockquote .RE .\" } blockquote .PP \fB\fIunsigned long long\fR\fR\ \&\fBtimeout\fR (\fIread\-only\fR) \(em The PAM conversation timeout, in seconds\&. .\" blockquote { .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_get_timeout\fR('u .R rc_err_t \fBauthentication2_Authentication_get_timeout\fR(rc_instance_t\ *inst, . unsigned\ long\ long\ *result); .RS .RE .fi .\" blockquote { .RS 4 .PP Get property value\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIresult\fR \(em Property value returned .RE .\" } blockquote .RE .\" } blockquote .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBAuthentication Methods\fR .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_authenticate\fR('u .R rc_err_t \fBauthentication2_Authentication_authenticate\fR(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); .RS .RE .fi .\" blockquote { .RS 4 .PP Commence the authentication process\&. .PP This internally creates an instance of Session interface and returns it to the caller\&. .PP Once the initial authentication succeeded (only normal user can authenticate directly) we can proceed with role assumption\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fIusername\fR (\fInullable\fR) \(em See \'username\' in Session`create() method\&. .PP \fIscheme\fR (\fInullable\fR) \(em See \'scheme\' in Session`create() method\&. .PP \fItimeout\fR (\fInullable\fR) \(em See \'timeout\' in Session`create() method\&. .PP \fIpreserve\fR (\fInullable\fR) \(em See \'preserve\' in Session`create() method\&. .\" blockquote { .RS 4 .PP 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\&. .PP Changed from TRUE to FALSE in 2\&.1\&. .RE .\" } blockquote .PP \fIresult\fR \(em Reference to a newly created Session instance\&. .PP \fIerror\fR \(em Can contain PAM specific error in \'pam\' or generic error in \'error\'\&. .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication_redeem\fR('u .R rc_err_t \fBauthentication2_Authentication_redeem\fR(rc_instance_t\ *inst, . const\ char\ *token, . rc_instance_t\ **result, . authentication2_AuthState_t\ **error); .RS .RE .fi .\" blockquote { .RS 4 .PP Redeem a token that was acquired from earlier\&. .PP 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\&. .PP 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\&. .PP \fBArguments:\fR .PP \fIinst\fR \(em RAD instance .PP \fItoken\fR \(em See \'token\' in Session`create() method\&. .PP \fIresult\fR \(em Reference to a Session instance corresponding to given token\&. .PP \fIerror\fR \(em Only the generic \'error\' will be filled in this case\&. .RE .\" } blockquote .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBAuthentication Retrieve\fR .RS 4 .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication__rad_get_name\fR('u .R rc_err_t \fBauthentication2_Authentication__rad_get_name\fR(adr_name_t\ **result, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP Obtain RAD name of a Authentication object\&. .PP \fBArguments:\fR .PP \fIresult\fR \(em RAD name .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication__rad_lookup\fR('u .R rc_err_t \fBauthentication2_Authentication__rad_lookup\fR(rc_conn_t\ *c, . boolean_t\ strict, . rc_instance_t\ **result, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP Lookup a Authentication instance\&. .PP 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\&. .PP \fBArguments:\fR .PP \fIc\fR \(em RAD connection handle .PP \fIstrict\fR \(em Strict (B_TRUE) or relaxed (B_FALSE) versioning .PP \fIresult\fR \(em RAD instance .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .nf .HP \w'rc_err_t\ \fBauthentication2_Authentication__rad_list\fR('u .R rc_err_t \fBauthentication2_Authentication__rad_list\fR(rc_conn_t\ *c, . boolean_t\ strict, . adr_pattern_scheme_t\ scheme, . adr_name_t\ ***result, . int\ *result_count, . int\ n, . \&.\&.\&.); .RS .RE .fi .\" blockquote { .RS 4 .PP List RAD names of a available Authentication instances\&. .PP Returns an array and array size of matching object names\&. .PP \fBArguments:\fR .PP \fIc\fR \(em RAD connection handle .PP \fIstrict\fR \(em Strict (B_TRUE) or relaxed (B_FALSE) versioning .PP \fIscheme\fR \(em Apply glob (NS_GLOB) or regex (NS_REGEX) matching .PP \fIresult\fR \(em Array of RAD names .PP \fIresult_count\fR \(em Number of names in result array .PP \fIn\fR \(em Number of key\-value pairs provided as variadic arguments .PP \&.\&.\&. \(em Optional key\-value pairs that compose the primary key .RE .\" } blockquote .RE .SH "ENUMERATED TYPES" .PP \fBenum PAMMsgStyle\fR \(em Style of a PAM message\&. .\" blockquote { .RS 4 .PP .nf 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; .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP A2PAMMS_PROMPT_ECHO_OFF (0) \(em A request for non\-sensitive information, such as a username\&. Client must respond\&. Corresponds to PAM_PROMPT_ECHO_OFF in pam_start(3PAM)\&. .PP A2PAMMS_PROMPT_ECHO_ON (1) \(em 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)\&. .PP A2PAMMS_ERROR_MSG (2) \(em 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)\&. .PP A2PAMMS_TEXT_INFO (3) \(em 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)\&. .RE .\" } blockquote .PP \fBenum PAMState\fR \(em State of the PAM authentication process\&. .\" blockquote { .RS 4 .PP .nf typedef enum authentication2_PAMState { A2PAMS_CONTINUE = 0, A2PAMS_SUCCESS = 1, A2PAMS_ERROR = 2, } authentication2_PAMState_t; .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP A2PAMS_CONTINUE (0) \(em 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\&. .PP A2PAMS_SUCCESS (1) \(em Authentication has succeeded\&. .PP A2PAMS_ERROR (2) \(em Authentication has failed\&. .RE .\" } blockquote .PP \fBenum AuthScheme\fR \(em Type of authentication\&. PAM is the only one supported at the moment\&. .\" blockquote { .RS 4 .PP .nf typedef enum authentication2_AuthScheme { A2AS_PAM = 0, } authentication2_AuthScheme_t; .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP A2AS_PAM (0) .RE .\" } blockquote .SH "STRUCTURED TYPES" .PP \fBstruct PAMMessage\fR \(em Individual PAM message\&. .\" blockquote { .RS 4 .PP typedef struct authentication2_PAMMessage authentication2_PAMMessage_t; .PP .nf struct authentication2_PAMMessage { authentication2_PAMMsgStyle_t apamm_style; char *apamm_message; }; .fi .nf .HP \w'void\ \fBauthentication2_PAMMessage_free\fR('u .R void \fBauthentication2_PAMMessage_free\fR(authentication2_PAMMessage_t\ *in); .RS .RE .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP \fBFields:\fR .PP \fIapamm_style\fR .PP \fIapamm_message\fR .RE .\" } blockquote .PP \fBstruct PAMAuthState\fR \(em Describes state of the PAM authentication\&. .\" blockquote { .RS 4 .PP typedef struct authentication2_PAMAuthState authentication2_PAMAuthState_t; .PP .nf struct authentication2_PAMAuthState { authentication2_PAMState_t *apamas_state; authentication2_PAMMessage_t **apamas_messages; int apamas_messages_count; char **apamas_responses; int apamas_responses_count; }; .fi .nf .HP \w'void\ \fBauthentication2_PAMAuthState_free\fR('u .R void \fBauthentication2_PAMAuthState_free\fR(authentication2_PAMAuthState_t\ *in); .RS .RE .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP 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)\&. .PP 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\&. .RE .\" } blockquote .\" blockquote { .RS 4 .PP \fBFields:\fR .PP \fIapamas_state\fR .PP \fIapamas_messages\fR \(em PAM\'s messages and/or questions for the client\&. See PAMMessage for details\&. .PP \fIapamas_messages_count\fR .PP \fIapamas_responses\fR \(em Client\'s responses to the user input collection requests (i\&.e\&. PROMPT_ECHO_ON, PROMPT_ECHO_OFF)\&. .PP \fIapamas_responses_count\fR .RE .\" } blockquote .PP \fBstruct AuthState\fR \(em Represents a state of the authentication either in progress or finished (successfully or not)\&. .\" blockquote { .RS 4 .PP typedef struct authentication2_AuthState authentication2_AuthState_t; .PP .nf struct authentication2_AuthState { authentication2_AuthScheme_t *aas_scheme; authentication2_PAMAuthState_t *aas_pam; char *aas_error; int aas_generation; }; .fi .nf .HP \w'void\ \fBauthentication2_AuthState_free\fR('u .R void \fBauthentication2_AuthState_free\fR(authentication2_AuthState_t\ *in); .RS .RE .fi .RE .\" } blockquote .\" blockquote { .RS 4 .PP 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)\&. .RE .\" } blockquote .\" blockquote { .RS 4 .PP \fBFields:\fR .PP \fIaas_scheme\fR .PP \fIaas_pam\fR .\" blockquote { .RS 4 .PP 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\&. .RE .\" } blockquote .PP \fIaas_error\fR \(em 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\&. .PP \fIaas_generation\fR \(em 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\&. .RE .\" } blockquote .SH "VERSION" .PP 2\&.1 .SH "ATTRIBUTES" .PP See attributes(7) for descriptions of the following attributes: .TS allbox tab(:); cB cB. T{ ATTRIBUTE TYPE T}:T{ ATTRIBUTE VALUE T} .T& l l l l. T{ Availability T}:T{ system/management/rad T} T{ Interface Stability T}:T{ Private T} .TE .sp 1 .SH "SEE ALSO" .PP \fBrad\fR(8) .SH "NOTES" .IP " 1." 4 Accessing Python documentation for this module: .sp .RS 4 .nf $ pydoc rad.bindings.com.oracle.solaris.rad.authentication_2 .fi .RE