Services Provided by the Connection Manager

A connection manager provides the following services to the application and endpoints.

1. Manage the local certificate.
   
   This service is automatic. The local certificate must be installed in the local certificate store and the application must have access to this certificate store. The application passes the name of the certificate's issuer and the certificate's serial number to be used in the connection manager constructor. After the connection manager has been created, the application can change the certificate dynamically by using SetLocalCertificate. However, this method can be called only when the connection manager is not listening. To change a certificate, the application stops listening, changes the certificate, and starts listening again. For the period during which the application is not listening, incoming connections are not be honored, so there is the potential risk of losing incoming connections. It should be noted that the need to change certificates occurs very seldom. An example scenario is a process that monitors certificate expiration dates and can acquire a new certificate and require the service to use this new certificate.
   
   When the application uses TLS transport, a local certificate is used for TLS negotiation when needed. In order to trust the remote certificate, the root certificate should also exist in the local certificate store. Supplying an invalid or expired certificate causes an exception to be thrown at the time the connection manager is supplied with the certificate information (either in a constructor or using the SetLocalCertificate method). However, after TLS negotiation is complete, Office Communications Server 2007 does not verify expiry for either the local or remote certificate.
   
   When TLS negotiation for an incoming connection fails, the connection manager raises an event. The TlsFailureException in the event provides additional information such as the TlsFailureReason.
   
   
2. Add a contact header.
   
   This service is not available to the application. The specific information in the contact header is determined based on the type of connection manager and its listening state, if any. If the connection manager is disabled for listening, then a specific proxy=replace URI parameter is added to the contact header. Some servers use this as hint to perform some address translation, the net effect of which is to reuse the connection for incoming traffic. If the connection manager is listening, this header will be missing. Also, the contact header will have an maddr parameter in some cases. TLS negotiation is affected by the presence of an maddr parameter, hence it will be missing in some TLS scenarios. If an endpoint has a Globally Routable User Agent URI (GRUU), it might not leverage this service except for REGISTER messages in which the contact header should not include a GRUU. Note that a contact header enables a remote to reconnect, so if a port is missing, the URI will not enable the remote to reconnect.
   
   
3. Dispatch incoming messages outside a dialog to the appropriate endpoint.
   
   This is done automatically with no special action required of the application. The endpoints are responsible for providing delegates to handle these messages. The following paragraphs describe the various mechanisms implemented.
   
   
   • A SipEndpoint (see About Endpoints) uses a unique ms-opaque URI parameter in its Contact header field for a REGISTER message. This enables the server to add the Contact header field to the Request-URI of any incoming messages. The ms-opaque parameter in the Request-URI is used to uniquely identify the endpoint that should receive the message. One reason for this is that a To header field URI cannot be relied upon to dispatch, especially when routing is involved. For example, an endpoint can be chosen by the server to handle an incoming INVITE message that was targeted for another endpoint. In such a case, the To header field URI will not match the endpoint that should process the message. The Request-URI might have the FQDN and hence does not help to determine the endpoint to dispatch to.
     
     
   • For a SipPeerToPeerEndpoint (see About Endpoints), the dispatch mechanism is very complex. A SipPeerToPeerEndpoint can be created using any of a number of constructors. In brief, if a SipPeerToPeerEndpoint is created with a specific GRUU that contains a grid parameter, the grid parameter is used as the endpoint context key. If a grid parameter was not supplied, a unique key is created for the endpoint context. If the peer-to-peer endpoint is created without passing a GRUU, a unique key is created for the endpoint context, the same as in the case where a GRUU was supplied without a grid parameter. In all cases, the SipPeerToPeerEndpoint has its own endpoint ID (EPID). In addition to a GRUU, the SipPeerToPeerEndpoint always has a URI that normally should match the GRUU’s user@host part.
     
     
   • The connection manager does not support forking of an INVITE request to multiple endpoints. For this reason every incoming message should be routable to a unique endpoint. Accordingly, the SipPeerToPeerEndpoint Uri property will contain the port as well as the key (a grid parameter or a uniquely generated key) using an ms-opaque parameter. If the Uri property is publicized through offline methods, and an incoming message arrives using the Uri property as the target, the message can be routed uniquely to the SipPeerToPeerEndpoint.
     
     The connection manager uses the following algorithm to route incoming messages to a SipPeerToPeerEndpoint.
     
     If the Request-URI contains an ms-opaque or grid parameter, the message is dispatched to the SipPeerToPeerEndpoint with a matching endpoint context.
     
     If the Request-URI contains neither an ms-opaque nor grid parameter, the message is dispatched using the To header field (URI and epid header parameter) according to the following rule:
     
     
   • Find all endpoints that match the To header field URI.
     
     If there is a unique matching endpoint, send the message to this endpoint.
     
     If there are multiple matching endpoints, choose the one that matches the EPID in the To header field (if there is one).
     
     If there are multiple matching endpoints and the To header field does not contain an EPID, choose the endpoint that has the largest number of matching URI parameters in the To header field URI (that is, user@host). That is, the message should contain all parameters in the endpoint URI for a match. Choose the first endpoint that matches and has the greatest number of parameters.
     
     If there is no match using the preceding steps and the connection manager hosts a single SipPeerToPeerEndpoint and StrictDispatching is set to false (the default), deliver the message to the single SipPeerToPeerEndpoint.
     
     If there are multiple SipPeerToPeerEndpoints with the same GRUU but they differ only in EPID, dispatching is not easy when the incoming message contains no ms-opaque or grid parameters and the To header field does not contain an EPID. There are two sub-cases depending on whether the To header field URI is or is not a GRUU. In either case, the connection manager searches for an endpoint that matches the To header field URI. For this reason it is desirable for the SipPeerToPeerEndpoint to have a URI that matches the GRUU’s To header field URI. If there are multiple endpoints, then one is picked that matches the largest number of parameters as before.
     
     If there are multiple SipPeerToPeerEndpoints with the same non-GRUU URIs, they differ only in EPID. If an incoming message is intended to target one of these endpoints, then it should contain the EPID. Otherwise, the first endpoint that matches the greatest number of parameters will be chosen.
     
     The following figure summarizes this rule as a flowchart.
     
     
     
   Having multiple SipPeerToPeerEndpoints that have the same GRUU but no grid parameter represents a misconfiguration of the server. If a message is targeted with a GRUU (which is meant to uniquely identify an endpoint), the connection manager cannot determine which endpoint should receive the message because there are multiple endpoints with the same GRUU. For this reason, the application should avoid creating multiple endpoints with the same GRUU unless the GRUU also contains a grid parameter. Office Communications Server 2007 is not designed to dispatch a GRUU-targeted message to one of numerous endpoints that match the GRUU. Instead, matching is done using URIs. For a GRUU-based service, the two supported scenarios are as follows:
   
   
   1. One SipPeerToPeerEndpoint with a GRUU for the connection manager with StrictDispatching set to false.
      
      
   2. Multiple SipPeerToPeerEndpoints each with a GRUU but a different grid parameter.
      
      
