From OpenHome

Revision as of 13:43, 11 November 2014 by Simonc (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.
Set on startup; does not change at runtime.

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.
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.
Returns a 800 fault code if the Id argument is invalid.
Returns a 801 fault code if the login was attempted but failed.

Logout

Optional action, indicating that a token returned from an earlier call to Login() is no longer required.
Returns a 800 fault code if the Id argument is invalid.
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.

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_String</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_String</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>
            </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>Logout</name>
            <argumentList>
                <argument>
                    <name>Id</name>
                    <direction>in</direction>
                    <relatedStateVariable>A_ARG_TYPE_String</relatedStateVariable>
                </argument>
                <argument>
                    <name>Token</name>
                    <direction>in</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_Bool</name>
            <dataType>boolean</dataType>
        </stateVariable>
    </serviceStateTable>
</scpd>