Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

> ## Secure Sockets Layer (SSL)

> You can use the Secure Sockets Layer (SSL) to provide a security infrastructure that protects AppServer communications both on the Internet and the intranet. SSL provides data privacy over network connections and authentication between clients and servers on those connections using elements of Public Key Infrastructure (PKI). These elements include private and public keys that the clients and servers use to authenticate each other and to set up data encryption and decryption services between the initiator of the communications (SSL client) and the responder (SSL server). The server is identified by the private key that it stores and the client is identified as a valid SSL client for that server by the public key that it stores and provides to the server. SSL clients gain access to public keys using digital (public key) certificates provided by a trusted certificate authority (CA) that also provides the private key confidentially to the SSL server.

> SSL is both application and transport independent. For the AppServer, OpenEdge supports SSL in two basic transport contexts:

> - HTTP — For Internet applications.

> - AppServer protocol — For intranet applications.

> For more information on SSL and how it uses private and public keys and public key certificates to handle security tasks in these contexts, see OpenEdge Getting Started: Core Business Services .

> Note: SSL incurs heavy performance penalties, depending on the client, server, and network resources and load.

> ##### Secure AppServer configurations

> To enable SSL security between SSL clients and servers, you must manage access to the public and private keys for each SSL client and server, respectively. How you do this depends on the SSL configuration you are managing. To secure an AppServer using SSL, you can configure the AppServer connections in two different ways or in combination as follows:

> 1. Internet-secure AppServer — A secure connection over the Internet between the AppServer client and a Web server that hosts an appropriate OpenEdge adapter to access the AppServer. The connection between the client and Web server is secured using HTTPS (HTTP tunneled through SSL).

> 2. SSL-enabled AppServer — A secure connection directly between the client and the AppServer. This connection is secured by tunneling the direct AppServer protocol through SSL.

> 3. Internet-secure and SSL-enabled AppServer — A combination of 1. and 2., where the connection between the AppServer client and the Web server is secured using HTTPS (as in 1.) and the connection between the appropriate OpenEdge adapter and AppServer is secured using SSL tunneling, similar to a direct connection between the AppServer client and AppServer (as in 2.).

> Note: This configuration is likely to incur the heaviest performance penalty of the three because it uses two SSL connections, each of which requires encryption and decryption of data for each client request and for each AppServer response.

> The remaining sections on SSL and the AppServer describe:

> - Internet-secure AppServer

> - SSL-enabled AppServer

> - SSL connection handling for brokers and agents of an SSL-enabled AppServer

> - Identifying the SSL server connected to an AppServer client

> ##### Internet-secure AppServer

> You can configure HTTPS security for an AppServer application on the Internet, depending on the type of client and AppServer adapter. For an AppServer client that directly calls AppServer application services (4GL client or .NET and Java Open Client), you use the AppServer Internet Adapter (AIA) to access the AppServer on behalf of the client. For a Web service client that accesses AppServer application services as Progress 4GL Web services, you use the Web Services Adapter (WSA) to access the AppServer on behalf of the Web service accessed by the client. The OpenEdge Adapter for Sonic ESB also supports Web service client or general ESB client and service access to the AppServer as an OpenEdge service with Internet and intranet security on the ESB side provided by the Sonic Enterprise Service Bus (ESB).

> In all cases, to secure an Internet connection between the client and AppServer using HTTPS, you must configure the:

> - Client as an HTTPS client

> - Server hosting the AppServer adapter as an HTTPS server

> You can configure and connect the client (AppServer or Web service client) as an HTTPS client, depending on the client type, as described in Table 4–3:

