ISO/IEC 29341-8-12:2008
(Main)Information technology - UPnP Device Architecture - Part 8-12: Internet Gateway Device Control Protocol - Link Authentication Service
Information technology - UPnP Device Architecture - Part 8-12: Internet Gateway Device Control Protocol - Link Authentication Service
Ingrid Glavich Ingrid Glavich 2 10 1995-11-10T13:27:00Z 2008-11-17T15:12:00Z 2008-11-17T15:12:00Z 1 76 437 3 1 512 10.6845 Clean 21 0 0 MicrosoftInternetExplorer4 /* Style Definitions */ table.MsoNormalTable {mso-style-name:"Table Normal"; mso-tstyle-rowband-size:0; mso-tstyle-colband-size:0; mso-style-noshow:yes; mso-style-parent:""; mso-padding-alt:0cm 5.4pt 0cm 5.4pt; mso-para-margin:0cm; mso-para-margin-bottom:.0001pt; mso-pagination:widow-orphan; font-size:10.0pt; font-family:"Times New Roman";}
ISO/IEC 29341-8-12:2008(E) enables a UPnP control point to configure and control the parameters pertaining to authentication by an authentication server. The series of ISO/IEC 29341 publications defines an architecture for pervasive peer-to-peer network connectivity of intelligent appliances, wireless devices and PCs. It is designed to bring easy to use, flexible, standards-based connectivity to ad-hoc or unmanaged networks whether in the home, in a small business, public spaces or attached to the Internet.
General Information
Standards Content (Sample)
ISO/IEC 29341-8-12
Edition 1.0 2008-11
INTERNATIONAL
STANDARD
Information technology – UPnP Device Architecture –
Part 8-12: Internet Gateway Device Control Protocol – Link Authentication
Service
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form
or by any means, electronic or mechanical, including photocopying and microfilm, without permission in writing from
either IEC or IEC's member National Committee in the country of the requester.
If you have any questions about ISO/IEC copyright or have an enquiry about obtaining additional rights to this
publication, please contact the address below or your local IEC member National Committee for further information.
IEC Central Office
3, rue de Varembé
CH-1211 Geneva 20
Switzerland
Email: inmail@iec.ch
Web: www.iec.ch
About the IEC
The International Electrotechnical Commission (IEC) is the leading global organization that prepares and publishes
International Standards for all electrical, electronic and related technologies.
About IEC publications
The technical content of IEC publications is kept under constant review by the IEC. Please make sure that you have the
latest edition, a corrigenda or an amendment might have been published.
ƒ Catalogue of IEC publications: www.iec.ch/searchpub
The IEC on-line Catalogue enables you to search by a variety of criteria (reference number, text, technical committee,…).
It also gives information on projects, withdrawn and replaced publications.
ƒ IEC Just Published: www.iec.ch/online_news/justpub
Stay up to date on all new IEC publications. Just Published details twice a month all new publications released. Available
on-line and also by email.
ƒ Electropedia: www.electropedia.org
The world's leading online dictionary of electronic and electrical terms containing more than 20 000 terms and definitions
in English and French, with equivalent terms in additional languages. Also known as the International Electrotechnical
Vocabulary online.
ƒ Customer Service Centre: www.iec.ch/webstore/custserv
If you wish to give us your feedback on this publication or need further assistance, please visit the Customer Service
Centre FAQ or contact us:
Email: csc@iec.ch
Tel.: +41 22 919 02 11
Fax: +41 22 919 03 00
ISO/IEC 29341-8-12
Edition 1.0 2008-11
INTERNATIONAL
STANDARD
Information technology – UPnP Device Architecture –
Part 8-12: Internet Gateway Device Control Protocol – Link Authentication
Service
INTERNATIONAL
ELECTROTECHNICAL
COMMISSION
PRICE CODE
M
ICS 35.200 ISBN 978-2-88910-882-4
– 2 – 29341-8-12 © ISO/IEC:2008(E)
CONTENTS
FOREWORD .4
ORIGINAL UPNP DOCUMENTS (informative).6
1. Overview and Scope .8
2. Service Modeling Definitions .9
2.1. ServiceType .9
2.2. State Variables.9
2.2.1. NumberOfEntries .9
2.2.2. Identifier .9
2.2.3. Secret.10
2.2.4. SecretType.10
2.2.5. AuthType.11
2.2.6. AuthState .11
2.2.7. CredentialState .12
2.2.8. Description.12
2.2.9. MACAddress.12
2.2.10. CredentialDuration .13
2.2.11. LinkedIdentifier.13
2.2.12. LastChange.13
2.2.13. LastError.14
2.3. Eventing and Moderation .14
2.3.1. Event Model.14
2.4. Actions .16
2.4.1. GetGenericEntry .17
2.4.2. GetSpecificEntry .18
2.4.3. AddEntry .19
2.4.4. UpdateEntry.20
2.4.5. DeleteEntry .21
2.4.6. GetNumberOfEntries .22
2.4.7. FactoryDefaultReset .22
2.4.8. ResetAuthentication.23
2.4.9. Common Error Codes.23
2.5. Theory of Operation .24
2.5.1. 802.1x introduction .24
2.5.2. High level intended operation .24
2.5.3. Detailed level operation .25
2.5.4. Record format .26
2.5.5. Example using client certificate credentials.27
2.5.6. Limitations on Pending Records.27
3. XML Service Description .28
4. Test .33
29341-8-12 © ISO/IEC:2008(E) – 3 –
LIST OF TABLES
Table 1: State Variables .9
Table 1.1: allowedValueList for SecretType.10
Table 1.2: allowedValueList for AuthType.11
Table 1.3: allowedValueList for AuthState.11
Table 1.4: allowedValueList for CredentialState.12
Table 2: Event Moderation .14
Table 3: Actions.16
Table 4: Arguments for GetGenericEntry .17
Table 5: Arguments for GetSpecificEntry .18
Table 6: Arguments for AddEntry.19
Table 7: Arguments for UpdateEntry .20
Table 8: Arguments for DeleteEntry .21
Table 9: Arguments for GetNumberOfEntries.22
Table 10: Common Error Codes .23
– 4 – 29341-8-12 © ISO/IEC:2008(E)
INFORMATION TECHNOLOGY –
UPNP DEVICE ARCHITECTURE –
Part 8-12: Internet Gateway Device Control Protocol –
Link Authentication Service
FOREWORD
1) ISO (International Organization for Standardization) and IEC (International Electrotechnical Commission) form the
specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in
the development of International Standards. Their preparation is entrusted to technical committees; any ISO and
IEC member body interested in the subject dealt with may participate in this preparatory work. International
governmental and non-governmental organizations liaising with ISO and IEC also participate in this preparation.
2) In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
Draft International Standards adopted by the joint technical committee are circulated to national bodies for voting.
Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote.
3) The formal decisions or agreements of IEC and ISO on technical matters express, as nearly as possible, an
international consensus of opinion on the relevant subjects since each technical committee has representation
from all interested IEC and ISO member bodies.
4) IEC, ISO and ISO/IEC publications have the form of recommendations for international use and are accepted by
IEC and ISO member bodies in that sense. While all reasonable efforts are made to ensure that the technical
content of IEC, ISO and ISO/IEC publications is accurate, IEC or ISO cannot be held responsible for the way in
which they are used or for any misinterpretation by any end user.
5) In order to promote international uniformity, IEC and ISO member bodies undertake to apply IEC, ISO and
ISO/IEC publications transparently to the maximum extent possible in their national and regional publications.
Any divergence between any ISO/IEC publication and the corresponding national or regional publication
should be clearly indicated in the latter.
6) ISO and IEC provide no marking procedure to indicate their approval and cannot be rendered responsible for
any equipment declared to be in conformity with an ISO/IEC publication.
7) All users should ensure that they have the latest edition of this publication.
8) No liability shall attach to IEC or ISO or its directors, employees, servants or agents including individual experts
and members of their technical committees and IEC or ISO member bodies for any personal injury, property
damage or other damage of any nature whatsoever, whether direct or indirect, or for costs (including legal fees)
and expenses arising out of the publication of, use of, or reliance upon, this ISO/IEC publication or any other IEC,
ISO or ISO/IEC publications.
9) Attention is drawn to the normative references cited in this publication. Use of the referenced publications is
indispensable for the correct application of this publication.
IEC and ISO draw attention to the fact that it is claimed that compliance with this document may involve the use of
patents as indicated below.
ISO and IEC take no position concerning the evidence, validity and scope of the putative patent rights. The holders
of the putative patent rights have assured IEC and ISO that they are willing to negotiate free licences or licences
under reasonable and non-discriminatory terms and conditions with applicants throughout the world. In this
respect, the statements of the holders of the putative patent rights are registered with IEC and ISO.
Intel Corporation has informed IEC and ISO that it has patent applications or granted patents.
Information may be obtained from:
Intel Corporation
Standards Licensing Department
5200 NE Elam Young Parkway
MS: JFS-98
USA – Hillsboro, Oregon 97124
Microsoft Corporation has informed IEC and ISO that it has patent applications or granted patents as listed below:
6101499 / US; 6687755 / US; 6910068 / US; 7130895 / US; 6725281 / US; 7089307 / US; 7069312 / US;
10/783 524 /US
29341-8-12 © ISO/IEC:2008(E) – 5 –
Information may be obtained from:
Microsoft Corporation
One Microsoft Way
USA – Redmond WA 98052
Philips International B.V. has informed IEC and ISO that it has patent applications or granted patents.
Information may be obtained from:
Philips International B.V. – IP&S
High Tech campus, building 44 3A21
NL – 5656 Eindhoven
NXP B.V. (NL) has informed IEC and ISO that it has patent applications or granted patents.
Information may be obtained from:
NXP B.V. (NL)
High Tech campus 60
NL – 5656 AG Eindhoven
Matsushita Electric Industrial Co. Ltd. has informed IEC and ISO that it has patent applications or granted patents.
Information may be obtained from:
Matsushita Electric Industrial Co. Ltd.
1-3-7 Shiromi, Chuoh-ku
JP – Osaka 540-6139
Hewlett Packard Company has informed IEC and ISO that it has patent applications or granted patents as listed
below:
5 956 487 / US; 6 170 007 / US; 6 139 177 / US; 6 529 936 / US; 6 470 339 / US; 6 571 388 / US; 6 205
466 / US
Information may be obtained from:
Hewlett Packard Company
1501 Page Mill Road
USA – Palo Alto, CA 94304
Samsung Electronics Co. Ltd. has informed IEC and ISO that it has patent applications or granted patents.
Information may be obtained from:
Digital Media Business, Samsung Electronics Co. Ltd.
416 Maetan-3 Dong, Yeongtang-Gu,
KR – Suwon City 443-742
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights
other than those identified above. IEC and ISO shall not be held responsible for identifying any or all such patent
rights.
ISO/IEC 29341-8-12 was prepared by UPnP Implementers Corporation and adopted, under the PAS procedure, by
joint technical committee ISO/IEC JTC 1, Information technology, in parallel with its approval by national bodies of
ISO and IEC.
The list of all currently available parts of the ISO/IEC 29341 series, under the general title Universal plug and play
(UPnP) architecture, can be found on the IEC web site.
This International Standard has been approved by vote of the member bodies, and the voting results may be
obtained from the address given on the second title page.
– 6 – 29341-8-12 © ISO/IEC:2008(E)
ORIGINAL UPNP DOCUMENTS
(informative)
Reference may be made in this document to original UPnP documents. These references are retained in order to
maintain consistency between the specifications as published by ISO/IEC and by UPnP Implementers Corporation.
The following table indicates the original UPnP document titles and the corresponding part of ISO/IEC 29341:
UPnP Document Title ISO/IEC 29341 Part
UPnP Device Architecture 1.0 ISO/IEC 29341-1
UPnP Basic:1 Device ISO/IEC 29341-2
UPnP AV Architecture:1 ISO/IEC 29341-3-1
UPnP MediaRenderer:1 Device ISO/IEC 29341-3-2
UPnP MediaServer:1 Device ISO/IEC 29341-3-3
UPnP AVTransport:1 Service ISO/IEC 29341-3-10
UPnP ConnectionManager:1 Service ISO/IEC 29341-3-11
UPnP ContentDirectory:1 Service ISO/IEC 29341-3-12
UPnP RenderingControl:1 Service ISO/IEC 29341-3-13
UPnP MediaRenderer:2 Device ISO/IEC 29341-4-2
UPnP MediaServer:2 Device ISO/IEC 29341-4-3
UPnP AV Datastructure Template:1 ISO/IEC 29341-4-4
UPnP AVTransport:2 Service ISO/IEC 29341-4-10
UPnP ConnectionManager:2 Service ISO/IEC 29341-4-11
UPnP ContentDirectory:2 Service ISO/IEC 29341-4-12
UPnP RenderingControl:2 Service ISO/IEC 29341-4-13
UPnP ScheduledRecording:1 ISO/IEC 29341-4-14
UPnP DigitalSecurityCamera:1 Device ISO/IEC 29341-5-1
UPnP DigitalSecurityCameraMotionImage:1 Service ISO/IEC 29341-5-10
UPnP DigitalSecurityCameraSettings:1 Service ISO/IEC 29341-5-11
UPnP DigitalSecurityCameraStillImage:1 Service ISO/IEC 29341-5-12
UPnP HVAC_System:1 Device ISO/IEC 29341-6-1
UPnP HVAC_ZoneThermostat:1 Device ISO/IEC 29341-6-2
UPnP ControlValve:1 Service ISO/IEC 29341-6-10
UPnP HVAC_FanOperatingMode:1 Service ISO/IEC 29341-6-11
UPnP FanSpeed:1 Service ISO/IEC 29341-6-12
UPnP HouseStatus:1 Service ISO/IEC 29341-6-13
UPnP HVAC_SetpointSchedule:1 Service ISO/IEC 29341-6-14
UPnP TemperatureSensor:1 Service ISO/IEC 29341-6-15
UPnP TemperatureSetpoint:1 Service ISO/IEC 29341-6-16
UPnP HVAC_UserOperatingMode:1 Service ISO/IEC 29341-6-17
UPnP BinaryLight:1 Device ISO/IEC 29341-7-1
UPnP DimmableLight:1 Device ISO/IEC 29341-7-2
UPnP Dimming:1 Service ISO/IEC 29341-7-10
UPnP SwitchPower:1 Service ISO/IEC 29341-7-11
UPnP InternetGatewayDevice:1 Device ISO/IEC 29341-8-1
UPnP LANDevice:1 Device ISO/IEC 29341-8-2
UPnP WANDevice:1 Device ISO/IEC 29341-8-3
UPnP WANConnectionDevice:1 Device ISO/IEC 29341-8-4
UPnP WLANAccessPointDevice:1 Device ISO/IEC 29341-8-5
UPnP LANHostConfigManagement:1 Service ISO/IEC 29341-8-10
UPnP Layer3Forwarding:1 Service ISO/IEC 29341-8-11
UPnP LinkAuthentication:1 Service ISO/IEC 29341-8-12
UPnP RadiusClient:1 Service ISO/IEC 29341-8-13
UPnP WANCableLinkConfig:1 Service ISO/IEC 29341-8-14
UPnP WANCommonInterfaceConfig:1 Service ISO/IEC 29341-8-15
UPnP WANDSLLinkConfig:1 Service ISO/IEC 29341-8-16
UPnP WANEthernetLinkConfig:1 Service ISO/IEC 29341-8-17
UPnP WANIPConnection:1 Service ISO/IEC 29341-8-18
UPnP WANPOTSLinkConfig:1 Service ISO/IEC 29341-8-19
UPnP WANPPPConnection:1 Service ISO/IEC 29341-8-20
UPnP WLANConfiguration:1 Service ISO/IEC 29341-8-21
UPnP Printer:1 Device ISO/IEC 29341-9-1
UPnP Scanner:1.0 Device ISO/IEC 29341-9-2
UPnP ExternalActivity:1 Service ISO/IEC 29341-9-10
UPnP Feeder:1.0 Service ISO/IEC 29341-9-11
UPnP PrintBasic:1 Service ISO/IEC 29341-9-12
UPnP Scan:1 Service ISO/IEC 29341-9-13
UPnP QoS Architecture:1.0 ISO/IEC 29341-10-1
UPnP QosDevice:1 Service ISO/IEC 29341-10-10
UPnP QosManager:1 Service ISO/IEC 29341-10-11
UPnP QosPolicyHolder:1 Service ISO/IEC 29341-10-12
UPnP QoS Architecture:2 ISO/IEC 29341-11-1
UPnP QOS v2 Schema Files ISO/IEC 29341-11-2
UPnP QosDevice:2 Service ISO/IEC 29341-11-10
29341-8-12 © ISO/IEC:2008(E) – 7 –
UPnP Document Title ISO/IEC 29341 Part
UPnP QosManager:2 Service ISO/IEC 29341-11-11
UPnP QosPolicyHolder:2 Service ISO/IEC 29341-11-12
UPnP RemoteUIClientDevice:1 Device ISO/IEC 29341-12-1
UPnP RemoteUIServerDevice:1 Device ISO/IEC 29341-12-2
UPnP RemoteUIClient:1 Service ISO/IEC 29341-12-10
UPnP RemoteUIServer:1 Service ISO/IEC 29341-12-11
UPnP DeviceSecurity:1 Service ISO/IEC 29341-13-10
UPnP SecurityConsole:1 Service ISO/IEC 29341-13-11
– 8 – 29341-8-12 © ISO/IEC:2008(E)
1. Overview and Scope
This device template is compliant with the UPnP Device Architecture, Version 1.0.
This service-type enables a UPnP control point to configure and control the parameters pertaining to
authentication by an authentication server. The service specifies variables and actions that are used by control
points to add, update and delete records used for authentication. This would typically be used for maintaining
per-client authentication parameters on a device. This service would support a user/client list with the
credentials (password, public key) and the specific access rights on a per-user basis. The service is mainly
designed for authentication on a wireless access point (AP) that implements link layer security such as 802.1x. It
may be used for other purposes - e.g., to securely store client credentials such as certificates and asymmetric
keys for network-layer security protocols.
The working committee has however looked at this service only from the perspective of 802.1x usage and
therefore this document makes several references to the 802.1x protocol. This service may be co-located with
the access point device that requires the authentication service or located on a different device on the network
such as an Internet Gateway Device (IGD). The service was defined to associate WLAN clients and their
*
credentials to bootstrap a secure WLAN in a UPnP technology compliant WLANAccessPointDevice .
This service is defined as a standalone service and will remain at the component level. Any product that
implements a standard device specification will have the option to implement this standard service specification.
The product will be tested at certification testing time for this service in addition to being tested to the product’s
original device type (e.g., WLANAccessPointDevice, InternetGatewayDevice).
*
Refer to companion documents defined by the UPnP Internet Gateway working committee for more details on
specific devices and services referenced in this document.
29341-8-12 © ISO/IEC:2008(E) – 9 –
2. Service Modeling Definitions
2.1. ServiceType
The following service type identifies a service that is compliant with this template:
urn:schemas-upnp-org:service:LinkAuthentication:1
2.2. State Variables
Table 1: State Variables
Variable Name Req. Data Allowed Value Default Value Eng.
or Type Units
Opt.
NumberOfEntries
R ui2 >=0 0 N/A
Identifier
R String <= 64 char Empty string N/A
Secret R String Encoded in Empty string N/A
BASE64, <=
1024 char
SecretType
R String See Table 1.1, Not specified N/A
<= 32 char
AuthType R String See Table 1.2, Not specified N/A
<= 32 char
AuthState
R String See Table 1.3, “Unconfigured” N/A
<= 32 char
CredentialState
R String See Table 1.4, “Unconfigured” N/A
<= 32 char
Description
R String <= 256 char Empty string N/A
MACAddress
R String MAC address, Empty string N/A
“xx:xx:xx:xx:xx:x
x”, case-
independent, 17
char
CredentialDuration
R ui4 >= 0 0 Seconds
LinkedIdentifier R String <= 64 char Empty string N/A
LastChange
R String <= 1024 char Empty string N/A
LastError
R String <= 1024 char Empty string N/A
Non-standard state variables X TBD TBD TBD TBD
implemented by an UPnP device
vendor go here.
R = Required, O = Optional, X = Non-standard.
Values listed in this column are required. To specify standard optional values or to delegate assignment of
values to the vendor, you must reference a specific instance from the appropriate table below.
2.2.1. NumberOfEntries
This variable indicates the number of entries in the authentication database.
2.2.2. Identifier
This variable is similar to a username or userID field. This field is matched when a client supplies an
EAP-Identity string. This service expects Identifier to uniquely identify each record in the
– 10 – 29341-8-12 © ISO/IEC:2008(E)
authentication database, that is, there are no records with duplicate Identifier fields. Note, EAP uses
the term Identifier to refer to a single octet used to match EAP request and responses, in this
specification Identifier refers to the EAP Identity string. See RFC 2716 Section 3.1. The Identifier may
contain the characters < > & which will “break” the surrounding XML, therefore the Identifier string
must be ‘escaped’. Refer to DeviceSecurity section “XML Strings as UPnP Parameters”.
2.2.3. Secret
This variable contains the secret as per the type specified in SecretType. It is encoded as a
canonical BASE64 string (as used by the DeviceSecurity service).
2.2.4. SecretType
This variable specifies the type of secret contained in the Secret field. Possible string values are
specified in table 1.1.
Table 1.1: allowedValueList for SecretType
Value Req. or Opt. Description
TextPassword R This value indicates that Secret field contains a text
password
X509Certificate R This value indicates the Secret field contains an X.509
certificate
PublicKey R
This value indicates the Secret field contains a public key
PubKeyHash160 R
This value indicates the Secret field contains a 160-bit
hash of a public key
Vendor-defined R R
Vendor-defined O O
R = Required, O = Optional.
29341-8-12 © ISO/IEC:2008(E) – 11 –
2.2.5. AuthType
This variable specifies the type of authentication. Possible string values are specified in table 1.2
Table 1.2: allowedValueList for AuthType
Value Req. or Opt. Description
SharedSecret R This value indicates the 802.1x client is using an
authentication method that requires addition of a credential
such as shared secret that is missing, i.e., TextPassword.
When AuthState is Pending the user would be expected to
provide the shared secret to the AP via the control point
using the UpdateEntry action. This results in a change in
the Secret field value.
ValidateCredentials R This value indicates the 802.1x client is using an
authentication method that requires the verification of
existing credentials, i.e. as in an X509Certificate. When
AuthState is Pending this requires the user or control
point to validate the credential in the Secret field.
Vendor-defined R R
Vendor-defined O O
R = Required, O = Optional.
2.2.6. AuthState
This variable specifies the current state of the authentication process. Possible string values are
specified in table 1.3. Refer to the state diagram and theory of operation for details.
Table 1.3: allowedValueList for AuthState
Value Req. or Opt. Description
Unconfigured R A WLAN client corresponding to this Identifier has yet
to authenticate.
R
Failed A WLAN client corresponding to this Identifier failed
to successfully authenticate the contents of the secret field
- for example, with 802.1x authentication. This state informs
control points the secret that was entered or validated has
failed.
R
Succeeded A WLAN client corresponding to this Identifier
successfully authenticated using the contents of the secret
field, for example, with 802.1x authentication. This state
informs control points that the secret that was entered or
validated has succeeded.
Vendor-defined R R
Vendor-defined O O
R = Required, O = Optional.
– 12 – 29341-8-12 © ISO/IEC:2008(E)
2.2.7. CredentialState
This variable specifies the current state of the credential approval/validation process. Possible string
values are specified in table 1.4. Refer to the state diagram and theory of operation for details.
Table 1.4: allowedValueList for CredentialState
Value Req. or Opt. Description
Unconfigured R This value indicates that other variables in the particular
record are uninitialized or in an invalid state. Examples of
such variables include Secret and AuthType. This
record will not be used for authentication; it may be used for
other purposes.
R This value indicates the record referred to by the
Pending
Identifier does not have a validated Secret field.
(alert CP for action)
Control points are expected to prompt the end-user to enter
the SharedSecret or validate a credential. Upon end-user
acceptance the control point changes AuthState to either
Accepted or Denied
Accepted R This value indicates the database record referred to by the
Identifier field has had its Secret field
entered/validated by the end-user.
Denied R This value indicates that when a client attempts to
authenticate it is not allowed to proceed with link layer
authentication. This state is intended to restrict devices from
the network and restrict events from those devices.
Vendor-defined R R
Vendor-defined O O
R = Required, O = Optional.
The component performing authentication and authorization for network access is expected to refer to
the client database for credential information. If a given Identifier is not found in the database, a
new record is created, populated, and set to Pending. The user, via a control point, can update the
record to Accepted, or Denied. The control point may query the user for an amount of time to grant
the client temporary network access. The amount of time is specified in seconds and is stored in the
CredentialDuration variable.
2.2.8. Description
This variable stores a string used exclusively by control points to aid in identifying authentication
records. For example, a control point may prompt the user to supply a friendly name for the client
device. It is stored in the authentication records and may not be used by the AP device. The
Description may contain the characters < > & which will “break” the surrounding XML, therefore the
Description string must be ‘escaped’. Refer to DeviceSecurity section “XML Strings as UPnP
Parameters”.
2.2.9. MACAddress
This variable specifies the MAC address of the client. It is not intended to be used to authenticate the
client, as MAC Addresses are mutable. This field can be used by control points to display the device’s
MAC address during the initial authentication process when the client device is first added to the
network and authentication database. This field is dynamically updated by the AP when a client
device is authenticating. This field is also updated to reflect the last MAC address that successfully or
unsuccessfully authenticated. See the theory of operation section for more details.
29341-8-12 © ISO/IEC:2008(E) – 13 –
2.2.10. CredentialDuration
This variable determines the time (in number of seconds) a client record with a CredentialState of
Accepted is allowed to authenticate. A value of 0 means the client record is permanent, that is,
there is no expiration period. Non-zero values specify temporary access. When a non-zero
CredentialDuration transitions to zero (the number of seconds has expired) the record must be
deleted and LastChange event triggered. Note that permanent client records with
CredentialDuration of zero persist across device resets or reboots. It is up to vendors to
implement persistence as appropriate for their device, for example store in non-volatile storage such
as flash or disk. Non-zero CredentialDuration values do not persist across device resets or
reboots, that is, the temporary client is expected to be re-authenticated. The remaining number of
seconds can be retrieved via the GetGenericEntry and GetSpecificEntry actions. Automatic
second decrements to the CredentialDuration do NOT generate a LastChange event.
2.2.11. LinkedIdentifier
Some EAP authentication methods allow two EAP negotiations. For example, PEAP optionally
negotiates two phases, a Part 1 and a Part 2 phase to complete authentication. Each phase may
negotiate using unique Identifiers, AuthTypes, and credentials. To allow the EAP server to indicate
related records to the control point this field contains the Identifier for the initial EAP negation. For
example, if PEAP Part1 used an Identifier of User1, AuthType of ValidateCredentials and
SecretType of PubKeyHash160 and PEAP Part 2 used an Identifier of User2, AuthType of SharedSecret,
then two records would exist with the LinkedIdentifier field of the User2 record containing User1.
Therefore, if the Part 2 authentication phase fails, the EAP server should delete both records User 1
and User 2. Additionally, if the user refuses to authenticate Part 2, the control point should set both
records CredentialState to Denied or optionally delete both records User1 and User2.
The LinkedIdentifier may contain the characters < > & which will “break” the surrounding XML,
therefore the LinkedIdentifier string must be ‘escaped’. Refer to DeviceSecurity section “XML Strings
as UPnP Parameters”.
2.2.12.LastChange
This variable is used for eventing purposes to allow control points to receive meaningful event
notifications when a record is added, deleted or changed.
LastChange is an evented string variable whose value is an escaped XML string (as used by the
DeviceSecurity service) with the following format (white space is shown for readability but is not
necessary or desirable):
value…
where action is one of {Add, Delete, Update}, fieldname is one of {Identifier, Secret,
SecretType, AuthType, AuthState, CredentialState, LinkedIdentifier}, and
value is specified per the State Variables table. The Identifier must always be present. To
prevent sending the Secret, which can be a large string, over the network an empty string should be
sent in its place. This is intended to reduce the traffic when the LastChange event triggers, and also
of course avoids sending sensitive information via event messages. Multiple changes to a single
record can be concatenated to trigger only a single event to subscribed control points. When a record
is updated, it is recommended that only those fields whose values have changed be sent, but control
points should not assume this.
– 14 – 29341-8-12 © ISO/IEC:2008(E)
For example, creation of a new record might result in the following value for LastChange.
Foo
TextPassword
SharedSecret
Unconfigured
Unconfigured
A subsequent change to CredentialState might result in the following value.
Foo
Pending
2.2.13.LastError
This variable is used for eventing purposes to allow control points to discover when an asynchronous
error (i.e. an error that is not the direct result of a UPnP action) has occurred in the authentication
server backend handler. For example, the EAP server might have tried to add a new record to the
authentication database but failed due to lack of resources.
LastError is an evented string variable whose value is an escaped XML string (as used by the
DeviceSecurity service) with the following format (white space is shown for readability but is not
necessary or desirable):
integer-code
error-description
Where appropriate, standard UPnP error codes and descriptions can be used. New codes should be
allocated according to the conventions described in Section 2.4.9.
2.3. Eventing and Moderation
Table 2: Event Moderation
Variable Name Evented Moderated Max Event Logical Min Delta
1 2
Event Rate Combination per Event
LastChange
Yes No N/A N/A N/A
LastError
Yes No N/A N/A N/A
Non-standard state variables TBD TBD TBD TBD
implemented by an UPnP device
vendor go here.
Determined by N, where Rate = (Event)/(N secs). TBD
(N) * (allowedValueRange Step).
2.3.1. Event Model
Control points can use LastChange events to notify end-users of clients attempting to access the network for
the first time, and can use LastError events to notify them of asynchronous errors. Additionally, control
points can use events for duplication or to backup the authentication database to a control point such as a PC or
into another wireless access point. Refer to the Theory of operation for further details.
29341-8-12 © ISO/IEC:2008(E) – 15 –
Note: events alone cannot be used to duplicate a database, because they will not contain the value of the
Secret field. A control point could, on noting that Secret had changed, use GetSpecificEntry to
retrieve its value.
– 16 – 29341-8-12 © ISO/IEC:2008(E)
2.4. Actions
Table 3 lists the required and optional actions for the UPnP AP device. This is followed by detailed information
about these actions, including short descriptions of the actions, the effects of the actions on state variables, and
error codes defined by the actions.
Securing UPnP actions in this service is optional but strongly recommended, using UPnP security protocols as
defined by UPnP Security working group. If the AP implements security for UPnP actions, Table 3 indicates
which actions MUST be secure. The others may be implemented as secure or open. Secure actions MUST be
protected for both confidentiality and integrity.
Access permissions will be inherited from the containing device (e.g., WLANAccessPointDevice).
Table 3: Actions
Name Secure or Req. or
Open* Opt.
GetGenericEntry
S R
GetSpecificEntry
S R
AddEntry S R
UpdateEntry S R
DeleteEntry
S R
GetNumberOfEntries
S R
FactoryDefaultReset S R
ResetAuthentication S R
Non-standard actions implemented by an UPnP device vendor go here. X X
R = Required, O = Optional, X = Non-standard.
* This column is relevant if DeviceSecurity service is present in the container device
29341-8-12 © ISO/IEC:2008(E) – 17 –
2.4.1. GetGenericEntry
This action retrieves authentication records one entry at a time. Control points can call this action with
an incrementing array index until no more entries are found in the authentication record list. If
LastChange is updated during a call, the process may have to start over. Entries in the array are
contiguous. As entries are deleted, the array is compacted, and the evented variable LastChange is
triggered. Authentication records are logically stored as an array and retrieved using an array index
ranging from 0 to NumberOfEntries-1.
2.4.1.1. Arguments
Table 4: Arguments for GetGenericEntry
Argument Direction relatedStateVariable
NewIndex NumberOfEntries
IN
NewIdentifier OUT Identifier
NewSecret OUT Secret
NewSecretType OUT SecretType
NewAuthType AuthType
OUT
NewAuthState AuthState
OUT
NewCredentialState CredentialState
OUT
NewDescription OUT Description
NewMACAddress OUT MACAddress
NewCredentialDuration OUT CredentialDuration
NewLinkedIdentifier OUT LinkedIdentifier
2.4.1.2. Dependency on State (if any)
2.4.1.3. Effect on State (if any)
None.
2.4.1.4. Errors
errorCode errorDescription Description
402 Invalid Args See UPnP Device Architecture section on Control.
713 SpecifiedArrayIndexInvalid The specified array index is out of bounds.
– 18 – 29341-8-12 © ISO/IEC:2008(E)
2.4.2. GetSpecificEntry
This action retrieves one authentication record entry specified by the input parameter
NewIdentifierKey. Authentication records are logically stored as an array in the authentication
record list and can be retrieved using their Identifier as a unique value.
2.4.2.1. Arguments
Table 5: Arguments for GetSpecificEntry
Argument Direction relatedStateVariable
NewIdentifierKey Identifier
IN
NewIdentifier Identifier
OUT
NewSecret Secret
OUT
NewSecretType OUT SecretType
NewAuthType OUT AuthType
NewAuthState OUT AuthState
NewCredentialState OUT CredentialState
NewDescription Description
OUT
NewMACAddress MACAddress
OUT
NewCredentialDuration
OUT CredentialDuration
NewLinkedIdentifier OUT LinkedIdentifier
2.4.2.2. Dependency on State (if any)
2.4.2.3. Effect on State (if any)
None.
2.4.2.4. Errors
errorCode errorDescription Description
402 Invalid Args See UPnP Device Architecture section on Control.
605 String Argument Too Long A string argument is too long for the device to handle
properly.
702 IdentifierKeyNotPresent The record corresponding to input Identifier key is not
found in the authentication record list.
29341-8-12 © ISO/IEC:2008(E) – 19 –
2.4.3. AddEntry
This action creates a new authentication record.
2.4.3.1. Arguments
Table 6: Arguments for AddEntry
Argument Direction relatedStateVariable
NewIdentifier Identifier
IN
NewSecret Secret
IN
NewSecretType IN SecretType
NewAuthType IN AuthType
NewAuthState IN AuthState
NewCredentialState CredentialState
IN
NewDescription Description
IN
NewMACAddress MACAddress
IN
NewCredentialDuration IN CredentialDuration
NewLinkedIdentifier IN LinkedIdentifier
NewNumberOfEntries OUT NumberOfEntries
2.4.3.2. Dependency on State (if any)
2.4.3.3. Effect on State (if any)
When adding a new record the LastChange variable is evented including the new fields and values.
2.4.3.4. Errors
errorCode errorDescription Description
402 Invalid Args See UPnP Device Architecture section on Control.
501 Action Failed See UPnP Device Architecture section on Control.
605 String Argument Too Long A string argument is too long for the device to handle
properly.
701 EntryAlreadyPresent If an existing record with Identifier already exists in the
database return this error.
– 20 – 29341-8-12 © ISO/IEC:2008(E)
2.4.4. UpdateEntry
This action modifies an existing authentication record.
2.4.4.1. Arguments
Table 7: Arguments for UpdateEntry
Argument Direction relatedStateVariable
NewIdentifier Identifier
IN
NewSecret Secret
IN
NewSecretType IN SecretType
NewAuthType IN AuthType
NewAuthState IN AuthState
NewCredentialState CredentialState
IN
NewDescription Description
IN
NewMACAddress MACAddress
IN
NewCredentialDuration IN CredentialDuration
NewLinkedIdentifier IN LinkedIdentifier
NewNumberOfEntries OUT NumberOfEntries
2.4.4.2. Dependency on State (if any)
2.4.4.3. Effect on State (if any)
The modified fields and values are evented via the LastChange event.
2.4.4.4. Errors
errorCode errorDescription Description
402 Invalid Args See UPnP Device Architecture section on Control.
501 Action Failed See UPnP Device Architecture section on Control.
605 String Argument A string argument is too long for the device to handle properly.
Too Long
714 EntryNotPresent If existing record with Identifier does not exist return this error.
29341-8-12 © ISO/IEC:2008(E) – 21 –
2.4.5. DeleteEntry
This action deletes an authentication record specified by InIdentifier.
2.4.5.1. Arguments
Table 8: Arguments for DeleteEntry
Argument Direction relatedStateVariable
NewIdentifier Identifier
IN
NewNumberOfEntries NumberOfEntries
OUT
2.4.5.2. Dependency on State (if any)
2.4.5.3. Effect on State (if any)
As each entry is deleted, the array is compacted, and the evented variable LastChange is triggered.
LastChange only includes the ActionField set to Delete followed by the Identifier field.
2.4.5.4. Errors
errorCode errorDescription Description
402 Invalid Args See UPnP Device
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.
Loading comments...