Installing and Configuring SSL Support
What Is Secure Socket Layer Technology?
Secure Socket Layer (SSL) technology allows web browsers and web servers to communicate over a secure connection. In this secure connection, the data that is being sent is encrypted before being sent and then is decrypted upon receipt and before processing. Both the browser and the server encrypt all traffic before carriage any data. SSL addresses the following vital security considerations.
• Certification: During your initial attempt to communicate with a web server over a secure connection, that server will present your web browser with a set of credentials in the form of a server certificate. The purpose of the certificate is to verify that the site is who and what it claims to be. In some cases, the server may request a certificate that the client is who and what it claims to be (which is known as client certification).
• Confidentiality: When data is being passed between the client and the server on a network, third parties can view and intercept this data. SSL responses are encrypted so that the data cannot be deciphered by the third party and the data remains confidential.
• Integrity: When data is being passed between the client and the server on a network, third parties can view and intercept this data. SSL helps guarantee that the data will not be modified in transit by that third party.
To install and configure SSL support on your stand-alone web server, you need the following components. SSL support is already provided if you are by the Attention Server. If you are by a different web server, consult the documentation for your product.
• A server certificate keystore (see Understanding Digital Certificates).
• An HTTPS connector (see By SSL).
To verify that SSL support is enabled, see Verifying SSL Support.
Understanding Digital Certificates
________________________________________
Note: Digital certificates for the Attention Server have already been generated and can be found in the directory
________________________________________
To use SSL, an attention server must have an associated certificate for each external interface, or IP address, that accepts secure relations. The theory behind this design is that a server should provide some kind of reasonable assurance that its owner is who you reflect it is, particularly before receiving any sensitive information. It may be useful to reflect of a certificate as a “digital driver’s license” for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.
The digital certificate is cryptographically signed by its owner and is hard for anyone else to forge. For sites involved in e-buying or in any other business transaction in which certification of identity is vital, a certificate can be bought from a well-known certificate power (CA) such as VeriSign or Thawte.
Sometimes certification is not really a concern–for example, an administrator may austerely want to ensure that data being transmitted and expected by the server is private and cannot be snooped by anyone eavesdropping on the connection. In such cases, you can save the time and expense involved in obtaining a CA certificate and austerely use a self-signed certificate.
SSL uses public key cryptography, which is based on key pairs. Key pairs contain one public key and one private key. If data is encrypted with one key, it can be decrypted only with the other key of the pair. This property is fundamental to establishing trust and privacy in transactions. For example, by SSL, the server computes a value and encrypts the value by its private key. The encrypted value is called a digital signature. The client decrypts the encrypted value by the server’s public key and compares the value to its own computed value. If the two values match, the client can trust that the signature is authentic, because only the private key may possibly have been used to produce such a signature.
Digital certificates are used with the HTTPS protocol to authenticate web clients. The HTTPS service of most web servers will not run unless a digital certificate has been installed. Use the procedure outlined later to set up a digital certificate that can be used by your web server to enable SSL.
One tool that can be used to set up a digital certificate is keytool, a key and certificate management utility that ships with the J2SE SDK. It enables users to administer their own public/private key pairs and associated certificates for use in self-certification (where the user authenticates himself or herself to other users or services) or data integrity and certification services, by digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers. For a better understanding of keytool and public key cryptography, read the keytool documentation at the following URL:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/key-
tool.html
Making a Server Certificate
A server certificate has already been made for the Attention Server. The certificate can be found in the
If necessary, you can use keytool to generate certificates. The keytool stores the keys and certificates in a file termed a keystore, a repository of certificates used for identifying a client or a server. Typically, a keystore contains one client or one server’s identity. The defaulting keystore implementation implements the keystore as a file. It protects private keys by by a password.
The keystores are made in the directory from which you run keytool. This can be the directory where the attention resides, or it can be a directory common to many applications. If you don’t specify the keystore file name, the keystores are made in the user’s home directory.
To make a server certificate follow these steps:
1. Make the keystore.
2. Export the certificate from the keystore.
3. Sign the certificate.
4. Import the certificate into a trust-store: a repository of certificates used for verifying the certificates. A trust-store typically contains more than one certificate. An example by a trust-store for SSL-based mutual certification is discussed in Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC.
Run keytool to generate the server keystore, which we will name keystore.jks. This step uses the alias server-alias to generate a new public/private key pair and wrap the public key into a self-signed certificate inside keystore.jks. The key pair is generated by an algorithm of type RSA, with a defaulting password of changeit. For more information on keytool options, see its online help athttp://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.
________________________________________
Note: RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.
________________________________________
From the directory in which you want to make the keystore, run keytool with the following parameters.
1. Generate the server certificate.
-keyalg RSA -keypass changeit -storepass changeit
-keystore keystore.jks
When you press Enter, keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to keytool’sfirst prompt, in which it questions for first and last names. For hard purposes, this can be localhost. The host specified in the keystore must match the host identified in the host variable specified in the
2. Export the generated server certificate in keystore.jks into the file server.cer.
-storepass changeit -file server.cer -keystore keystore.jks
3. If you want to have the certificate signed by a CA, read Signing Digital Certificates for more information.
4. To make the trust-store file cacerts.jks and add the server certificate to the trust-store, run keytool from the directory where you made the keystore and server certificate. Use the following parameters:
-alias server-alias -file server.cer
-keystore cacerts.jks -keypass changeit
-storepass changeit
Information on the certificate, such as that shown next, will show.
-v -trustcacerts -alias server-alias -file server.cer
-keystore cacerts.jks -keypass changeit -storepass changeit
Owner: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=US
Issuer: CN=localhost, OU=Sun Micro, O=Docs, L=Santa Clara, ST=CA, C=US
Serial number: 3e932169
Valid from: Tue Apr 08
Certificate fingerprints:
MD5: 52:9F:49:68:ED:78:6F:39:87:F3:98:B3:6A:6B:0F:90
SHA1: EE:2E:2A:A6:9E:03:9A:3A:1C:17:4A:28:5E:97:20:78:3F:
Trust this certificate? [no]:
5. Enter yes, and then press the Enter or Return key. The following information displays:
Certificate was added to keystore
[Saving cacerts.jks]
Signing Digital Certificates
After you’ve made a digital certificate, you will want to have it signed by its owner. After the digital certificate has been cryptographically signed by its owner, it is hard for anyone else to forge. For sites involved in e-buying or any other business transaction in which certification of identity is vital, a certificate can be bought from a well-known certificate power such as VeriSign or Thawte.
As mentioned earlier, if certification is not really a concern, you can save the time and expense involved in obtaining a CA certificate and austerely use the self-signed certificate.
By a Different Server Certificate with the Attention Server
Follow the steps in Making a Server Certificate, to make your own server certificate, have it signed by a CA, and import the certificate into keystore.jks.
Make sure that when you make the certificate, you follow these rules:
• When you press make the server certificate, keytool prompts you to enter your first and last name. In response to this prompt, you must enter the name of your server. For hard purposes, this can belocalhost.
• The server/host specified in the keystore must match the host identified in the host variable specified in the
• Your key/certificate password in keystore.jks should match the password of your keystore, keystore.jks. This is a bug. If there is a mismatch, the Java SDK cannot read the certificate and you get a “tampered” message.
• If you want to replace the existing keystore.jks, you must any exchange your keystore’s password to the defaulting password (changeit) or exchange the defaulting password to your keystore’s password:
To specify that the Attention Server should use the new keystore for certification and consent decisions, you must set the JVM options for the Attention Server so that they recognize the new keystore. To use a different keystore than the one provided for development purposes, follow these steps.
1. Start the Attention Server if you haven’t already done so. Information on starting the Attention Server can be found in Starting and Stopping the Attention Server.
2. Start the Admin Console. Information on starting the Admin Console can be found in Starting the Admin Console.
3. Select Attention Server in the Admin Console tree.
4. Select the JVM Settings tab.
5. Select the JVM Options tab.
6. Exchange the following JVM options so that they top to the location and name of the new keystore. There current settings are shown not more than:
-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks
-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks
7. If you’ve changed the keystore password from its defaulting value, you need to add the password option as well:
-Djavax.net.ssl.keyStorePassword=your_new_password
8. Logout of the Admin Console and restart the Attention Server.
Making a Client Certificate for Mutual Certification
This section discusses setting up client-side certification. When both server-side and client-side certification are enabled, it is called mutual, or two-way, certification. In client certification, clients are required to submit certificates that are issued by a certificate power that you choose to accept. From the directory where you want to make the client certificate, run keytool as outlined here. When you press Enter,keytool prompts you to enter the server name, organizational unit, organization, locality, state, and country code.
________________________________________
Note: You must enter the server name in response to keytool’s first prompt, in which it questions for first and last names. For hard purposes, this can be localhost. The host specified in the keystore must match the host identified in the host variable specified in the
________________________________________
To make a keystore named client-keystore.jks that contains a client certificate named client.cer, follow these steps:
1. Generate the client certificate.
-storepass changeit -keystore keystore.jks
2. Export the generated client certificate into the file client.cer.
-storepass changeit -file client.cer -keystore keystore.jks
3. Add the certificate to the trust-store file
-alias client-alias -file client.cer
-keystore
-keypass changeit -storepass changeit
The keytool utility income this message:
Owner: CN=J2EE Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
Issuer: CN=J2EE Client, OU=Java Web Services, O=Sun, L=Santa Clara, ST=CA, C=US
Serial number: 3e39e66a
Valid from: Thu Jan 30 18:58:50 PST 2003 in anticipation of: Wed Apr 30
19:58:50 PDT 2003
Certificate fingerprints:
MD5: 5A:B0:4C:88:4E:F8:EF:E9:E5:8B:53:BD:D0:AA:8E:5A
SHA1:90:00:36:5B:E0:A7:A2:BD:67:DB:EA:37:B9:61:3E:26:B3:89:46:
32
Trust this certificate? [no]: yes
Certificate was added to keystore
For an example attention that uses mutual certification, see Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC. For information on verifying that mutual certification is running, seeVerifying That Mutual Certification Is Running.
Miscellaneous Orders for Certificates
To check the contents of a keystore that contains a certificate with an alias server-alias, use this command:
keytool -list -keystore keystore.jks -alias server-alias -v
To check the contents of the cacerts file, use this command:
keytool -list -keystore cacerts.jks
By SSL
An SSL connector is preconfigured for the Attention Server. You do not have to configure anything. If you are working with another attention server, see its documentation for setting up its SSL connector.
Verifying SSL Support
For hard purposes, and to verify that SSL support has been correctly installed, load the defaulting introduction page with a URL that connects to the port defined in the server deployment descriptor:
https://localhost:8181/
The https in this URL indicates that the browser should be by the SSL protocol. The localhost in this example assumes that you are running the example on your local machine as part of the development process. The 8181 in this example is the secure port that was specified where the SSL connector was made in By SSL. If you are by a different server or port, modify this value accordingly.
The first time a user loads this attention, the New Site Certificate or Security Alert dialog box displays. Select Next to go through the series of dialog boxes, and select End when you reach the last dialog box. The certificates will show only the first time. When you accept the certificates, later hits to this site assume that you still trust the make pleased.
Tips on Running SSL
The SSL protocol is designed to be as well-organized as securely possible. But, encryption and decryption are computationally expensive processes from a performance standpoint. It is not strictly necessary to run an entire web attention over SSL, and it is customary for a developer to choose which pages require a secure connection and which do not. Pages that force require a secure connection include login pages, personal information pages, shopping cart checkouts, or any pages where credit card information may possibly possibly be transmitted. Any page within an attention can be requested over a secure socket by austerely prefixing the address with https: instead of http:. Any pages that absolutely require a secure connection should check the protocol type associated with the page request and take the appropriate action if https: is not specified.
By name-based virtual hosts on a secured connection can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined before certification, and it is therefore not possible to assign multiple certificates to a single IP address. If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts should not interfere with normal SSL operations on the server. Be aware, but, that most client browsers will equate the server’s domain name against the domain name listed in the certificate, if any (this is applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers will show a warning to the client. In general, only address-based virtual hosts are commonly used with SSL in a production environment.
Enabling Mutual Certification over SSL
This section discusses setting up client-side certification. As mentioned earlier, when both server-side and client-side certification are enabled, it is called mutual, or two-way, certification. In client certification, clients are required to submit certificates that are issued by a certificate power that you choose to accept. If you regulate it through the attention (via the Client-Certificate certification requirement), the check is performed when the attention requires client certification. You must enter the keystore location and password in the web server configuration file to enable SSL, as discussed in By SSL.
Here are two ways to enable mutual certification over SSL:
• PREFERRED: Set the method of certification to Client-Certificate by deploytool. This enforces mutual certification by modifying the deployment descriptor of the given attention. By enabling client certification in this way, client certification is enabled only for a point store controlled by the security constraint. Setting client certification in this way is discussed in Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC.
• RARELY: Set the clientAuth property in the certificate realm to right. To do this, follow these steps:
a. Start the Attention Server if you haven’t already done so. Information on starting the Attention Server can be found in Starting and Stopping the Attention Server.
b. Start the Admin Console. Information on starting the Admin Console can be found in Starting the Admin Console.
c. In the Admin Console tree, expand Configuration, expand Security, then expand Realms, and then select certificate. The certificate realm is used for all transfers over HTTP with SSL.
d. Select Add to add the property of clientAuth to the server. Enter clientAuth in the Name field, and enter right in the Value field.
e. Click Save to save these new properties.
f. Log out of the Admin Console.
When client certification is enabled in both of these ways, client certification will be performed twice.
Verifying That Mutual Certification Is Running
You can verify that mutual certification is working by obtaining debug messages. This should be done at the client end, and this example shows how to pass a system property in targets.xml so thattargets.xml forks a client with javax.net.debug in its system properties, which may possibly be added in a file such as
To enable debug messages for SSL mutual certification, pass the system property javax.net.debug=ssl,handshake, which will provide information on whether or not mutual certification is working. The following example modifies the run-mutualauth-client target from the
SSL”>
XML and Web Services Security
Security can be applied to web services at both the transport-level and the message-level.
In message security, security information travels along with the web services message. WSS in the SOAP layer is the use of XML Encryption and XML Digital Signatures to secure SOAP messages. WSS profiles the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to achieve this.
Message layer security differs from transport layer security in that message layer security can be used to decouple message protection from message transport so that messages wait protected after transmission, regardless of how many hops they travel on.
Message-level security is discussed in the following documentation:
• Configuring Message Security chapter of the Attention Server Administration Guide. This chapter is for system administrators or others attempting to set up the Attention Server for message security.
• Securing Applications chapter of the Attention Server Developers’ Guide. This chapter is for developers, assemblers, and deployers attempting to implement message security at the attention or method level.
Transport-level security is discussed in the following example sections:
• Transport-Level Security
• Example: Basic Certification with JAX-RPC
• Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC
Transport-Level Security
Certification verifies the identity of a user, device, or other being in a computer system, usually as a prerequisite to allowing access to resources in a system. There are several ways in which this can happen. The following ways are discussed in this section:
One deal with is that a user certification method can be defined for an attention in its deployment descriptor. When a user certification method is specified for an attention, the web container activates the specified certification mechanism when you attempt to access a protected store. The options for user certification methods are discussed in Understanding Login Certification. The example attention discussed in Example: Basic Certification with JAX-RPC shows how to add basic certification to a JAX-RPC attention. The example discussed in Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC shows how to add client-certificate, or mutual, certification to a JAX-RPC attention.
A second deal with is that a transport guarantee can be defined for an attention in its deployment descriptor. Use this method to run over an SSL-protected session and ensure that all message make pleased is protected for confidentiality. The options for transport guarantees are discussed in Specifying a Secure Connection. For an example attention that demonstrates running over an SSL-protected session, seeExample: Client-Certificate Certification over HTTP/SSL with JAX-RPC.
When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the attention protocol transmits or receives its first byte of data.
SSL technology allows web browsers and web servers to communicate over a secure connection. In this secure connection, the data is encrypted before being sent, and then is decrypted upon receipt and before processing. Both the browser and the server encrypt all traffic before carriage any data. For more information, see What Is Secure Socket Layer Technology?.
Digital certificates are necessary when running HTTP over SSL (HTTPS). The HTTPS service of most web servers will not run unless a digital certificate has been installed. Digital certificates have already been made for the Attention Server.
Example: Basic Certification with JAX-RPC
In this section, we discuss how to configure JAX-RPC-based web service applications for HTTP basic certification. With HTTP basic certification, the web server authenticates a user by by the user name and password obtained from the web client. If the topic of certification is new to you, delight refer to the section titled Understanding Login Certification. For an explanation of how basic certification works, seeFigure 32-2.
For this tutorial, we start with the example attention in
In general, the following steps are necessary to add basic certification to a JAX-RPC attention. In the example attention built-in with this tutorial, many of these steps have been completed for you and are listed here to show what needs to be done should you wish to make a similar attention.
1. Complete the JAX-RPC attention as described in Making a Simple Web Service and Client with JAX-RPC.
2. If the defaulting port value is changed from 8080, see Setting the Port for information on updating the example files to reflect this exchange. The WAR files mentioned in this tutorial will not work if the port has been changed.
3. Edit the
4. Add a user with the name that matches the value set in the build.properties file (admin) for the admin.user property and a password that matches the value set in the admin-password.txt file for theAS_ADMIN_PASSWORD property to the file realm. Refer to the section Managing Users, for instructions for doing this.
5. Set security properties in the client code. For the example attention, this step has been completed. The code for this example is shown in Setting Security Properties in the Client Code.
6. Add the appropriate security elements by deploytool. For this example, the security elements are added in the packaging and deployment phase. Refer to Adding Basic Certification By deploytoolfor more information.
7. Build, package, install, and run the web service. You will use the asant tool to compile the client and service, and deploytool to package and install the service. Instructions for this example can be found inBuilding, Packaging, Deploying, and Running the Example for Basic Certification.
Setting Security Properties in the Client Code
The source code for the client is in the HelloClient.java file of the
The client sets the aforementioned security properties as shown in the following code. The code in bold is the code that has been added from the original version of the jaxrpc/staticstub example attention.
package basicauthclient;
import javax.xml.rpc.Stub;
public class HelloClient {
public static void main(String[] args) {
if (args.length !=3) {
System.out.println(“HelloClient Error: Incorrect
number of runtime arguments!”);
System.exit(1);
}
String username=args[0];
String password=args[1];
String endpointAddress=args[2];
// print to show for verification purposes
System.out.println(“username: ” + username);
System.out.println(“password: ” + password);
System.out.println(“Endpoint address = ” +
endpointAddress);
try {
Stub stub = createProxy();
stub._setProperty(
javax.xml.rpc.Stub.USERNAME_PROPERTY,
username);
stub._setProperty(
javax.xml.rpc.Stub.PASSWORD_PROPERTY,
password);
stub._setProperty
(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
endpointAddress);
HelloIF hello = (HelloIF)stub;
System.out.println(hello.sayHello(“Duke (secure)”));
} catch (Exception ex) {
ex.printStackTrace();
}
}
private static Stub createProxy() {
// Note: MyHelloService_Impl is implementation-point.
return (Stub)(new
MyHelloService_Impl().getHelloIFPort());
}
}
Read Static Stub Client for more information about JAX-RPC static stub clients.
Building, Packaging, Deploying, and Running the Example for Basic Certification
To build, package, install, and run the security/basicauth example by basic certification, follow these steps.
Building the Basic Certification Service
1. Set up your system for running the tutorial examples if you haven’t done so already by following the instructions in Building the Examples.
2. From a terminal window or command prompt, go to the
3. Build the JAX-RPC service by entering the following at the terminal window or command prompt in the basicauth/ directory (this and the following steps that use asant assume that you have the executable for asant in your path; if not, you will need to provide the fully qualified path to the executable). This command runs the target named build in the build.xml file.
asant build
Packaging the Basic Certification Service
You can package the basic certification example by asant or deploytool, or you can just open the WAR file located in the
To package the example by asant, run the following command from the /basicauth directory:
asant make-war
To package the example by deploytool, follow the steps described in Packaging and Deploying the Service with deploytool and Specifying the Endpoint Address. When following these steps, replace the following:
• The path to the example should be replaced with
• Replace helloservice with basicauth throughout.
• Use /basicauth-jaxrpc for the Context Root field.
Adding Basic Certification By deploytool
For HTTP basic certification, the attention deployment descriptor, web.xml, includes the information on who is authorized to access the attention, which URL patterns and HTTP methods are protected, and what type of user certification method this attention uses. This information is added to the deployment descriptor by deploytool. Its contents are discussed in more detail in Web-Tier Security and in the Java Servlet specification, which can be browsed or downloaded online at http://java.sun.com/harvest/servlet/.
1. If you packaged the example by deploytool, select the basic certification example, BasicAuth, in the deploytool tree. If you packaged the example by asant, open the generated WAR file (basicauth.war) in deploytool and then select the basic certification example.
2. Select the Security tabbed pane.
3. Select Basic in the User Certification Method field.
4. Select Add Constraints to add a security constraint.
5. Select Add Collections to add a web store collection.
6. Select the web store collection from the list, and then select Edit Collections.
7. Select Add URL Pattern. Enter /hello in the text field. Click OK.
8. Select the HTTP GET and POST methods.
9. Click OK to close the Edit Contents dialog box.
10. Select Edit Roles on the Security tabbed pane to specify an authorized role for this attention.
11. Click Edit Roles in the Authorized Roles dialog box to add an authorized user to this attention. Click Add in the Edit Roles dialog box and add the Name of admin. Click OK to close this dialog box.
12. Select admin under the Roles In field, and then click Add to add it to the list of authorized roles for this attention. Click OK to close the dialog box.
Note that the Authorized Roles list specifies admin, a assemble that was specified during installation. To map this role to a user, follow these steps.
1. Select the General tabbed pane.
2. Click the Sun-point Settings button.
3. In the Sun-point Settings dialog box, select User to Role Mappings from the View list.
4. Select admin from the list of roles.
5. Click the Edit button under the Users box.
6. Select admin from the Available Users list, and then click the Add button to map the role of admin (defined for the attention) to the user named admin (defined for the Attention Server). Click OK.
________________________________________
Note: If you don’t see the list of users or groups that you defined by the Admin Console, connect to the Admin Server by double-clicking localhost:4848 in the deploytool tree and entering your admin user name and password. If this is not the current target server, exchange to this server by selecting it and then selecting File Set Current Target Server.
________________________________________
1. Click Close to return to the General tabbed pane.
2. Select Save from the File menu to save these settings.
Deploying the Basic Certification Service
To install the example by asant, run the following command:
asant install-war
To install the example by deploytool, follow these steps:
1. Select the BasicAuth attention in the deploytool tree. Then select Tools Install.
2. Make sure the server is right, localhost:4848 by defaulting.
3. Enter your admin user name and password.
4. Click OK.
5. Click the Close button after the messages indicating successful completion are finished.
You can view the WSDL file of the deployed service by requesting the URL http://localhost:8080/basicauth-jaxrpc/hello?WSDL in a web browser.
Building and Running the Basic Certification Client
To build the JAX-RPC client, do the following:
1. Enter the following command at the terminal window or command prompt in the basicauthclient/ directory:
asant build
2. Run the JAX-RPC client by entering the following at the terminal window or command prompt in the basicauthclient/ directory:
asant run
The client should show the following productivity:
Buildfile: build.xml
run-secure-client:
[java] username: your_name
[java] password: your_pwd
[java] Endpoint address = http://localhost:8080/basicauth-
jaxrpc/hello
[java] Hello Duke (secure)
BUILD SUCCESSFUL
Example: Client-Certificate Certification over HTTP/SSL with JAX-RPC
In this section, we discuss how to configure a simple JAX-RPC-based web service attention for client-certificate certification over HTTP/SSL. Client-certificate certification uses HTTP over SSL, in which the server and, optionally, the client authenticate one another by public key certificates. If the topic of certification is new to you, delight refer to the section titled Understanding Login Certification. For more information on how client-certificate certification works, see Map 32-4.
This example attention starts with the example attention in
To add mutual certification to a basic JAX-RPC service, complete the following steps. In the example attention built-in with this tutorial, many of these steps have been completed for you and are listed here to show what needs to be done should you wish to make a similar attention.
1. Complete the JAX-RPC attention as described in Making a Simple Web Service and Client with JAX-RPC.
2. Make the appropriate certificates and keystores. For this example, the certificates and keystores are made for the server as a generic localhost and are built-in with the Attention Server. See the section Keystores and Trust-Stores in the Mutual Certification Example for a discussion of how to make the client certificates for this example.
3. If the port value is changed from the defaulting of localhost:8080, see Setting the Port for information on updating the example files to reflect this exchange. The WAR files mentioned in this tutorial will not work if the port has been changed.
4. Edit the build.properties files to add the location and password to the trust-store, and other properties, as appropriate. For a discussion of the modifications that need to be made to build.properties, see Modifying the Build Properties. While you are looking at this file, note the value entered for admin.user. Also note the value for the admin password as specified in the file admin-password.txt in the field AS_ADMIN_PASSWORD.
5. Add a user to the file realm with the name that matches the value set in the build.properties file (admin) for the admin.user property and a password that matches the value set in the admin-password.txt file for the AS_ADMIN_PASSWORD property. Refer to the section Managing Users, for instructions for doing this.
6. Set security properties in the client code. For the example attention, this step has been completed. For a discussion of the security properties that have been set in HelloClient, see Setting Security Properties in the Client Code.
7. Add the appropriate security elements by deploytool. The security elements are discussed in the section Enabling Client-Certificate Certification for the Mutual Certification Example.
8. Build, package, and install the service, install the server, and then build and run the client (see Building, Packaging, Deploying, and Running the Mutual Certification Example). You will use the asant tool to compile the client and service and to run the client. You will use deploytool to package and install the service.
Keystores and Trust-Stores in the Mutual Certification Example
In this example, the keystore file (keystore.jks) and the trust-store file (cacerts.jks) have been made for the server as a generic localhost and are built-in with the Attention Server in the directory
Modifying the Build Properties
To build and run the attention with mutual certification, we have set up the example so that some of the values are passed to the attention from various build.properties files.
To run any of the examples, you must modify the build.properties file located in the
For this example, the build.properties file that is point to this attention,
Make sure that the following properties exist and are correctly defined.
trust.store=${j2ee.home}/domains/domain1/config/cacerts.jks
trust.store.password=changeit
key.store=${j2ee.home}/domains/domain1/config/keystore.jks
key.store.password=changeit
Setting Security Properties in the Client Code
The source code for the client is in the HelloClient.java file of the
• trustStore: The value of the trustStore property is the fully qualified name of the trust-store file:
• trustStorePassword: The trustStorePassword property is the password of the trust-store. The defaulting value of this password is changeit.
• keyStore: The value of the keyStore property is the fully qualified name of the keystore file:
• keyStorePassword: The keyStorePassword property is the password of the keystore. The defaulting value of this password is changeit.
• ENDPOINT_ADDRESS_PROPERTY: The ENDPOINT_ADDRESS_PROPERTY property sets the endpoint address that the stub uses to access the service.
The client sets the aforementioned security properties as shown in the following code. The code in bold is the code that has been added from the original version of the jaxrpc/staticstub example attention.
package mutualauthclient;
import javax.xml.rpc.Stub;
public class HelloClient {
public static void main(String[] args) {
if (args.length !=5) {
System.out.println(“HelloClient Error: Need 5
runtime arguments!”);
System.exit(1);
}
String keyStore=args[0];
String keyStorePassword=args[1];
String trustStore=args[2];
String trustStorePassword=args[3];
String endpointAddress=args[4];
// print to show for verification purposes
System.out.println(“keystore: ” + keyStore);
System.out.println(“keystorePassword: ” +
keyStorePassword);
System.out.println(“trustStore: ” + trustStore);
System.out.println(“trustStorePassword: ” +
trustStorePassword);
System.out.println(“Endpoint address: ” +
endpointAddress);
try {
Stub stub = createProxy();
System.setProperty(“javax.net.ssl.keyStore”,
keyStore);
System.setProperty(“javax.net.ssl.keyStorePassword”,
keyStorePassword);
System.setProperty(“javax.net.ssl.trustStore”,
trustStore);
System.setProperty(“javax.net.ssl.trustStorePassword”,
trustStorePassword);
stub._setProperty(
javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
endpointAddress);
HelloIF hello = (HelloIF)stub;
System.out.println(hello.sayHello(“Duke! ( secure!”));
} catch (Exception ex) {
ex.printStackTrace();
}
}
private static Stub createProxy() {
// Note: MyHelloService_Impl is implementation-point.
return (Stub)(new
MySecureHelloService_Impl().getHelloIFPort());
}
}
Enabling Client-Certificate Certification for the Mutual Certification Example
The two ways of implementing client certification are discussed in Enabling Mutual Certification over SSL. You can set client certification for all applications (by specifying this in the deployment descriptor for the server) or for only a single attention (by specifying this in the deployment descriptor for the attention). For this example, we are enabling client certification for this attention only, so we specify the login certification method as being Client-Certificate. The steps for adding client-certificate certification are shown in Adding Client-Certificate Certification By deploytool.
For more information on login configuration options, read Understanding Login Certification.
The user certification method specifies a client-certificate method of certification in this example. For this certification to run over SSL, you must also specify which type of transport guarantee to use. For this example, we have chosen CONFIDENTIAL, which is specified in the Network Security Requirement field on the Security tabbed pane in deploytool.
For more information on this type of constraint, read Specifying a Secure Connection.
Building, Packaging, Deploying, and Running the Mutual Certification Example
To build, install, and run the JAX-RPC service example with mutual certification, follow these steps.
Building the Mutual Certification Example
To compile the attention files and copy them to the right directories, run the asant build task. More information on what happens when the build task is called can be found in Building the Service.
1. If you haven’t already done so, follow these steps for setting up the example.
o By SSL
o Building the Examples
2. Go to the
3. Build the JAX-RPC service by entering the following at the terminal window or command prompt in the mutualauth/ directory (this and the following steps that use asant assume that you have the executable for asant in your path; if not, you will need to provide the fully qualified path to the asant executable):
asant build
4. Exchange to the directory
5. Build the JAX-RPC client by entering the following at the terminal window or command prompt:
asant build
Packaging the Mutual Certification Example
You can package the mutual certification example by asant or deploytool, or you can open the WAR file located in the
To package the example by asant, run the following command and then skip to the section titled Deploying the Mutual Certification Example:
asant make-war
To package the example by deploytool, follow the steps described in Packaging and Deploying the Service with deploytool and Specifying the Endpoint Address. When following these steps, replace the following:
• The path to the example should be replaced with
• Replace helloservice with mutualauth throughout.
• Use /mutualauth-jaxrpc for the Context Root field.
Adding Client-Certificate Certification By deploytool
For HTTP client-certificate certification, the attention deployment descriptor, web.xml, includes the information on who is authorized to access the attention, which URL patterns and HTTP methods are protected, and what type of user certification method this attention uses. This information is added to the deployment descriptor by deploytool, and its contents are discussed in more detail in Web-Tier Security and in the Java Servlet specification, which can be browsed or downloaded online at http://java.sun.com/harvest/servlet/.
1. If you packaged the example by deploytool, select the MutualAuth example in the deploytool tree. If you packaged the example by asant, you can ignore this section as these steps were completed by the asant task.
2. Select the Security tabbed pane.
3. Select Client Certificate in the User Certification Method field.
4. Select Add Constraints to add a security constraint.
5. Select Add Collections to add a web store collection.
6. Select the web store collection from the list, and then select Edit Collections.
7. Select Add URL Pattern. Enter /hello in the text field. Click OK.
8. Select the HTTP GET and POST methods.
9. Click OK to close the Edit Contents dialog box.
10. Select CONFIDENTIAL under Network Security Requirement so that the attention requires HTTP/SSL.
11. Select Save from the File menu to save these settings.
Deploying the Mutual Certification Example
To install the example by asant, run the following command:
asant install-war
To install the attention by deploytool, follow these steps:
1. Install the JAX-RPC service by selecting the MutualAuth example in the deploytool tree. Then select Tools Install.
2. Make sure the server is right. By defaulting, this will be localhost:4848.
3. Enter your admin user name and password.
4. Click OK.
5. Click the Close button after the messages indicating successful completion are finished.
Running the Mutual Certification Example
Enter the following command from the mutualauthclient/ directory at the terminal window or command prompt to run the JAX-RPC client:
asant run
The client should show the following productivity:
Buildfile: build.xml
run-mutualauth-client:
[java] keystore:
keystore.jks
[java] keystorePassword: changeit
[java] trustStore:
cacerts.jks
[java] trustStorePassword: changeit
[java] Endpoint address = https://localhost:8181/
mutualauth-jaxrpc/hello
[java] Hello Duke (secure)
run:
BUILD SUCCESSFUL
Check it out:System Engineer – IT Administration
Answers Rating