This topic describes issues to consider when designing security features for Microsoft Unified Communications Managed API applications.


There are two trust issues affecting Unified Communications Managed API applications:

  • Identify entities that are trusted by the application.

  • Establish trust with Microsoft Office Communications Server.

Hosts or Domains Trusted by the Application

Unified Communications Managed API applications can use Transmission Control Protocol (TCP) or Mutual Transport Layer Security (MTLS) to communicate between endpoints. If the application supports MTLS, use the Transport Layer Security (TLS) server connection manager to specify a list of hosts or domains trusted by the application. Incoming connections from these trusted hosts or domains are automatically trusted. Incoming connections from a host or domain that is not among the entries in this list are not allowed.

The TLS server connection manager has the ability to listen for incoming TLS connections. An application can also optionally set a flag to indicate whether MTLS is needed. TLS server connection manager allows an application to supply a list of allowed domains that are trusted for incoming connections. Incoming connections from any other host are not allowed.

The subject or alternate subject, if subject is empty, in the remote certificate is used to identify allowed domains. By default, the list of allowed domains contain the local host name. If this list is cleared, then any incoming connection is allowed. If subject is not empty, only computers having the matching subject name in the list of allowed domains are allowed. Each entry in this list is either an FQDN of the remote computer that can make incoming connections; or a domain, starting with a leading period, of computers that can connect. For example, or The list of allowed domains is used only when MTLS is enabled, since the remote certificate is needed for verification.

Applications Trusted by Office Communications Server

Use the Host Authorization tab on the Office Communications Server property page to configure Office Communications Server to trust the connection to the application, and to treat traffic from the application as another server. For more information, in the Microsoft Office Communications Server 2007 Administration Guide, see "Configuring Authorized Hosts."

Connection and Incoming Messages Throttling

With Unified Communications Managed API, you can manage performance issues such as denial of service (DOS) with connection and message throttling. Use connection and message throttling to optimize process memory when incoming requests are excessive and the application is slow to process requests. Unified Communications Managed API supports two types of throttling at the signaling layer in the TLS Server connection manager.

  • Connection throttling uses TCP-level push back by not consuming any more data until the number of transactions outstanding on the connection is reduced to a reasonable level. The application cannot send new requests on the connection, but responses are allowed to reduce the outstanding transaction count.

  • Message throttling controls the number of incoming messages placed in internal queues such as the thread pool queue, or individual session queues that are not yet processed by the application.

Message Throttling

When incoming messages are received, the platform creates events and stores them in internal queues. For example, an incoming INVITE message is stored as an SessionReceived event in a thread pool queue. These events consume memory, and memory may be consumed faster than the application can process messages. This results in increasing memory pressure over time. Since these events are not seen by the application yet, message throttling gives some control for limiting these events. Message throttling is available only for TLS Server connection manager.

Three properties are available to control message throttling in Unified Communications Managed API applications.

  • MessageThrottlingHighMark

  • MessageThrottlingLowMark

  • CurrentMessageThrottlingCount

Use the MessageThrottlingHighMark and MessageThrottlingLowMark properties to control upper and lower limits for outstanding incoming messages, including INVITE, page mode messages, and in-dialog messages that are maintained in internal queues including the thread pool queue, and not yet seen by the application. If the current number of outstanding incoming messages is higher than MessageThrottlingHighMark, new incoming messages are automatically rejected until the value drops below the value specified by MessageThrottlingLowMark.

By default, the MessageThrottlingHighMark and MessageThrottlingLowMark values are set to MaxValue indicating that throttling is disabled. If both the lower and upper limit values are set simultaneously to MaxValue, lower and higher limit checks are disabled.

Use the CurrentMessageThrottlingCount property to get the current count of incoming messages including INVITE, page mode messages, and in-dialog messages that are waiting in internal queues such as the thread pool queue or the session queue, for reporting to the application. This value is available only when message throttling is enabled. Otherwise, it is always 0.

