Creating HTTP and HTTPS connections in Java applications

Test

Chapter 5: Using SSL in Java Clients

---

Creating HTTP and HTTPS connections in Java applications
You can create HTTP connections in Java applications usingthe HTTP protocol handling code built in to the Java Developer’sKit, and HTTPS connections using the HTTPS protocol handler providedwith EAServer.

HTTP connections
The standard Java virtual machine provides HTTP connectivitywith these classes in java.net package:

• URL allows you to use UniformResource Locator strings for HTTP connections and other protocolconnections that can be represented by URLs.
• URLConnection represents a connectionto a server and resource indicated by a URL.
• HttpURLConnection extends URLwith additional methods that are specific to the HTTP protocol.
  

For details on these classes, see the JDK documentation. Thefollowing code shows a typical example. This code opens a connection,retrieves the data (text is assumed), and prints it:

1. URL url = new URL("http://www.sybase.com/");
   
2. URLConnection conn = url.openConnection();
   
3. conn.connect();
   
4. InputStreamReader content
   
5.     = new InputStreamReader(conn.getInputStream());
   
6. for (int i=0; i != -1; i = content.read())
   
7. {
   
8.     System.out.print((char) i);  
   
9. }

复制代码

HTTPS connections
The procedure for creating HTTPS connections is similar tothat for HTTP connections, except that you must install EAServer’sHTTPS protocol handler in the Java virtual machine and configureSSL parameters before opening a connection.

System requirements
EAServer’s HTTPS protocol handler uses the same SSLimplementation as used by Java and C++ IIOP clientsand requires a full client runtime install. For information on systemrequirements, see “Requirements”.


Installing the HTTPS protocol handler
The EAServer HTTPS protocol handler can be installed two ways:

• By configuring the java.protocol.handler.pkgs Javasystem property, making it the default handler for all HTTPS URLs.This is the recommended approach if you do not need to use anothervendor’s HTTPS protocol handler in addition to the EAServerimplementation.
• By calling one of the java.net.URL constructorsthat takes a java.net.URLStreamHandler as a parameter.This approach must be used if you must use more than one HTTPS protocolhandler in one EAServer or in one client application.
  

Configuring the default protocol handlers
The java.protocol.handler.pkgs Javasystem property configures the Java virtual machine default URLprotocol handlers. To use the EAServer handlers, you must add com.sybase.jaguar.net tothe list. For more information on this property, see the documentationfor java.net.URL in JDK 1.2.

In a client application, specify this property on the commandline; for example:

jre -Djava.protocol.handler.pkgs=com.sybase.jaguar.net ...

For an EAServer, set the JVM options property using the Advancedtab in the Server Properties dialog box:

Property	Value
com.sybase.jaguar.server.jvm.options	If not already set, set to: -Djava.protocol.handler.pkgs=com.sybase.jaguar.net If already set, verify that the value includes this option.JVM options must be separated with a comma.

You can specify more than one package by separating packagenames with a | (pipe) character, but you can configureonly one handler per protocol.

Specifying protocol handlers at runtime
If you must use more than one HTTPS protocol handler in oneEAServer or in one client application, you must call one of the java.net.URL constructorsthat takes a java.net.URLStreamHandler as a parameter.The specified java.net.URLStreamHandler instanceoverrides the default handler for the protocol specified by theURL. For example, to specify the EAServer HTTPS handler, use codelike this:

1. import java.net.*;
   
2. import com.sybase.jaguar.net.JagURLStreamHandlerFactory;
   
3. import com.sybase.jaguar.net.HttpsURLConnection;
   
4. 
   
5. ....
   
6. 
   
7. String url_string = "https://localhost:8081/index.html";
   
8. 
   
9. // The URL stream handler factory is required to create a stream
   
10. // handler.
    
11. JagURLStreamHandlerFactory fact = new JagURLStreamHandlerFactory();
    
12. 
    
13. // Extract the protocol from the front of the URL string
    
14. String protocol = url_string.substring(0, url_string.indexOf(":"));
    
15. 
    
16. // If the protocol is HTTPS, use the EAServer HTTPS handler. Otherwise,
    
17. // use the default handler
    
18. java.net.URL url;
    
19. if (protocol.equals("https"))
    
20. {
    
21.     url = new URL((URL)null, url_string,
    
22.         fact.createURLStreamHandler(protocol));
    
23. } else
    
24. {
    
25.     url = new URL(url_string);
    
26. }

复制代码

