Revision as of 14:19, 22 December 2014

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 teh 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>

@@ Line 12: / Line 12: @@
 RSA public key that must be used to encrypt any/all passwords.
 <br>When encrypting ensure PKCS1 OAEP padding is used.
-<br>May be blank on startup; will not vary once set.  The rest of the service cannot usefully be used before this is set.
+<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 ==

From OpenHome