When message throttling is enabled, new incoming messages are automatically rejected with an error message of 480 (Temporarily Unavailable). To reduce the message count, the application must process the messages. Determining the high and low limit values for outstanding incoming messages is difficult. One way to determine these values is to set the high mark to MaxValue – 1, making it unlikely that message throttling is used, and monitor the value of CurrentMessageThrottlingCount to see how it varies over a typical run. Since both values are not MaxValue in this case, throttling is enabled. This should give an idea regarding reasonable values to set as high and low limits.

Connection Throttling

Connection throttling relies on TCP-level push back so that the sender cannot send more traffic when the buffer is full. The application sets high and low marks on the outstanding number of transactions per connection either globally for all connections, or overrides the marks on a per connection basis. When the number of outstanding transactions goes beyond the high mark, the connection is in throttling mode and stays there until the number goes below the low mark. While connection throttling is enabled, incoming requests and responses are not consumed, so the sender cannot send more transactions until the buffer is cleared on the incoming side. To reduce the count, the outgoing outstanding transactions should time out, or the incoming outstanding transactions should be processed.

When connection throttling is enabled, outgoing operations fail, the exception is defined in an OperationFailureException class, with the OperationFailureReason class set to the ConnectionThrottling enumeration. The application can use this enumeration to determine that the connection is in throttling mode and refrain from sending more messages that might use the same connection. For example, INVITE sessions that have an affinity to a connection will use the same connection, so one failure of this nature on a session will likely cause the same failure for another message sent on that session. The application can register for the ThrottlingStateChanged event on the connection. To determine if the connection is still in throttling mode, use the IsConnectionThrottled property on the connection.

Three properties are available to control connection throttling in Unified Communications Managed API applications.

  • ConnectionThrottlingHighMark

  • ConnectionThrottlingLowMark

  • IsConnectionThrottled

Use the ConnectionThrottlingHighMark and ConnectionThrottlingLowMark properties to control the upper and lower limits for connections. When the number of outstanding transactions on a connection exceeds the upper limit, the connection is throttled until the number of outstanding transactions falls below the lower limit.

When the connection is throttled, send and receive operations fail. Responses, however, can be sent to reduce the level of transactions. Outstanding outgoing transactions that are pending will time out.

By default, the values of the upper and lower limits are set to MaxValue, indicating that throttling is disabled. If both the lower and upper limit values are set simultaneously to MaxValue, lower and higher limit checks are disabled.

The IsConnectionThrottled property gets a value indicating whether the connection is throttled. If throttling is enabled, then a connection can be controlled based on the load. The application can refrain from sending more traffic using the session until this connection is no longer in throttling mode. For example, a signaling session might cache a connection it uses for outgoing messages. If the connection is throttled, the application can refrain from sending more messages on that session until the connection is no longer throttled.

Security Notes

The following recommended actions can help authors create more secure applications.

  • Use TLS not TCP. Although the Unified Communications Managed API platform supports TCP, application developers should use TLS whenever possible, and should use MTLS in applications that act as servers. TLS helps mitigate spoofing, tampering, and repudiation issues. An application developer should not use TCP for an application that runs in a networking environment where computers are not fully trusted.

  • Use Office Communications Server to authenticate users and far-end hosts. When an application is acting as a client, authenticate users and the far-end host server. Authentication helps to ensure that the server is legitimate and that messages have not been tampered with through message signing. This approach helps mitigate spoofing, tampering, and repudiation issues.

  • Avoid contacts with untrusted servers. Applications should avoid contacting servers based on a received SIP extension header, an instant message, or other source. Use a single trusted server.

  • Do not assume that the server is trusted. A server can be trusted only if TLS or authentication is used.

  • Do not trust instant messages and URLs in presence documents. Applications should assume that instant messages and URLs contained in presence documents or instant messages are untrusted and can be potentially harmful.

  • Plan for and mitigate attacks at the application's entry points.

See Also