> Table 4–3: HTTPS management for clients of an Internet-secure
> AppServer
> Client type... | HTTPS configuration is supported by...
> --- | ---
> 4GL client | OpenEdge using the `certutil` command-line tool to manage public key certificates. The client connects using an HTTPS URL formatted for accessing an Internet-secure AppServer. For more information on managing the public key certificates, see the sections on managing OpenEdge key and certificate stores in OpenEdge Getting Started: Core Business Services . For information on connecting to an Internet-secure AppServer from a 4GL client, see the sections on using the -URL connection parameter in Chapter 3, "Programming Progress 4GL Client Applications," and the sections on formatting an Internet URL to the AppServer using HTTPS in Appendix A "Connecting to AppServers Using a URL."
> Open Client | Microsoft tools to manage public key certificates for .NET Open Clients and by OpenEdge using the `procertm` command-line tool to manage public key certificates for Java Open Clients. The client connects using an HTTPS URL formatted for accessing an Internet-secure AppServer. For more information on managing public key certificates for .NET clients, see the information on managing certificate stores in the Microsoft .NET documentation. For more information on managing public key certificates for Java clients, see the information on managing certificate stores in OpenEdge Development: Java Open Clients . For information on connecting to an Internet-secure AppServer from an Open Client, see the sections on connecting to the AppServer in OpenEdge Development: Open Client Introduction and Programming , and the sections on formatting an Internet URL to the AppServer using HTTPS in Appendix A "Connecting to AppServers Using a URL."
> Web service client | Web service client platforms for Web service clients. Web service clients connect to or access the Web service through the Web server using the WSA URL configured for it and provided to the Web service client as part of other Web service access information included in the Web Services Description Language (WSDL) file for the specified Web service. The WSA, itself, maintains the connection information to the Web service specified in the WSDL file. For more information on managing public key certificates for Web service clients, see the documentation on your Web service client platform. For more information on how a Web service client connects to and accesses the WSA-managed Web service, see the information on programming Web service clients in OpenEdge Development: Web Services and the information on managing a WSA and deploying a Progress 4GL Web service in OpenEdge Application Server: Administration .
> ESB client or service | The Sonic ESB. An ESB client or service accesses other ESB services using the interfaces provided by the Sonic ESB. For more information on managing public key certificates and any other ESB security configuration options for ESB clients and services, and on accessing ESB services in general (including OpenEdge services), see the Sonic ESB documentation. For more information on using the OpenEdge Adapter for Sonic ESB to support OpenEdge services on the Sonic ESB, see OpenEdge Development: Messaging and ESB .

> On the server end of the Internet connection, you can configure the HTTPS server and OpenEdge adapters that access the AppServer as described in Table 4–4.

> Table 4–4: HTTPS management for Internet-secure AppServer adapters
> Adapter type... | HTTPS configuration is supported by...
> --- | ---
> AIA | The Web server utilities provided to manage private key stores for the Web server accessed as an HTTPS server. For more information on managing key stores on a Web server, see the Web server documentation. Also, in order to ensure that AppServer clients use HTTPS to access the AIA, you must set the `httpsEnabled` property appropriately in the `ubroker.properties` file for the AIA. For more information, see the sections on configuring the AIA in OpenEdge Application Server: Administration .
> WSA | The Web server utilities provided to manage private key stores for the Web server accessed as an HTTPS server. For more information on managing key stores on a Web server, see the Web server documentation. The use of HTTPS by the WSA is determined by its URL, which you specify when you create a WSA instance. Therefore, if specified, a WSA instance requires that clients use HTTPS to access all Web services that it manages. For more information, see the sections on creating and managing a WSA in OpenEdge Application Server: Administration .
> OpenEdge Adapter for Sonic ESB | The Sonic ESB utilities provided to manage a private key store for the HTTP direct acceptor used to handle requests to the ESB from Web service clients. For more information on managing key stores for an HTTP direct acceptor for the Sonic ESB, see the Sonic ESB documentation. The Sonic ESB also supports access to an OpenEdge service from clients and services on the ESB other than Web service clients. For information on securing access to OpenEdge services from these types of clients, see the Sonic ESB documentation. For more information on managing the OpenEdge Adapter for Sonic ESB, see the sections on the OpenEdge Adapter for Sonic ESB in OpenEdge Application Server: Administration .

> ##### SSL-enabled AppServer

> To secure a direct connection between the client and AppServer using SSL, you must configure the:

> - AppServer client as an SSL client.

> - AppServer, itself, as an SSL server.

> Note: A given AppServer can support only SSL or non-SSL connections. It cannot support both simultaneously. So, to allow applications to run in both an SSL-enabled and non-SSL-enabled AppServer environment, you must dedicate at least one AppServer to SSL connections and another AppServer to non-SSL connections.
> SSL-enabled and non-SSL-enabled AppServers can both run as Internet-secure AppServers using the AIA (see the "Internet-secure AppServer" section).