4. Create a new connection for a destination tuple.
   
   Office Communications Server 2007 is not designed to make a connection to a GRUU target. To reach a GRUU target, the application should use either a SipEndpoint or a SipPeerToPeerEndpoint that uses a proxy. In either case, the message is delivered to the server or to a proxy that should be capable of routing the message using a GRUU. If a SipPeerToPeerEndpoint without a proxy is used to make a connection to a GRUU target, the connection will be made under the assumption that the GRUU target is a plain URI. In this case the user@host part of the GRUU is taken. Because a GRUU specifies neither a transport mechanism nor a port, TCP transport using port 5060 is assumed. In other words, the destination tuple that is formed is (user@host of the GRUU, 5060, TCP), which might not be what the application intended. It is the responsibility of the application to ensure that such connections are not requested.
   
   When making a new outgoing TLS connection, Office Communications Server 2007 ensures that the host of the destination tuple matches that of the remote certificate supplied during TLS negotiation.
   
   
5. Share a connection.
   
   This service is available when using a server connection manager. Outgoing connections are managed in a set of pools. Each connection pool is identified by the destination tuple (host, port, transport). A pool can have one or more connections to the same destination. By default, every pool creates up to five connections. This value can be changed globally or on a per-pool basis. If an endpoint or subcomponent of an endpoint requires a connection and the pool has reached its maximum, the existing connections in the pool are shared in a round robin fashion. This type of connection sharing is intended to improve throughput.
   
   
6. Respond to incoming messages automatically when the message cannot be dispatched to an endpoint.
   
   This is done automatically. If a message cannot be delivered to an endpoint or the endpoint did not register for the message, the connection automatically responds with 500 Internal Server Error.
   
   
7. Control the lifetime of connections.
   
   Any incoming connection is actively disconnected if there are no endpoints. Otherwise, an incoming connection will be disconnected if no valid message is received within about one minute.
   
   If there is no traffic on an incoming connection for 15 minutes, the connection is disconnected.
   
   If there is no traffic on an outgoing connection used in a server connection manager, the connection is disconnected.
   
   Outgoing connections that use the client connection manager do not have any timeout for Idle. The idle timeout for outgoing and incoming connections can be controlled by the application on a per-connection basis or globally. The application cannot set the idle timeout for outgoing connections that are created using a client connection manager.
   
   Each outgoing connection has a reference count equal to the number of components that have cached the connection. When the reference count drops to zero, the connection is marked for disconnection after one minute unless the reference count becomes positive during that time.
   
   
8. Start or stop listening for incoming connections.
   
   The application can start listening using a specific IP address or by passing the IP address 0.0.0.0 to indicate that it intends to listen using all available addresses. If port 0 is specified, the application intends to listen using any available port.
   
   
9. Manage a list of hosts that are trusted for incoming connections.
   
   The host entries in the trusted list should match the subject or alternate subject (if the subject is missing) of the remote certificate that was supplied during TLS negotiation for an incoming connection. By default, and for security reasons, this list is populated only with the local host name. The application is responsible for adding a specific FQDN or domain to this list to accept incoming connections from trusted sources. However, when making an outbound connection using a TLS server connection manager that is configured for mutual TLS, the host of the connection is automatically added to this trusted list before the connection is made, provided that the trusted list is non-empty. This allows the host to connect. This is done for convenience and there is no mechanism to disable this behavior. If the trusted list is cleared, anyone can make an incoming connection.
   
   
10. Manage enhanced key usage.
    
    This controls the kinds of certificates that are acceptable. Typically, a certificate is marked for client authentication or server authentication or both. If this list is empty, then any kind of certificate is accepted. If the list is non-empty, only a certificate that carries the key usages mentioned in this list is accepted.