RAD Module Example
Example 2-8 Using Various RAD Module Elements
This example API demonstrates the use of various RAD module elements.
<?xml version="1.0" encoding="UTF-8"?>
<api xmlns="https://xmlns.oracle.com/radadr" name="com.oracle.solaris.rad.example">
<summary>
Example API
</summary>
<!-- A introductory paragraph to describe the API -->
<doc>
<para>
This API defines PAM authentication methods that may be used to authenticate
a <strong>rad(8)</strong> client. <emphasis>NOTE: this is only an example
and may not represent a working authentication interface!</emphasis>
</para>
</doc>
<version major="1" minor="0"/>
<!-- An ADR enum type -->
<!-- Each value in the enum has a short one-line description -->
<enum name="BlockType" stability="private">
<value name="CONV">
<summary>
conversation must continue
</summary>
</value>
<value name="SUCCESS">
<summary>
authentication has succeeded
</summary>
</value>
<value name="ERROR">
<summary>
authentication has failed
</summary>
</value>
</enum>
<!-- An ADR struct type -->
<!-- Each field in the struct has a short one-line description -->
<struct name="Block" stability="private">
<field type="BlockType" name="type">
<summary>
the status of the conversation
</summary>
</field>
<field name="messages" nullable="true">
<summary>
the messages to display to the user
</summary>
<list type="Message"/>
</field>
</struct>
<!-- Another ADR enum type -->
<!-- Use of the verbatim tag to document the enum values -->
<enum name="MsgType" stability="private">
<summary>Types of messages that may be returned from a PAM
conversation </summary>
<doc>
<verbatim>
+-----------------+-------------------------------------+
| MsgType | Action |
+-----------------+-------------------------------------|
| PROMPT_ECHO_OFF | Prompt the user for sensitive data, |
| | disabling echo of their response |
| PROMPT_ECHO_ON | Prompt the user for non-sensitive |
| | data, echoing their response |
| TEXT_INFO | Print a general information message |
| TEXT_INFO | Print an error message |
+-----------------+-------------------------------------+
</verbatim>
</doc>
<value name="PROMPT_ECHO_OFF" />
<value name="PROMPT_ECHO_ON" />
<value name="ERROR_MSG" />
<value name="TEXT_INFO" />
</enum>
<!-- Another ADR struct type -->
<struct name="Message" stability="private">
<field type="MsgType" name="style">
<summary>
this message's type
</summary>
</field>
<field type="string" name="message">
<summary>
the message text
</summary>
</field>
</struct>
<interface name="Authentication" stability="private">
<doc>
<!-- A paragraph that describes the interface -->
<para>
The <code>Authentication</code> interface implements a PAM exchange to
authenticate <strong>rad(8)</strong> clients. Handles to this type of
object can be retrieved from the RAD server using an object name built
with:
</para>
<!-- An ordered list - items are numbered -->
<list type="ordered">
<item>
the "<code>com.oracle.solaris.rad.pam</code>" domain name
</item>
<item>
a key named "<code>type</code>" paired with a value of
"<code>Authentication</code>"
</item>
</list>
<!-- A link to the login() method in the Authentication interface -->
<!-- A link to the Block struct -->
<para>
The <link interface="Authentication" method="login">login()</link> method
begins a PAM conversation to authenticate as a user. It returns a list
of <link struct="Block">Block</link> objects encapsulating the status of
the conversation, the messages that should be displayed, and the input
that should be collected.
</para>
<para>
At each step, when the requested input has been collected, it is
submitted using <link interface="Authentication"
method="submit">submit()</link>. This method also returns a list of
<link struct="Block">Block</link> objects, allowing the conversation to
continue indefinitely until authentication is complete.
</para>
<!-- A link to a struct field, and an enum value -->
<para>
When either of the two returns a <link struct="Block">Block</link> whose
<link struct="Block" field="type">type</link> is <link enum="BlockType"
value="SUCCESS">SUCCESS</link>, authentication has succeeded and <link
interface="Authentication" method="complete">complete()</link> should be
called to close the conversation.
</para>
<para>
A typical algorithm for walking through this conversation might be:
</para>
<!-- A program listing, with a caption -->
<example caption="Authentication interface" language="python">
import rad.connect as radcon
import rad.auth as rada
# Create a connection
rc=radcon.connect_tls("host")
# Get a native-looking python object that throws RAD exceptions
auth = rada.RadAuth(rc)
# login with username and password
auth.pam_login("jdoe", "******")
print rc
rc.close()
print rc
</example>
<para>
This example uses the rad.auth module which makes simplifying
assumptions for a default Solaris install.
</para>
</doc>
<!-- User Identity -->
<property name="user" type="string" access="ro" nullable="true" stability="private">
<summary>
gets the username of the connected user
</summary>
</property>
<!-- PAM Authentication -->
<method name="login" stability="private">
<summary>
begins a PAM conversation to authenticate as the specified user
</summary>
<result type="Block"/>
<error/>
<argument type="string" name="locale"/>
<argument type="string" name="username"/>
</method>
<method name="submit" stability="private">
<summary>
continues a PAM conversation with information collected from the
previous step
</summary>
<result type="Block"/>
<error/>
<argument name="responses">
<list type="secret"/>
</argument>
</method>
<method name="complete" stability="private">
<summary>
completes the PAM conversation with the RAD server
</summary>
</method>
</interface>
</api>