Version 2.5 TECHNICAL NOTE Oracle Protocol Agent Overview Stonesoft Corp. Itälahdenkatu 22A, FIN-00210 Helsinki Finland Tel. +358 (9) 4767 11 Fax. +358 (9) 4767 1234 email: info@stonesoft.com Copyright 2002 Stonesoft Corp. All rights reserved. All trademarks or registered trademarks are property of their respective owners.
Protocol Overview Oracle is a well-scalable (up to large enterprise systems) SQL-based Relational Database Management System (RDBMS) produced and marketed by Oracle Corporation. Oracle s networking technology Oracle Net8 (called SQL*Net prior to Oracle8) facilitates the use of Oracle services across multiple network protocols (like IP) and operating systems. Oracle Net8 is available for at least the following platforms: Microsoft Windows 95/98 (client only) Microsoft Windows NT (client and server) Solaris for Sun SPARC (client and server) Linux (client and server) HP-UX (client and server) IBM AIX (client and server) Caldera SCO UnixWare (client and server) Because this document focuses on topics affecting firewalling issues, it does not intend to cover the overall communication scheme in Oracle environments. The reader is assumed to be familiar with the documentation of Oracle Server and Oracle Corporation's support services like Oracle Technology Network (OTN) and Oracle MetaLink SM. Documentation of the Protocol Oracle Corporation has not published specification of the SQL*Net protocol. Information about communication model and configuring is available on Oracle Technology Network (OTN). Useful references: Oracle Technology Network: otn.oracle.com Oracle MetaLink Support Services: metalink.oracle.com Oracle Net8 FAQ: http://www.orafaq.org/faqnet.htm TECHNICAL NOTE 2
SQL*Net, Net7 and Net8 SQL*Net is Oracle's client/server middleware product that offers a transparent connection from client tools to the database or from one database to another. SQL*Net v2 is the basic communication software for Oracle 7 servers. Users have many options for allowing client access to Oracle7 servers via SQL*Net v2.x. Net8 is the successor to SQL*Net v2. Net8 is fully backward compatible, over the wire, with all the currently supported production releases of SQL*Net v2.x. Net8 clients can interact with either SQL*Net v2 or Net8 services. SQL*Net v2 clients can interact with Net8 services. The Net8 Listener supports both Oracle7 and Oracle8 databases allowing only one listener per node. TNS Protocol TNS (Transparent Network Substrate) is Oracle's networking architecture. TNS provides a uniform application interface to enable network applications to access the underlying network protocols transparently. The TNS architecture consists of three software components: TNS-based applications, Oracle Protocol Adapters, and networking software like TCP/IP. A TNS message is divided into two logical parts of variable lengths: binary type header and payload part. The header is in network byte order. The length of the header depends on the version of SQL*Net and it is not directly stored in the message. The length of the payload part is stored in the header. In most cases the payload part is in ASCII format. Oracle Application Proxies Some other firewall vendors also offer the Net8 Firewall Proxy function in their firewall. The Net8 Firewall Proxy has the same functionality as the Oracle Connection Manager. Oracle JServer and GIOP service Clients use the General Inter-ORB Protocol (GIOP) connection communicating with Oracle JServer. TECHNICAL NOTE 3
Communication Model Components Communication between an Oracle client and a server has three components (see Figure 1.1) concerning a firewall: client, Oracle Listener and Oracle database (the client wants to connect to). FIGURE 1.1 Communication components Client StoneGate Listener Database From StoneGate's point of view a client can be any kind of application communicating with a Listener by TNS protocol over TCP. Listener is an application that negotiates with the client how a database connection can be opened. Database is a service that is identified by an alias. Clients use aliases to access databases. Usually, there is an instance of a Listener running in the server providing Oracle database services. Thus, it cannot be presumed that also the database connection tries to pass a firewall, if a Listener connection has succeeded in it. Communication Process There are two main types of connections that may go through the firewall. At first, a client opens a Listener connection and sends a request for a database connection to it. The client can store its IP address or host name in the request. After receiving a response from the Listener, the client can close the connection and open a new connection to the database depending on the response. TECHNICAL NOTE 4
From the firewall's point of view, there are two alternative communication models: database connection redirection (see Figure 1.2) and dispatching (see Figure 1.3). On UNIX systems, the Listener process will fork a new Oracle process to deal with the new incoming connection. With UNIX, forked processes will inherit the resources of the parent process, in other words: file handles and TCP sockets. With earlier releases of SQL*Net for Windows NT, there is no capability of sharing a TCP socket between two processes and no way to inherit a TCP socket. To work around this restriction the main Oracle process creates a new thread of execution and thus, a local connection is made between the Listener and this new thread. The newly created database thread dynamically selects a new TCP port to use for the connection request and informs the Listener of the new port to be used. The Listeners requests the client to redirect the connection to this port. Listener Connection A client opens the Listener connection typically to destination port 1521 (with SQL*Net v1 to port 1525). Transport level protocol is TCP either plain or SSL encrypted. Payload data contains TNS messages, and the first TNS message (after the TCP handshake ) goes from the client to Listener. FIGURE 1.2 Database connection redirection Listener Client 1 StoneGate 2 3 Database 4 When the Listener is configured to use connection redirection (as in Figure 1.2), it responds to the client's request (phase 1) with an ANSWER message (phase 2). The text part of this response contains the IP address and a dynamically selected destination port number of the requested database service. After receiving the response client closes the Listener connection and tries to open a database connection (phase 3) to the negotiated address. TECHNICAL NOTE 5
Note: The negotiated database address is not necessarily behind the same firewall. FIGURE 1.3 Database connection dispatching Client 1, 5 StoneGate 4, 8 Listener Database 2, 6 3, 7 In database connection dispatching (Figure 1.3), a client does not open a separate connection to the database. Instead, the Listener communicates directly with the database and relays messages between the client and the database. When the Listener receives a request (phase 1) from a client, it checks the availability of the requested database service (phases 2 and 3) and responds to the client by an ACCEPT message (phase 4), which indicates connection dispatching. Typically, the Listener sends a RESEND message back to the client to get some time for checking the database service but still avoiding timeout on the client side. After detecting the RESEND message, the client sends same request again to the Listener. When the client has seen an ACCEPT message, the actual database communication takes place by DATA messages (phases 5, 6, 7 and 8). Database Connection A client opens a separate database connection directly to a dynamically selected destination port of the database server (in redirection mode). The source port of the connection is dynamic as well. The specification of this database connection is not known, but it is not used to negotiate other related connections. TECHNICAL NOTE 6
Useful Tools Sql*plus SQL*Plus is a command line SQL and PL/SQL language interface and reporting tool that ships with the Oracle Database Server. It can be used interactively or driven from scripts. The predecessor for SQL*Plus was called UFI (User Friendly Interface). UFI was included in the first releases of Oracle, its interface was primitive and not very user-friendly. Tnsping Tnsping is a command line utility, which determines whether or not a Listener is reachable. It, however, never actually connects with the Listener. A socket is never created and opened. It only checks to ascertain that a Listener is present on the server side. When one connects to a Listener using Tnsping, an estimate of the round trip time (RTT) in milliseconds appears. If Tnsping fails, a network error message appears without the resource use of a database connection. TOAD TOAD is Windows based software called a Tool for Oracle Application Developers. It is developed by Toadsoft company (www.toadsoft.com). Toad is used, e.g., for generating many kinds of traffic between a client and a database. TECHNICAL NOTE 7
Protocol Agent Description This document refers to the Oracle TNS Protocol Agent delivered with StoneGate Engine version 1.6.1 and later. The Usage of the PA The Oracle TNS PA is needed for Listener connections if any of following cases occurs: An IP address of a client is NATed (source NAT of the Listener connection) An IP address of a Listener is NATed (destination NAT of the Listener connection) The length of TNS messages is limited The number of addresses of database services where clients are allowed to connect is limited A Listener uses redirection of database connection (negotiation of related connection). This has been found to take place only when Oracle Server is run on Windows NT with WinSock API v. 1.1. Differences between SQL*Net Proxy and the PA The SQL*Net Proxy, provided by Oracle Corp., acts as an userspace proxy, but the Oracle TNS PA runs on kernel space as a non-proxy. Therefore the PA reaches the high performance and throughput, which can be important in case the Listener is not using connection redirection. The Oracle TNS PA supports all the common features of StoneGate engine, i.e. HA, NAT and load balancing. The Oracle TNS PA is fully transparent to the Oracle client, to the Listener and to the database server. The Oracle TNS PA is a stateful component and it sees all the connection data, both as a TCP stream and as individual packets. The Oracle TNS PA has security features, (e.g. the configurable limitation of the network), from where clients can connect the database. Operation The Oracle TNS PA has four main functions: Allowing a database connection through the firewall, if negotiated by a client and a Listener TECHNICAL NOTE 8
Modifying payload data of the Listener connection due to NAT Performing minimal protocol sanity checking Performing message length and database address verifying when configured. The Protocol Agent appears fully transparent both to a client and a Listener. The data of the Listener connection remains unchanged when NAT is not used for it. NAT modifications are directed only to CONNECT and ANSWER type TNS messages. Protocol Validation One TNS message can be divided to one or several TCP data stream portions. The PA uses a value of the TNS header field Packet Length to recognise message boundaries. Every TNS message has to contain valid binary header of 8 bytes. Request validation The PA recognises a TNS message to be a valid connection request, if: it is sent by the client type of the message is CONNECT. Response validation The PA recognises a TNS message to be a valid response, if: it is sent by the Listener type of the message is either ACCEPT or ANSWER. Database Connection Opening The PA allows a related database connection to open through the firewall when: a valid ANSWER type response is recognized the response contains HOST and PORT fields in the payload part the database address is allowed in the PA's configuration. TECHNICAL NOTE 9
A database connection is allowed to open from the same IP address as the client used in the Listener connection, but the client can use any source port. The database connection is allowed to open to an IP address in the HOST field and to port in the PORT field. If the HOST field contains host name instead of a plain IP address as a value, the PA generates an error to log and does not allow the data connection to open. NAT Modifications to Payload Data The PA modifies the payload data of a Listener connection in two cases: If destination NAT is applied to a Listener connection and a client stores Listener's IP address in a connection request, the PA changes a non-nated IP to a NATed one. Also, if the checksums of a TNS message are in use (greater than zeroes), the PA restores them to zeroes depending on the configuration of the PA. If a Listener suggests connection redirection to a connected Listener's IP address and this IP is destination NATed, the PA changes the non-nated IP to a NATed one. Also, if the checksums of a TNS message are in use (greater than zeroes), the PA restores them to zeroes depending on the configuration of the PA. Exceptions, Limitations and Assumptions Following general limitations have to be taken into account, if a Listener uses connection redirection: The Listener has to be configured to use IP addresses instead of host names, if a database connection is to open through the firewall. A client has to use same IP address as the source address of both the Listener and a database connection using, if the database connection is to open through the firewall. Database location and destination NAT When a database is running on a different host than the Listener and the address of the database is NATed, the Listener has to respond with the type of (non-nated) IP address to which the client can connect from the other side of the firewall. TECHNICAL NOTE 10
Checksums of TNS messages The PA leaves checksums of a TNS message unchanged after modification of the message data. When checksums are in use, it is recommended to configure the PA to reset checksums to zeroes after message modification. Net7 and TNS message splicing Most Net7 clients send at least data connection requests spliced into two parts (TCP stream portions). If the IP address of the database to be connected is destination NATed, the Oracle PA has to make modifications to both parts of the request message: to message length field in the first part and to database IP address in the second one. The PA has to delay the first part, because a new message length cannot be solved before analyzing the second part. Delaying means removing all TCP payload data from the first part and letting this empty TCP packet go on to the Listener. When the PA has got and modified the second part, it attaches data removed from the first packet to the beginning and allow whole message go to the Listener. As a result of this operation the whole request message arrives to Listener in one part. Net7, Windows NT and destination NAT Connections from Oracle Net7 client to Oracle Listener on Windows NT 4 cannot be destination NATed. Host Names in listener configuration The PA cannot process unresolved host names in Listener responses, and due to that a separate database connection cannot pass the firewall. In this case, the PA generates a log entry but does not drop the Listener connection. A Listener should be configured to answer plain IP addresses to clients to in order to avoid this problem. Security Benefits Oracle PA performs only minimal checking to payload data of the connection, because there is no official description of the TNS protocol available. TECHNICAL NOTE 11
Security benefits can be achieved by the use of two configuration parameters, which limit the length of TNS packets and the destination addresses of the separate database connection. Solving Typical Problems When running into a problem with Oracle PA, following actions should be performed to help an inspection: In which port a Listener is waiting for client connections? Typically the port is 1521. Check that the destination port in the rule allowing Listener connections is correct. Does the Listener use host names instead of plain IP addresses? In this case, change host names to IP addresses or ensure that the Listener can access a DNS server. Does the Listener propose to open a separate connection to the database? If it does not, try not to use the PA with Listener connections. Does the Listener use plain TCP instead of encrypted SSL connections? If it does not, change the connection type to normal TCP in Listener configuration. If the actions do not help to solve a problem, try to collect the following information: Switch Protocol Agents to diagnostic mode and check what kind of information appears to the log. What versions of Oracle client and server is used and on which platforms? Between which ports the Oracle client tries to open a separate database connection? Check the availability of the Listener using tnsping command line utility on the client side. Does the Listener run on same host than the database to be connected? What kind of special client software (other than standard Oracle components) is used? Get a tcpdump of Listener connections (typically opening to port 1521) from both sides of the firewall. The tcpdump has to be stored in binary format for example by command: tcpdump -s 2048 -w <output_file> -i<interface> -n port 1521 Performance The use of Oracle PA does not have any significant effect on the firewall's performance. The PA is attached to the Listener connection until it terminates, which induces a very small processing overhead for every type of TNS packet in the connection. TECHNICAL NOTE 12
Run-time memory usage of the PA is quite small. It allocates typically less than 128 bytes of memory space for every connection passing through. Fail-over transparency The Oracle PA implements all the normal high availability features of Protocol Agents, like connection fail-over between firewall nodes. In case of fail-over of a firewall node handling a redirected database connection, the Listener connection has to be reopened and negotiation has to take place to allow new database connection to pass through the firewall. Supported Environments The PA supports following Oracle environments: Oracle Net7 for Windows NT 4 Oracle Net8 for Windows NT 4 Oracle Net9 for Windows 2000 Server Oracle Net8 for Solaris v. 8 (Sun UltraSPARC 5) Oracle Net8 for Linux. Configuration of the PA Oracle PA supports following three configuration parameters. Maximum length of TNS packets The parameter limits the maximum length of TNS messages (measured as the length of TCP payload data). It is recommended to set this parameter only when a Listener uses database connection redirection, because in this case the PA is not handling packets containing actual database information. TABLE 1.1 Maximum length of TNS packets Parameter type integer Valid values 1-2147483647 Default value 4096 TECHNICAL NOTE 13
TNS packet checksum clearing This parameter affects handling of the checksum of a plain header and the whole message when the contents of the TNS message is modified by the PA due to NAT. Special value 0 means that the checksum is not calculated and it should not be used to check the integrity of a TNS message. The Oracle PA cannot recalculate checksums, if they are in use in a modified message. In this case the parameter can be used to force the PA to reset checksums to zero. However, the effect of this feature on Oracle components is unknown. TABLE 1.2 TNS packet checksum clearing Parameter type Valid values Default value string yes, no yes Allowed addresses of database connections This parameter limit destination addresses where a client can open separate database connection. TABLE 1.3 Allowed addresses of database connections Parameter type Valid values IP address network masks in form n.n.n.n Default value 255.255.255.255 Known Issues Oracle Server in HP-UX Oracle Listener runs in HP-UX has been found to act in an exceptional way when communicating with a client. The Listener can also send CONNECT type messages to the client. These messages do not contain an ASCII part, because they are obviously not used to negotiate end points of a new connection. TECHNICAL NOTE 14
Socket Sharing in Windows Some releases of SQL*Net for Windows NT use the Winsock API version 1.1, which does not have the capability to share a TCP socket between the Listener process and database process. To avoid this problem the Listener uses database connection redirection. Connection redirection can be avoided by changing an NT's system registry, if the Winsock API is of version 2.0 or later. A new parameter of type REG_EXPAND_SZ can be created under the path HKEY_LOCAL_MACHINE\Software\Oracle\<home>. The name of this parameter is USE_SHARED_SOCKET and value is TRUE. If the Oracle server manages several home structures, this parameter has to be created for each home path into the system registry. TECHNICAL NOTE 15