> You can configure and connect the SSL client to the AppServer, depending on the client type, as described in Table 4–5.

> Table 4–5: SSL management for clients of an SSL-enabled AppServer
> Client type... | SSL configuration is supported by...
> --- | ---
> 4GL client | OpenEdge using the `certutil` command-line tool to manage public key certificates. The client connects using an AppServer URL formatted for accessing an SSL-enabled AppServer. You can specify this URL using the `AppServerS` protocol for an SSL connection mediated by a NameServer or using the `AppServerDCS` protocol for an SSL connection directly to a specified AppServer. For more information on managing the public key certificates, see the sections on managing OpenEdge key and certificate stores in OpenEdge Getting Started: Core Business Services . For information on connecting to an SSL-enabled AppServer from a 4GL client, see the sections on using the -URL connection parameter in Chapter 3, "Programming Progress 4GL Client Applications," and the sections on formatting an AppServer URL using the `AppServerS` or `AppServerDCS` protocol in Appendix A "Connecting to AppServers Using a URL."
> Open Client | Microsoft tools to manage public key certificates for .NET Open Clients and by OpenEdge using the `procertm` command-line tool to manage public key certificates for Java Open Clients. The client connects using an AppServer URL formatted for accessing an SSL-enabled AppServer. You can specify this URL using the `AppServerS` protocol for an SSL connection mediated by a NameServer or using the `AppServerDCS` protocol for an SSL connection directly to a specified AppServer. For more information on managing public key certificates for .NET clients, see the information on managing certificate stores in the Microsoft .NET documentation. For more information on managing public key certificates for Java clients, see the information on managing certificate stores in OpenEdge Development: Java Open Clients . For information on connecting to an SSL-enabled AppServer from an Open Client, see the sections on connecting to the AppServer in OpenEdge Development: Open Client Introduction and Programming , and the sections on formatting an AppServer URL using the `AppServerS` or `AppServerDCS` protocol in Appendix A "Connecting to AppServers Using a URL."
> AIA | OpenEdge: Using the `certutil` command-line tool to manage public key certificates for the AIA as an SSL client of the AppServer. Using the Progress Explorer framework to configure the AIA properties required to specify that the connection to the AppServer uses SSL. In this configuration, with the AIA in an SSL connection to the AppServer, the 4GL or Open Client accessing the AppServer through the AIA would typically connect to the AIA using HTTPS in order to ensure a secure connection all along the way to the AppServer (see Table 4–3). For more information on managing the public key certificates for an AIA as an SSL client, see the sections on managing OpenEdge certificate stores in OpenEdge Getting Started: Core Business Services . For more information on configuring an AIA to specify an SSL connection to the AppServer, see the sections on AIA administration in OpenEdge Application Server: Administration .
> WSA | OpenEdge: Using the `certutil` command-line tool to manage public key certificates for the WSA as an SSL client of the AppServer. Using the Progress Explorer to configure the required Web service properties for each Web service managed by the WSA that you want to establish an SSL connection to the AppServer. Note: Each Web service managed by a WSA can be configured individually as an SSL-enabled Web service. However, you manage the public key certificates for all SSL-enabled Web services that are managed by a single WSA using the same certificate store. In this configuration, with a given WSA-managed Web service in an SSL connection to the AppServer, the Web service client would typically connect to the Web service itself using HTTPS in order to ensure a secure connection all along the way to the AppServer (see Table 4–3). For more information on managing the public key certificates for a WSA as an SSL client of the AppServer, see the sections on managing OpenEdge certificate stores in OpenEdge Getting Started: Core Business Services . For more information on configuring a Web service as an SSL-enabled Web service, see the sections on WSA and Web service administration in OpenEdge Application Server: Administration .
> OpenEdge Adapter for Sonic ESB | Both: OpenEdge using the `certutil` command-line tool to manage public key certificates for the OpenEdge Adapter for Sonic ESB as an SSL client of the AppServer. Sonic ESB using the Sonic ESB Explorer to configure the required OpenEdge service properties for each OpenEdge service managed by the OpenEdge Adapter for Sonic ESB that you want to establish an SSL connection to the AppServer. Note: Each OpenEdge service managed by a OpenEdge Adapter for Sonic ESB can be configured individually as an SSL-enabled OpenEdge service. However, you manage the public key certificates for all SSL-enabled OpenEdge services that are managed by a single OpenEdge Adapter for Sonic ESB using the same OpenEdge certificate store. In this configuration, with a given OpenEdge service in an SSL connection to the AppServer, a Web service client would typically connect to the OpenEdge service itself using HTTPS to a SonicMQ broker, which then communicates with the OpenEdge Adapter for Sonic ESB in order to ensure a secure connection all along the way to the AppServer (see Table 4–3). For more information on managing the public key certificates for a OpenEdge Adapter for Sonic ESB as an SSL client of the AppServer, see the sections on managing OpenEdge certificate stores in OpenEdge Getting Started: Core Business Services . For more information on configuring an OpenEdge service as an SSL-enabled OpenEdge service, see the sections on OpenEdge Adapter for Sonic ESB and OpenEdge service administration in OpenEdge Application Server: Administration . For more information on using the OpenEdge Adapter for Sonic ESB to support OpenEdge services on the Sonic ESB, see OpenEdge Development: Messaging and ESB .

