From OpenHome

(Difference between revisions)
Jump to: navigation, search
(Created page with "= Overview = The Credentials provides access to username, password and current status of all remote services that require unique logins. <br>If a device's [[Developer:ProductSer...")
(→ReLogin)
 
(8 intermediate revisions not shown)
Line 11: Line 11:
== PublicKey ==
== PublicKey ==
RSA public key that must be used to encrypt any/all passwords.
RSA public key that must be used to encrypt any/all passwords.
-
<br>Set on startup; does not change at runtime.
+
<br>When encrypting ensure PKCS1 OAEP padding is used.
 +
<br>May be blank on startup; will not vary once set.  With the exception of the <tt>Ids</tt> state variable, the rest of the service cannot usefully be used before this is set.
== SequenceNumber ==
== SequenceNumber ==
Line 36: Line 37:
<br>Username, password and enabled will only change in response to invocations of the Credentials service.  The password is encrypted so is not suitable for user display.  Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
<br>Username, password and enabled will only change in response to invocations of the Credentials service.  The password is encrypted so is not suitable for user display.  Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
<br>Status may change in response to runtime events.  e.g. If an account expires, the status may change to include the error returned by the remote service provider.  Status is only set for error cases - a blank status indicates that a service is functioning correctly.  The exact format of status content varies between services.
<br>Status may change in response to runtime events.  e.g. If an account expires, the status may change to include the error returned by the remote service provider.  Status is only set for error cases - a blank status indicates that a service is functioning correctly.  The exact format of status content varies between services.
 +
<br>Data contains any other service-specific information.  The format of content varies between services.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
== Login ==
== Login ==
-
Read a token indicating that a registered user has logged in to a remote service.  This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account.
+
Read a token indicating that a registered user has logged in to a remote service.  This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account.  The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
<br>Returns a 801 fault code if the login was attempted but failed.
<br>Returns a 801 fault code if the login was attempted but failed.
-
== Logout ==
+
== ReLogin ==
-
Optional action, indicating that a token returned from an earlier call to <tt>Login()</tt> is no longer required.
+
Refresh an existing token returned from <tt>Login()</tt>.  This should only be called after the remote service has indicated that the current token has expired and is no longer valid.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
<br>Returns a 800 fault code if the <tt>Id</tt> argument is invalid.
-
<br>Returns a 802 fault code if the logout was attempted but failed.  This error is reported for information only; there is nothing a client should do in response to it.
+
<br>Returns a 801 fault code if a new login was attempted but failed.
== GetIds ==
== GetIds ==
Line 89: Line 91:
                     <name>Password</name>
                     <name>Password</name>
                     <direction>in</direction>
                     <direction>in</direction>
-
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
+
                     <relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
                 </argument>
                 </argument>
             </argumentList>
             </argumentList>
Line 134: Line 136:
                     <name>Password</name>
                     <name>Password</name>
                     <direction>out</direction>
                     <direction>out</direction>
-
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
+
                     <relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
                 </argument>
                 </argument>
                 <argument>
                 <argument>
Line 143: Line 145:
                 <argument>
                 <argument>
                     <name>Status</name>
                     <name>Status</name>
 +
                    <direction>out</direction>
 +
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
 +
                </argument>
 +
                <argument>
 +
                    <name>Data</name>
                     <direction>out</direction>
                     <direction>out</direction>
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
Line 164: Line 171:
         </action>
         </action>
         <action>
         <action>
-
             <name>Logout</name>
+
             <name>ReLogin</name>
             <argumentList>
             <argumentList>
                 <argument>
                 <argument>
Line 172: Line 179:
                 </argument>
                 </argument>
                 <argument>
                 <argument>
-
                     <name>Token</name>
+
                     <name>CurrentToken</name>
                     <direction>in</direction>
                     <direction>in</direction>
 +
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
 +
                </argument>
 +
                <argument>
 +
                    <name>NewToken</name>
 +
                    <direction>out</direction>
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                     <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                 </argument>
                 </argument>
Line 225: Line 237:
             <name>A_ARG_TYPE_String</name>
             <name>A_ARG_TYPE_String</name>
             <dataType>string</dataType>
             <dataType>string</dataType>
 +
        </stateVariable>
 +
        <stateVariable sendEvents="no">
 +
            <name>A_ARG_TYPE_Binary</name>
 +
            <dataType>bin.base64</dataType>
         </stateVariable>
         </stateVariable>
         <stateVariable sendEvents="no">
         <stateVariable sendEvents="no">

Latest revision as of 11:31, 9 January 2015

Contents

Overview

