[MS-AVEDGEA]: Audio Video Edge Authentication Protocol Specification
Intellectual Property Rights Notice for Protocol Documentation Copyrights. This protocol documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the protocols, and may distribute portions of it in your implementations of the protocols or your documentation as necessary to properly document the implementation. This permission also applies to any documents that are referenced in the protocol documentation. No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation. Patents. Microsoft has patents that may cover your implementations of the protocols. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, the protocols may be covered by Microsoft's Open Specification Promise (available here: http://www.microsoft.com/interop/osp). If you would prefer a written license, or if the protocols are not covered by the OSP, patent licenses are available by contacting protocol@microsoft.com. Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise. Tools. This protocol documentation is intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it. A protocol specification does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them.
Revision Summary Author Microsoft Corporation Microsoft Corporation Microsoft Corporation Microsoft Corporation Date April 4, 2008 April 25, 2008 June 27, 2008 August 15, 2008 Version 0.1 0.2 1.0 1.01 Comments Initial Availability Revised and edited the technical content Revised and edited the technical content Revised and edited the technical content
1 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Table of Contents
1 Introduction........................................................................................................................... 4 1.1 Glossary ............................................................................................................................. 4 1.2 References ......................................................................................................................... 4 1.2.1 Normative References .............................................................................................. 4 1.2.2 Informative References ............................................................................................ 5 1.3 Protocol Overview (Synopsis).......................................................................................... 5 1.4 Relationship to Other Protocols........................................................................................ 7 1.5 Prerequisites/Preconditions ............................................................................................... 7 1.6 Applicability Statement..................................................................................................... 8 1.7 Versioning and Capability Negotiation ............................................................................ 8 1.8 Vendor-Extensible Fields ................................................................................................. 8 1.9 Standards Assignments ..................................................................................................... 8 Messages ................................................................................................................................ 8 2.1 Transport ............................................................................................................................ 8 2.2 Message Syntax ................................................................................................................. 8 2.2.1 Request by the Client................................................................................................ 9 2.2.1.1 requestType Element ................................................................................... 9 2.2.1.1.1 request Element Definition ........................................................................ 9 2.2.1.1.2 requestType Type Definition ..................................................................... 9 2.2.1.1.2.1 Type Attributes.................................................................................... 9 2.2.1.1.3 Child Elements ......................................................................................... 10 2.2.1.1.3.1 credentialsRequest Element Definition............................................ 10 2.2.1.1.3.2 credentialsRequest Type Definition ................................................. 10 2.2.1.1.3.3 credentialsRequest Attributes ........................................................... 10 2.2.2 Response by the Server .......................................................................................... 11 2.2.2.1 responseType Element .............................................................................. 11 2.2.2.1.1 responseType Element Definition ........................................................... 11 2.2.2.1.2 responseType Type Definition................................................................. 11 2.2.2.1.3 responseType Attributes.............................................................................. 11 2.2.2.1.4 Child Elements ......................................................................................... 12 2.2.2.1.4.1 credentialsResponse Element Definition ......................................... 12 2.2.2.1.4.2 credentialsResponseType Type Definition ...................................... 12 2.2.2.1.4.3 credentialsResponseType Attributes ................................................ 13 2.2.2.1.4.4 credentialsResponseType ChildElements........................................ 13 Protocol Details ................................................................................................................... 14 3.1 Server Details .................................................................................................................. 14 3.1.1 Abstract Data Model .............................................................................................. 14 3.1.2 Timers ..................................................................................................................... 14 3.1.3 Initialization ............................................................................................................ 14 3.1.4 Higher-Layer Triggered Events ............................................................................. 14 3.1.5 Message Processing Events and Sequencing Rules.............................................. 14 3.1.5.1 General Rules............................................................................................. 15
2 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
2
3
3.1.5.2 Checking the Attributes of the Request .................................................... 15 3.1.5.3 Generating the credentialResponse........................................................... 15 3.1.5.4 Populating Attributes of the Response ..................................................... 16 3.1.5.5 Error Codes ................................................................................................ 16 3.1.5.6 Token Generation ...................................................................................... 17 3.1.5.6.1 Username .................................................................................................. 17 3.1.5.6.1.1 Token Blob Structure ........................................................................ 17 3.1.5.6.1.2 username Structure............................................................................ 18 3.1.5.6.2 Password ................................................................................................... 19 3.1.6 Timer Events........................................................................................................... 19 3.1.7 Other Local Events ................................................................................................. 19 4 Protocol Examples .............................................................................................................. 19 4.1 Request from Client to Server ........................................................................................ 19 4.2 Server Response to Client ............................................................................................... 20 Security ................................................................................................................................ 21 5.1 Security Considerations for Implementers ..................................................................... 21 5.1.1 Keyed Hash Function ............................................................................................. 21 5.1.2 Underlying Transport ............................................................................................. 22 5.1.3 Authentication......................................................................................................... 22 5.2 Index of Security Parameters .......................................................................................... 22 Appendix A: Product Behavior ......................................................................................... 22 Appendix B: [MS-AVEDGEA] Schema........................................................................... 22
5
6 7
Index ............................................................................................................................................. 27
3 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
1 Introduction
This document specifies the Audio Video Edge Authentication Protocol [MS-AVEDGEA]. This is a Microsoft® proprietary protocol used by clients to get security tokens needed to authenticate themselves with a server that implements the Traversal Using Relay NAT (TURN) Extensions [MS-TURN] protocol. Microsoft Office Communicator client uses this protocol to retrieve tokens from Microsoft Office Communications Server which implements [MS-AVEDGEA] protocol. It uses these tokens to obtain access to the Audio/Video Edge Server (A/V Edge Server), that implements the [MS-TURN] protocol for use with the Interactive Connectivity Establishment (ICE) Extensions [MS-ICE] protocol.
1.1 Glossary
The following terms are defined in [MS-GLOS]: client fully qualified domain name (FQDN) server Transport Layer Security (TLS) The following terms are defined in [MS-OCSGLOS]: Audio/Video Edge Server (A/V Edge Server) Content-Type HMAC-SHA1 Network Address Translation (NAT) SERVICE Session Initiation Protocol (SIP) The following terms are specific to this document: shared-secret: A shared secret is a piece of data only known to the parties involved in a secure communication. MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2 References
1.2.1 Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact dochelp@microsoft.com. We will assist you in finding the relevant information. Please check
4 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
the archive site, http://msdn.microsoft.com/en-us/library/cc136647.aspx, as an additional source. [IETFDRAFT-SIPSOAP-00] Deason, N., "SIP and SOAP", draft-deason-sip-soap-00, June 2000, http://tools.ietf.org/draft/draft-deason-sip-soap/draft-deason-sip-soap-00.txt. [MS-GLOS] Microsoft Corporation, "Windows Protocols Master Glossary", March 2008. [MS-OCSGLOS] Microsoft Corporation, "Office Communications Server Master Glossary", June 2008. [MS-SIPRE] Microsoft Corporation, "Session Initiation Protocol (SIP) Routing Extensions", June 2008. [MS-TURN] Microsoft Corporation, "Traversal Using Relay NAT (TURN) Extensions", June 2008. [RFC2119] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt. [RFC3261] Rosenberg, J., et al., "SIP: Session Initiation Protocol", RFC 3261, June 2002, http://www.ietf.org/rfc/rfc3261.txt. [XML10] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0 (Third Edition)", February 2004, http://www.w3.org/TR/REC-xml. [XMLSCHEMA1/2] Thompson, H.S., Ed., Beech, D., Ed., Maloney, M., Ed., and Mendelsohn, N., Ed., "XML Schema Part 1: Structures Second Edition", W3C Recommendation, October 2004, http://www.w3.org/TR/xmlschema-1/. [XMLSCHEMA2/2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes Second Edition", W3C Recommendation, October 2004, http://www.w3.org/TR/xmlschema2.
1.2.2 Informative References
[MS-ICE] Microsoft Corporation, "Interactive Connectivity Establishment (ICE) Extensions", June 2008. [RFC2104] Krawczyk, H., Bellare, M., and Canetti, R., "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997, http://www.ietf.org/rfc/rfc2104.txt.
1.3 Protocol Overview (Synopsis)
[MS-TURN] is used for Network Address Translation (NAT) and firewall traversal. To help clients traverse NATs and firewalls, servers implementing [MS-TURN] may need to be
5 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
deployed at particular places in the network topology. With the security tokens supplied by [MS-AVEDGEA], client can authenticate with these [MS-TURN] servers.
1 . AV E 2. AV DGEA req EDGE u A resp est o n se
[MS-AVEDGEA] server
en to Allo 3. Use tok
cate resou
rces
Client
[MS-TURN] server
Figure 1: Protocol overview The [MS-AVEDGEA] server is associated with a server implementing [MS-TURN] and SHOULD be aware of the configuration details of the associated [MS-TURN] server. When the client needs tokens, it sends a Session Initiation Protocol (SIP) SERVICE request as specified by [IETFDRAFT-SIPSOAP-00] to the [MS-AVEDGEA] server with the body of the message encoded in the [XML10] format. The server responds with a SIP SERVICE response message and a response code which indicates whether the response was a success or failure. If it was a success, then the response contains the security tokens along with location information of the associated [MS-TURN] server. If it was a failure, the response code indicates the type of failure. If there was an error with the XML body of the request, then the response will also contain an XML body that describes the exact cause of the problem. The [MS-AVEDGEA] server shares two shared-secret keys with the associated [MSTURN] server and it uses these keys to generate tokens. A security token consists of a username and password. The token is valid only for a certain amount of time. If the client requires the token to be valid for a shorter time interval, it can specify the length of the interval in the XML request. The server will honor this value if it is less than the default duration it uses. Since the expiry time in the token is not easily decipherable, the response also includes a duration element that specifies for how long the token is valid. The token also includes a hash of the identity specified by the client, which the [MS-TURN] server may use to implement resource management. The details about the token generation process are provided in section 3.1.5.6.
6 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
1.4 Relationship to Other Protocols
[MS-AVEDGEA] uses [MS-SIPRE] for receiving requests and sending out responses. [MS-AVEDGEA] uses the SIP SERVICE [IETFDRAFT-SIPSOAP-00] method, which is an extension to the standard SIP, to receive and send responses. The security tokens received from the [MS-AVEDGEA] server are used to obtain access to the [MS-TURN] server for use with the [MS-ICE] protocol.
1.5 Prerequisites/Preconditions
[MS-AVEDGEA] assumes that the [MS-TURN] server associated with the [MS-AVEDGEA] server has two network interfaces, one facing the internet and the other facing the intranet as shown in Figure 2.
Network interface 1
Network interface 2
Public Internet
[MS-TURN] server
Intranet
Figure 2: [MS-TURN] server with two interfaces The server implementing [MS-AVEDGEA] is assumed to be configured with the following information. A certificate for establishing Transport Layer Security (TLS) connections. The certificate MUST have a private key. Two shared-secret keys, known both to the [MS-AVEDGEA] server and the associated [MS-TURN] server.
7 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
User Datagram Protocol (UDP) and Transmission Control Protocol (TCP) ports, on which the associated [MS-TURN] server listens for MS-TURN protocol requests. The default for UDP is 3478. The default for TCP is 443. The IP address and FQDN of each network interface of the associated [MS-TURN] server.
1.6 Applicability Statement
[MS-AVEDGEA] is used to provide a client with security tokens for accessing the [MSTURN] server.
1.7 Versioning and Capability Negotiation
[MS-AVEDGEA] negotiates versions in the following manner: 1. The client specifies the version in the XML body of the request. 2. If the server does not support the version requested by the client, then the request is rejected with a "Version Mismatch" error. For more information, see section 3.1.5. This version of [MS-AVEDGEA] MUST set the version field to 1.0.
1.8 Vendor-Extensible Fields
None.
1.9 Standards Assignments
None.
2 Messages
2.1 Transport
[MS-AVEDGEA] messages MUST be transported using SIP SERVICE messages through a connection secured with TLS.
2.2 Message Syntax
The request and response messages of [MS-AVEDGEA] MUST be SIP SERVICE messages as specified in [IETFDRAFT-SIPSOAP-00]. [MS-AVEDGEA] protocol requests MUST include a Content-Type header, "application/msrtc-media-relay-auth+xml". The schema definition (as specified in [XMLSCHEMA1/2], [XMLSCHEMA2/2]) for the request and response messages is documented in Appendix B.
8 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
2.2.1 Request by the Client
The XML request sent by the client MUST include exactly one request element. 2.2.1.1 requestType Element
2.2.1.1.1
request Element Definition
2.2.1.1.2
requestType Type Definition
2.2.1.1.2.1
Type Attributes
Attribute Description
requestID
An ID that is used to identify the request. This MAY be used by the client to associate the response with the request, in case the client sent multiple simultaneous requests to the server with a unique requestID. This value MUST be 1.0. This indicates the version the client understands. If the server does not support this version, then it MUST return a "Version Mismatch" error message. A restricted length URI type that identifies the entity to which the request needs to be sent to. It MUST be a SIP URI. A restricted length URI type that identifies the entity that originated the request. It MUST be a SIP URI.
9 of 27
version to from
[MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Attribute
Description
route
An optional attribute with a default value of "loadbalanced". If the value of the attribute is "directIP" then the server MUST return the IP address of the [MS-TURN] server. If the attribute is not present or if the value is loadbalanced, then the server SHOULD return the fully qualified domain name (FQDN) that resolves to the [MS-TURN] server's IP address. It MAY return an IP address of the [MS-TURN] server instead.
Child Elements [MS-AVEDGEA] implements the following requestType child elements.
2.2.1.1.3 2.2.1.1.3.1 credentialsRequest Element Definition
2.2.1.1.3.2
credentialsRequest Type Definition
Element
Description
credentialsRequest
One or more subelements of type credentialsRequestType MUST be present within the requestType. The maxOccurs attribute specifies the maximum number of subelements that MUST be present in the request. The schema allows 100 subelements in this version of the server. If the XML request by the client adheres to the schema, except that the number of elements in the request exceeds maxOccurs, then a "Request Too Large" error MUST be returned by the server.
2.2.1.1.3.3
credentialsRequest Attributes
Attribute Description
10 of 27
[MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Attribute
Description
A restricted length string type that identifies the entity to which the token SHOULD be issued to. This is a required field. This field identifies the interface for which the tokens and FQDN/IP address and port information of the associated [MSlocation TURN] server MUST be returned. If the attribute is not present, details related to both interfaces MUST be returned. The number of minutes for which the token needs to be valid. The duration server MUST use this value if it is less than the default value. If it is not included, then the server MUST use the default value. A restricted length string type that identifies the credentialsRequestID credentialsRequest element within a requestType. identity
2.2.2 Response by the Server
The XML request sent by the server MUST include exactly one responseType element. 2.2.2.1 responseType Element
2.2.2.1.1
responseType Element Definition
2.2.2.1.2
responseType Type Definition
2.2.2.1.3 responseType Attributes
Attribute Description
11 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Attribute
Description
requestID
version
to from
This MUST be the same value as the requestID attribute in the request. This attribute MAY not be present if the request was not understood by the server. The value MUST be 1.0. If the server supported multiple versions and it understood the client's request, then it MUST be the version provided by the client. If the request was not understood, then the version MUST be equal to the latest version supported by the server. This MUST be the same as the to attribute in the request. This attribute MAY not be present if the request was not understood by the server. This MUST be the same as the from attribute in the request. This attribute MAY not be present if the request was not understood by the server. Specifies the reason for the error. It MUST be one of the values specified below. A detailed description of when each error message is thrown is provided in section 3.1.5.
reasonPhrase
2.2.2.1.4
Child Elements
credentialsResponse Element Definition
2.2.2.1.4.1
2.2.2.1.4.2
credentialsResponseType Type Definition
12 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Element Description
credentialsResponse
For each credentialsRequest in the request from the client, if the request succeeded, a credentialsResponse element MUST be included with the [MS-TURN] server information and the token for the identity in the credentialsRequest. If the processing of the request does not succeed, then there MUST be no credentialsResponse in the response sent by the server.
2.2.2.1.4.3
credentialsResponseType Attributes
Attribute Description
credentialsRequestID
2.2.2.1.4.4
This MUST be the same as the credentialsRequestID attribute in the request.
credentialsResponseType ChildElements
Description
Element
credentials
It MUST contain the following subelements: a username and a password, which form the security token needed by the client to contact the [MS-TURN] server. duration specifies how long the token is valid. It MAY contain: An optional element titled realm specifies which network segment the element belongs to.
13 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Element
Description
mediaRelayList
It MUST contain the following subelements: location indicates internet or intranet If the route attribute is set to 'loadbalanced' in the request element, then the subelement hostName MUST be present and SHOULD contain the FQDN that resolves to the [MS-TURN] server IP address. Instead, it MAY contain the IP address of the [MS-TURN] server. Otherwise if the route attribute is set to directIP in the request element, the subelement directIPAddress MUST be present and MUST contain the IP address of the [MS-TURN] server. tcpPort specifies the port the [MS-TURN] server is using to listen for TCP. udpPort specifies the port the [MS-TURN] server is using to listen for UDP.
3 Protocol Details
3.1 Server Details
3.1.1 Abstract Data Model
None.
3.1.2 Timers
None.
3.1.3 Initialization
None.
3.1.4 Higher-Layer Triggered Events
When a SIP SERVICE request is received by the server, the request MUST be processed based on the rules given in section 3.1.5 and a SIP SERVICE response message MUST be sent back to the user. The message contains the token information if the processing of the request succeeded, or a detailed error description if the processing failed.
3.1.5 Message Processing Events and Sequencing Rules
The SIP SERVICE Request described in section 2.2.1 MUST be the only message type that is accepted. The server MUST always respond with a SIP SERVICE response message as described in section 2.2.2. The error codes indicate the type of the error in the request.
14 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
3.1.5.1 General Rules When a request is received from the client, it is processed based on the following rules: 1. If the request message type is not SIP SERVICE, then the request MUST be rejected and an UnsupportedMessageType error response MUST be sent. 2. If the contenttype of the request is not equal to 'application/msrtc-media-relayauth+xml', then an UnsupportedContentType error response MUST be sent. The SIP header of the response MUST include an Accept header with the value 'application/msrtc-media-relay-auth+xml'. 3. For the previous two rules, the server does not send a XML response in its body. The error codes described in this section indicate the nature of the problem. In the checks that follow, if an error condition occurs, an XML body adhering to conditions described in section 2.2.2 MUST be sent. The reasonPhrase of the error message MUST be as described in the following sections. 4. If the request does not adhere to schema rules, then the request MUST be rejected with a reasonPhrase set to RequestMalformed. If the request adheres to schema rules, except that the number of credentialsRequest in the XML request is greater than the maxOccurs attribute in the schema, then the reasonPhrase in the error response MUST be RequestTooLarge. 5. The server MAY implement policies that restrict the request that can be sent by the client. If these policies are violated, the server MAY send an error response with a Forbidden reasonPhrase. 3.1.5.2 Checking the Attributes of the Request If the version in the XML request is not 1.0, then the reasonPhrase in the error response MUST be VersionMismatch. The from and to attributes MUST be SIP URIs. If they are SIP URIs, then the values of these attributes are copied to the response. Otherwise, an error message with the reasonPhrase set as RequestMalformed MUST be sent. 3.1.5.3 Generating the credentialResponse For each credentialRequest in the XML request: 1. If the duration attribute is present in the request, the lifetime of the token MUST be calculated as the minimum of the duration specified by the client and the preconfigured default lifetime value. 2. The tokens are generated using the lifetime calculated as stated previously and the identity specified by the client in the XML request. A detailed description of token
15 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
generation is provided in section 3.1.5.6. The username and password generated MUST be base64 encoded and included in the XML response. 3. A credentialResponse MUST be created with the same credentialsRequestID as in the credentialsRequest element in the client's request. The token information MUST be in the credentials element and the information regarding the [MS-TURN] server MUST be in the mediaRelayList Element. If the location element was specified by the client, then the [MS-TURN] server information related to that location only MUST be included in the mediarelayList element. Otherwise, both the intranet and internet information (appearing in Figure 2 earlier in this document) of the [MS-TURN] server MUST be included in the mediaRelayList element. 3.1.5.4 Populating Attributes of the Response If the request was processed successfully without an error, then the reasonPhrase MUST be set to Ok, and the following apply: The version attribute in the response MUST be set to 1.0. If the reasonPhrase is "RequestMalformed", then the from, to, and requestID attributes MAY not be included in the response. Otherwise from, to, and requestID attributes MUST be included and MUST be equal to the appropriate values in the XML request. If an unexpected server error occurs during processing of the request, then the reasonPhrase MUST be "InternalServerError." The SIP error codes that MUST be sent for the different response messages are listed in section 3.1.5.5. 3.1.5.5 Error Codes The following table shows SIP error codes corresponding to the different reasonPhrases in the SIP responses. Some of these reasonPhrases are not currently used by the server. The unused values are indicated in the table with a 'No' value in the Used now column. reasonPhrase in the response Ok RequestMalformed Forbidden TimeOut RequestTooLarge ServerBusy InternalServerError OtherFailure SIP error codes 200 400 403 408 413 486 500 500 Used now Yes Yes Yes No Yes No Yes No
16 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
reasonPhrase in the response NotSupported VersionMismatch
SIP error codes 501 501
Used now No Yes
The following two error responses are used when the XML body of the response is not sent. Response UnsupportedMessageType UnsupportedContentType SIP error codes 501 415 Used now Yes Yes
3.1.5.6 Token Generation [MS-AVEDGEA] server and the associated [MS-TURN] server share two secret keys. These keys are used to create security tokens for the clients. These keys MUST consist of randomly generated data with a minimum length of 20 bytes. The first key, Key1, is used to generate a hash that makes up part of the username. The second key, Key2, is used to generate the password. The username and password are defined later in this document.
3.1.5.6.1
Username
The username is constructed by hashing a blob of information, called the Token Blob, using HMAC-SHA1 [RFC2104] with the shared secret Key1. The 20-byte hash resulting from the HMAC-SHA1 function is appended to the end of the Token Blob structure. username is Token Blob appended with the hash of Token Blob. username =
and HashOfTokenBlob = HMAC-SHA1 (Key1, Token Blob). The Token Blob and username structures are defined later in this document.
3.1.5.6.1.1
Token Blob Structure
17 of 27
[MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 Major Version = 0x01 Minor Version = 0x00 Expiry Time Low Expiry Time High Size = 0x0020
Client ID (20 bytes)
Major Version (1 byte): This field identifies the major version of the [MS-AVEDGEA] server. It MUST be set to 0x01. Minor Version (1 byte): This field identifies the minor version of the [MS-AVEDGEA] server. It MUST be set to 0x00. Size (16 bits): This field identifies the size of the Token Blob. It MUST be set to 0x0020. Expiry Time Low (32 bits): This field contains the low 32 bits of the expiry time. The expiry time is the time the token expires expressed in FileTimeUTC. FileTimeUTC represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Expiry Time High (32 bits): This field contains the high 32 bits of the expiry time. Client ID (20 bytes): This field is used to identify the client for which the token is being created. We recommend that it be related to the identity element in the [MS-AVEDGEA] protocol request.
3.1.5.6.1.2
username Structure
18 of 27
[MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
Token Blob (32 bytes)
Token Blob Hash (20 bytes)
Token Blob Hash: The 20-byte hash resulting from HMAC-SHA1(Key1, Token Blob).
3.1.5.6.2
Password
The Password is constructed by hashing the username using HMAC-SHA1 as specified in [RFC2104] with the shared secret Key2. The 20-byte value resulting from the HMAC-SHA1 function is used as the password. password =
3.1.6 Timer Events
None.
3.1.7 Other Local Events
None.
4 Protocol Examples
The following examples illustrate the protocol request-response sequence.
4.1
Request from Client to Server
SERVICE sip: relay.contoso.com@contoso.com;gruu;opaque=srvr:MRAS:OKPDbAVxIEKtPh2g624 vPAAA SIP/2.0 Via: SIP/2.0/TLS 10.56.65.225:7012 Max-Forwards: 70 From: ;tag=09f804a3b1;epid=4906ed5712
19 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
To: Call-ID: 7b25d8f0304c4655814760e624d7c3aa CSeq: 1 SERVICE Contact: User-Agent: UCCP/2.0.6545.0 OC/2.0.6545.0 (Microsoft Office Communicator) Proxy-Authorization: NTLM qop="auth", realm="SIP Communications Service", opaque="9574F9DA", crand="5999c389", cnum="580", targetname="server1.contoso.com", response="0100000064386630f99f6cb864399660" Content-Type: application/msrtc-media-relay-auth+xml Content-Length: 471 sip:client@contoso.com intranet 480
4.2
Server Response to Client
SIP/2.0 200 OK Authentication-Info: NTLM rspauth="0100000000000000C614C5BD64399660", srand="B8926199", snum="862", opaque="9574F9DA", qop="auth", targetname="server1.contoso.com", realm="SIP Communications Service" Via: SIP/2.0/TLS 10.56.65.225:7012;ms-received-port=7012;ms-receivedcid=19E00 FROM: "Client";tag=09f804a3b1;epid=4906ed5712 TO: ;tag=554ef3a784
20 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
CSEQ: 1 SERVICE CALL-ID: 7b25d8f0304c4655814760e624d7c3aa CONTENT-LENGTH: 960 CONTENT-TYPE: application/msrtc-media-relay-auth+xml SERVER: RTCC/3.0.0.0 Media Relay Authentication Service ms-edge-proxy-message-trust: ms-source-type=EdgeProxyGenerated;ms-epfqdn= relay.contoso.com@contoso.com;ms-source-verified-user=verified AQAgAIaoZr4EM8gBrxTJGY83uqdEgRXUunam2c+RID/vAJeJSL4YINb AYMvRAHeANv+Zew== 35yqSF/p3A8gWXFHOC9YJA2kdvY= 480 intranet relay.contoso.com 3478 443
5 Security
5.1 Security Considerations for Implementers
5.1.1 Keyed Hash Function
[MS-AVEDGEA] uses the HMAC-SHA1 keyed hash function for generating tokens. The token generation process is explained in section 3.1.5.6.
21 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
5.1.2 Underlying Transport
Since the security tokens sent in the [MS-AVEDGEA] protocol response are in plain text, all the clients MUST communicate with the [MS-AVEDGEA] server through a channel secured by TLS, as specified in section 2.1.
5.1.3 Authentication
Using [MS-AVEDGEA], it is possible for unauthorized clients to request tokens and obtain them. Also, a client without proper authorization can send [MS-AVEDGEA] requests with different identities and obtain security tokens. This type of unauthorized activity precludes attempts by the [MS-TURN] server to perform resource management based on client identity (which is present as the hash in the token). Consequently, the [MS-AVEDGEA] server MUST authenticate the clients and verify the request before distributing tokens.
5.2 Index of Security Parameters
Security Parameter Shared secret keys between [MS-AVEDGEA] server and [MS-TURN] server HMAC-SHA1 [RFC2104] keyed hash algorithm Token generation algorithm TLS certificate (if TLS is used) Section 3.1.5.2 3.1.5.2 3.1.5.6 2.1
6 Appendix A: Product Behavior
The information in this specification is applicable to the following versions of the Microsoft product: Microsoft® Office Communications Server 2007 Microsoft® Office Communicator 2007 Exceptions, if any, are noted below. Unless otherwise specified, any statement of optional behavior in this specification prescribed using the terms SHOULD or SHOULD NOT implies Microsoft Office Communications Server 2007 behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that Microsoft Office Communications Server 2007 does not follow the prescription.
7 Appendix B: [MS-AVEDGEA] Schema
22 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
XML Schema for the MS-AVEDGEA
23 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
name="credentialsType"> name="username" type="xs:string" /> name="password" type="xs:string" /> name="duration" type="xs:positiveInteger" />
24 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
25 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
26 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008
Index
A Applicability, 8 C Capability negotiation, 8 E Examples overview, 19 request from client to server, 19 server response to client, 20 G Glossary, 4 I Introduction, 4 M Messages overview, 8 syntax, 8 transport, 8 Microsoft Office Communications Server 2007 behavior, 22 O Overview, 5 P Preconditions, 7 Prerequisites, 7 Protocol details, 14 R References informative, 5 normative, 4 Relationship to other protocols, 7 S Schema, 22 Security implementer considerations, 21 overview, 21 parameter index, 22 Server details, 14 Standards assignments, 8 Synopsis, 5 V Vendor-extensible fields, 8 Versioning, 8
27 of 27 [MS-AVEDGEA] - v1.01 Audio Video Edge Authentication Protocol Specification Copyright © 2008 Microsoft Corporation. Release: August 15, 2008