Simonc: Created page with "= Credentials Service = == Overview == The Credentials service provides access to username, password and current status of all remote services that require unique logins. If a d..."

2015-12-15T13:09:24Z

Created page with "= Credentials Service = == Overview == The Credentials service provides access to username, password and current status of all remote services that require unique logins. If a d..."

New page

= Credentials Service =
== Overview ==
The Credentials service provides access to username, password and current status of all remote services that require unique logins.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Credentials"</tt>, then that device is guaranteed to bear the Credentials service. If the Credentials service is available, all its properties and actions must be fully implemented.

== Evented Properties ==
=== 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 <tt>Ids</tt> 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 <tt>Ids</tt> changes. The client is responsible for polling each Id they are interested in to determine what has changed.

== Actions ==
=== Set ===
<tt>
Arguments: (in string id, in string username, in string password)
</tt> 
Set the username and password for a given service. The password must be encrypted using the RSA public key in the <tt>PublicKey</tt> 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, <tt>SequenceNumber</tt> will automatically change.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Clear ===
<tt>
Arguments: (in string id)
</tt> 
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, <tt>SequenceNumber</tt> will automatically change.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== SetEnabled ===
<tt>
Arguments: (in string id, in bool enabled
</tt> 
Set or clear the <tt>Enabled</tt> 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 <tt>SetEnabled()</tt> again).

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Get ===
<tt>
Arguments: (in string id, out string username, out string encPassword, out bool enabled, out string status, out string data)
</tt> 
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 <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.

=== Login ===
<tt>
Arguments: (in string id, out string token)
</tt> 
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 <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.
 Returns a <tt>801</tt> fault code if the login was attempted but failed.

=== Relogin ===
<tt>
Arguments: (in string id, in string currentToken, out string newToken)
</tt> 
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.

Returns a <tt>800</tt> fault code if the <tt>Id</tt> argument is invalid.
 Returns a <tt>801</tt> fault code if a new login was attempted but failed.

=== GetIds ===
<tt>
Arguments: (out string ids)
</tt> 
Read the value of the <tt>Ids</tt> property.

=== GetPublicKey ===
<tt>
Arguments: (out string key)
</tt> 
Read the value of the <tt>PublicKey</tt> property.

=== GetSequenceNumber ===
<tt>
Arguments: (out uint seq)
</tt> 
Read the value of the <tt>SequenceNumber</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Credentials"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="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>
</syntaxhighlight>

Av:Developer:Eriskay:CredentialsService - Revision history

Simonc: Created page with "= Credentials Service = == Overview == The Credentials service provides access to username, password and current status of all remote services that require unique logins. If a d..."