EAServer’s HttpsURLConnection class
EAServer provides the com.sybase.jaguar.net.HttpsURLConnection classto support HTTPS connectivity. This class extends java.net.URLConnection and implementsall methods of java.net.HttpURLConnection. HttpsURLConnection providesthese additional methods specifically for SSL support:

• A setSSLProperty method with signature:
  
  1. void setSSLProperty (String prop, String value) throws
     
  2.   CtsSecurity.InvalidPropertyException,
     
  3.   CtsSecurity.InvalidValueException

  复制代码
  
  Call this method to set the SSL properties described in “SSL properties”.
• A setSSLProperties method withsignature:
  
  1. void setSSLProperty (java.util.Properties props) throws
     
  2.   CtsSecurity.InvalidPropertyException,
     
  3.   CtsSecurity.InvalidValueException

  复制代码
  
  This method is the same as setSSLProperty,but allows you to set multiple properties with one call.
• A getSSLProperty method withsignature:
  
  1. void setGlobalProperty (String prop, String value) throws
     
  2.   CtsSecurity.InvalidPropertyException,
     
  3.   CtsSecurity.InvalidValueException

  复制代码
  
  Call this method to retrieve the SSL properties describedin “SSL properties”.
• A setGlobalProperty method withsignature:
  
  1. String[] getGlobalProperty(String prop) throws
     
  2.   CtsSecurity.InvalidPropertyException;

  复制代码
  
  Call this method to set the global SSL properties describedin “SSL properties”.Properties set with this method affect the handling of all HTTPSconnections, not just the current one.
• A getGlobalProperty method withsignature:
  
  1. CtsSecurity.SSLSessionInfo getSessionInfo() throws CtsSecurity.SSLException

  复制代码
  
  Call this method to retrieve the global SSL properties describedin “SSL properties”.
• A getSessionInfo method withsignature:
  CtsSecurity.SSLSessionInfo getSessionInfo() throws CtsSecurity.SSLExceptionThe SSLSessionInfo methods allow you todetermine the SSL session properties, such as the server’saddress, the client certificate in use, the server certificate inuse, and so forth. For more information, see the Interface Repositorydocumentation for the CtsSecurity::SSLSessionInfo IDLinterface. getSessionInfo throws an a SSLException instanceif SSL is not used on the connection.
  

Creating HTTPS connections

• Configure or install the EAServer HTTPS protocolhandler as described in “Installing the HTTPS protocol handler”.
• Create URL and URLConnection instances.If connecting to an EAServer, specify the address of an HTTPS listenerthat
  
  1. URL url = new URL("https://myhost:8081/index.html");
     
  2. URLConnection conn = url.openConnection();

  复制代码
  
  