> You can configure an AppServer as an SSL server by setting the appropriate SSL properties for the AppServer using the Progress Explorer framework. You must also manage a key store that contains the private key(s) for the AppServer using the `pkiutil` command-line tool.

> For more information on configuring an SSL-enabled AppServer, see the sections on AppServer administration in OpenEdge Application Server: Administration . For more information on managing key stores for an SSL-enabled AppServer, see the sections on managing OpenEdge key stores in OpenEdge Getting Started: Core Business Services .

> Note: An SSL-enabled AppServer can accept only SSL AppServer connections.

> ##### SSL connection handling for brokers and agents of an SSL-enabled AppServer

> When you configure an SSL-enabled AppServer, the AppServer broker and its agents use SSL-enabled server sockets depending on the AppServer operating mode, as shown in Table 4–6.

> Table 4–6: Processes using SSL server sockets for an SSL-enabled AppServer
> For this AppServer operating mode ... | SSL server sockets are used for the ...
> --- | ---
> State-reset | AppServer broker and agents.
> State-aware | AppServer broker and agents.
> Stateless | AppServer broker only.
> State-free | AppServer broker only.

> Thus, for state-reset and state-aware modes, the AppServer broker accepts an initial SSL connection from the SSL client, then disconnects and assigns that client an SSL connection to an available AppServer agent. Because these connections are sequential, encryption overhead is essentially reduced to a single connection per SSL client-server exchange, even though the client connects to both the broker and agent. The only additional overhead is the brief exchange between the broker and agent to locate and hand off the agent connection to the client.

> For stateless and state-free operating modes, the client is always connected to and exchanges all network communications with the AppServer broker, limiting encryption overhead to this single connection. All communications between the broker and agents occurs on the same system with no data broadcast on the network where it can be intercepted. Therefore, the communications between broker and agents is in clear text, eliminating any needless encryption overhead between them.

> ##### Identifying the SSL server connected to an AppServer client

> When you establish an SSL session as part of the client connection to an AppServer, you can determine the identity of that server using an interface mechanism appropriate for the type of client, as shown in Table 4–7.

> Table 4–7: Determining SSL server identity for an AppServer connection
> Client type ... | Identifies its SSL server using the ...
> --- | ---
> Progress 4GL client. | `SSL-SERVER-NAME` attribute on the server object handle.
> .NET or Java Open Client. | Common method on the AppObject.
> Any client of a Progress 4GL Web service. | SSL interface supported by the Web service client platform.

> For Progress 4GL and OpenClients, the SSL server identity is returned as the SSL server’s X.500 Subject name field (from the server certificate) after the SSL session as part of the AppServer connection has been established. For Web service client platforms, the method of identifying the SSL server is platform-determined, but is typically also the value of the SSL server’s X.500 Subject name field.

> For an Internet-secure AppServer or Progress 4GL Web service, the SSL server is the Web server that hosts the AIA or WSA. For an SSL-enabled AppServer, the AppServer itself is the SSL server. For more information on SSL and OpenEdge SSL clients and servers, see OpenEdge Getting Started: Core Business Services .

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095