The Credentials provides access to username, password and current status of all remote services that require unique logins.
If a device's Product service reports an attribute 'Credentials', then that device is guaranteed to bear the Credentials service.

State Variables

Ids

Space separated list of identifiers for services whose credentials can be set.
Set on startup; does not change at runtime.

PublicKey

RSA public key that must be used to encrypt any/all passwords.
When encrypting ensure PKCS1 OAEP padding is used.
May be blank on startup; will not vary once set. With the exception of the Ids state variable, the rest of the service cannot usefully be used before this is set.

SequenceNumber

Increases whenever any aspect of state for any user of credentials listed in Ids changes. The client is responsible for polling each Id they are interested in to determine what has changed.

Actions

Set

Set the username and password for a given service. The password must be encrypted using the RSA public key in the PublicKey state variable.
Calling this action automatically enables the service.
Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, SequenceNumber will automatically change.
Returns a 800 fault code if the Id argument is invalid.

Clear

Remove both username and password for a given service.
Note that some processing may happen asynchronously. If any of username, password or enabled states are changed for the service, SequenceNumber will automatically change.
Returns a 800 fault code if the Id argument is invalid.

SetEnabled

Set or clear the enabled state of a service. Disabling a service temporarily prevents its use by a device but allows the device to retain the username/password for later use (if the service is re-enabled by calling SetEnabled() again).
Returns a 800 fault code if the Id argument is invalid.

Get

Retrieve username, password, status and enabled state for a service.
Username, password and enabled will only change in response to invocations of the Credentials service. The password is encrypted so is not suitable for user display. Clients can infer whether a password has been set by checking whether the value returned has non-zero length.
Status may change in response to runtime events. e.g. If an account expires, the status may change to include the error returned by the remote service provider. Status is only set for error cases - a blank status indicates that a service is functioning correctly. The exact format of status content varies between services.
Data contains any other service-specific information. The format of content varies between services.
Returns a 800 fault code if the Id argument is invalid.

Login

Read a token indicating that a registered user has logged in to a remote service. This allows control points to access data that is specific to a certain user account without requiring access to the (sensitive) password for that account. The data returned may vary between credential-consuming services; the control point is responsible for knowing how to interpret it.
Returns a 800 fault code if the Id argument is invalid.
Returns a 801 fault code if the login was attempted but failed.

ReLogin

Refresh an existing token returned from Login(). This should only be called after the remote service has indicated that the current token has expired and is no longer valid.
Returns a 800 fault code if the Id argument is invalid.
Returns a 801 fault code if a new login was attempted but failed.

GetIds

Read the value of the Ids state variable.

GetPublicKey

Read the value of the PublicKey state variable.

GetSequenceNumber

Read the value of the SequenceNumber state variable.

Technical Details 

   Domain  : av.openhome.org
   Name    : Credentials
   Version : 1

Service Description (XML) 

<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <actionList>
        <action>
            <name>Set</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>UserName</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Password</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Clear</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>SetEnabled</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Enabled</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Get</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>UserName</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Password</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_Binary</relatedStateVariable>
                </argument>
                <argument>
                    <name>Enabled</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_Bool</relatedStateVariable>
                </argument>
                <argument>
                    <name>Status</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Data</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>Login</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Token</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>ReLogin</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>CurrentToken</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>NewToken</name>
                    <direction>out</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>GetIds</name>
            <argumentList>
                <argument>
                    <name>Ids</name>
                    <direction>out</direction>
                    <relatedStateVariable>Ids</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>GetPublicKey</name>
            <argumentList>
                <argument>
                    <name>PublicKey</name>
                    <direction>out</direction>
                    <relatedStateVariable>PublicKey</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
        <action>
            <name>GetSequenceNumber</name>
            <argumentList>
                <argument>
                    <name>SequenceNumber</name>
                    <direction>out</direction>
                    <relatedStateVariable>SequenceNumber</relatedStateVariable>
                </argument>
            </argumentList>
        </action>
    </actionList>
    <serviceStateTable>
        <stateVariable sendEvents="yes">
            <name>Ids</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>PublicKey</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="yes">
            <name>SequenceNumber</name>
            <dataType>ui4</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>A_ARG_TYPE_String</name>
            <dataType>string</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>A_ARG_TYPE_Binary</name>
            <dataType>bin.base64</dataType>
        </stateVariable>
        <stateVariable sendEvents="no">
            <name>A_ARG_TYPE_Bool</name>
            <dataType>boolean</dataType>
        </stateVariable>
    </serviceStateTable>
</scpd>
Retrieved from "http://wiki.openhome.org/wiki/Av:Developer:CredentialsService"