• Verify that the object returned by URL.openConnection isof class com.sybase.jaguar.net.HttpsURLConnection,then set SSL properties for the connection. “SSL properties” describesthe SSL properties that can be set. At a minimum, you must specifythe qop and pin properties, as well as the certificateLabel propertyif using mutual authentication. For example:
  
  1. if (conn instanceof HttpsURLConnection)
     
  2. {
     
  3.   HttpsURLConnection https_conn =     (HttpsURLConnection) conn;
     
  4.   try
     
  5.   {
     
  6.     https_conn.setSSLProperty( "qop","sybpks_intl" );
     
  7.     https_conn.setSSLProperty( "pin", "secret");
     
  8.     https_conn.setSSLProperty(
     
  9.            "certificateLabel", "John Smith");
     
  10.   }
      
  11.   catch ( CtsSecurity.InvalidPropertyException ipe )
      
  12.   {
      
  13.     System.err.println( ipe );
      
  14.   }
      
  15.   catch ( CtsSecurity.InvalidValueException ive )
      
  16.   {
      
  17.     System.err.println( ive );
      
  18.   }

  复制代码
  
  
• Open the connection, for example:
  
  1. conn.connect();

  复制代码
  
  

Test

Once the connection is open, you can perform any valid operationfor a connection that uses java.net.HTTPUrlConnection.You can also call the getSessionInfo method toretrieve a CtsSecurity.SSLSessionInfo instancethat allows you to verify the SSL connection parameters. For example:

1. java.net.URLConnection conn;
   
2. ... deleted code that constructed URLConnection ...
   
3. if (conn instanceof HttpsURLConnection)
   
4. {
   
5.   HttpsURLConnection https_conn =     (HttpsURLConnection) conn;
   
6.   CtsSecurity.SSLSessionInfo sessInfo =
   
7.     https_conn.getSessionInfo();

复制代码

The SSLSessionInfo methods allow you todetermine the SSL session properties, such as the server’saddress, the client certificate in use, the server certificate inuse, and so forth. For more information, see the Interface Repositorydocumentation for the CtsSecurity::SSLSessionInfo interface.

SSL properties
Table 5-2 liststhe properties that can be set and retrieved with the HttpsURLConnection getSSLProperty, getGlobalProperty, setSSLProperty,and setGlobalProperty methods. Global properties are set and read with the getGlobalProperty and setGlobalProperty methods. Global properties affect all HTTPS connections, not just the HttpsUrlConnection instanceon which they are set. The right column in Table 5-2 lists which methods are valid for each property.

Some properties, if not set or set incorrectly, cause the connection to invoke an SSL callback method. You can install a callback to respond to these cases with the callbackImpl global property. If you do not install an SSL callback, the default callback implementation aborts the connection attempt.

Table 5-2: HTTPS Properties

Property name	Description	Valid for methods
pin	Always required when using SSL. Specifies the PKCS #11 token PIN. This is requiredfor logging in to a PKCS #11 token for client authenticationand for retrieving trust information. This property cannot be retrieved. If not set, set to “any”, or set incorrectly,the connection invokes the getPin callback method.	setSSLProperty setGlobalProperty
certificateLabel	Required when using mutual authentication. Specifies the client certificate to use if the connectionrequires mutual authentication. The label is a simple name thatidentifies an X.509 certificate/private key in a PKCS #11 token.If the property is not set and the connection requires mutual authentication, theconnection invokes the getCertificateLabel callbackmethod, passing an array of available certificate names as an inputparameter.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
qop	Always required when using SSL. Specifies the name of a security characteristic to use. See “Choosing a security characteristic” for more information.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
userData	Specifies user data (String datatype).This is an optional property. Client code can set user data duringconnection initialization and access it using SSLSessionInfo::getProperty methodin the SSL callback implementation. This may be useful as a mechanismto store connection-level context information that is otherwisenot available through the SSLSessionInfo interface.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
useEntrustID	Specifies whether to use the EntrustID or the Sybase PKCS #11 token for authentication. Thisis a Boolean (true or false) property. If this property is set tofalse, Sybase PKCS #11 token properties are valid and Entrust-specific propertiesare ignored. If this property is set to true, Entrust-specific propertiesare valid and Sybase PKCS #11 token properties are ignored.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
entrustUserProfile	Specifies the full path to the file containingan Entrust user profile. This property is optional when the Entrustsingle-login feature is available and required when this featureis not available. If not set, the connection invokes the getCredentialAttribute callbackmethod.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
entrustPassword	Specifies the password for logging into Entrust with the specified user profile. This property is optionalwhen the Entrust single-login feature is available and requiredwhen this feature is not available. If the password is requiredbut not set or set incorrectly, the connection invokes the getPin callback method. This property cannot be retrieved.	setSSLProperty setGlobalProperty
entrustIniFile	Specifies the path name for the EntrustINI file that provides information on how to access Entrust. Thisis required when the useEntrustid property isset to true. If not set, the connection invokes the getCredentialAttribute callbackmethod.	setSSLProperty getSSLProperty setGlobalProperty getGlobalProperty
callbackImpl	Specifies the name of a Java class that implementsthe CtsSecurity.SSLCallbackIntf interface. Forexample: com.acme.AcmeSSLCallbackSee “Implementing an SSL callback” for more information.	setGlobalProperty getGlobalProperty
availableQop	Retrieve only. A list of available security characteristics.The qop property can be set only to values that appear in this list.	getGlobalProperty
availableQopDesc	Retrieve only. A list of descriptionsfor the available security characteristics, in the same order aslisted in the value of the availableQop property.	getGlobalProperty
entrustReady	Retrieve only. Returns true if EntrustPKI software is available on the client, false otherwise.	getGlobalProperty

Choosing a security characteristicTo use SSL, you must specify the name of an available securitycharacteristic as the value for the qop property.The characteristic describes the CipherSuites the client uses whennegotiating an SSL connection. When connecting, the client sendsthe list of CipherSuites that it uses to the server, and the server selectsa cipher suite from that list. The server chooses the first ciphersuite in the list that it can use. If the server cannot use anyof the available CipherSuites, the connection fails.

Chapter 13, “Security Configuration Tasks” describesthe security characteristics that are provided with EAServer. Atruntime, you can retrieve a list of characteristics and their descriptionsby retrieving the availableQop and availableQopDesc properties.

http://192.87.31.188/docs/eassec/eassec25.htm