test

Sun GlassFish Enterprise Server v3 Prelude Administration Guide

Chapter 6 Administering System Security

This chapter provides instructions for administering system security in the Sun GlassFishTM Enterprise Server v3 Prelude environment by using the asadmin and keytool command-line utilities.

The following topics are addressed here:

Instructions for accomplishing many of these tasks by using the Administration Console are contained in the Administration Console online help.

Additional information on security is contained in Chapter 7, Administering User Security.

About Enterprise Server Security

Security is about protecting data, that is, how to prevent unauthorized access or damage to data that is in storage or in transit. The Enterprise Server is built on the Java security model, which uses a sandbox where applications can run safely, without potential risk to systems or users. System security affects all the applications in the Enterprise Server environment.

System security features include the following:

Authentication

Authentication is the way in which an entity (a user, an application, or a component) determines that another entity is who it claims to be. An entity uses security credentials to authenticate itself. The credentials might be a user name and password, a digital certificate, or something else. Usually, servers or applications require clients to authenticate themselves. Additionally, clients might require servers to authenticate themselves. When authentication is bidirectional, it is called mutual authentication.

When an entity tries to access a protected resource, Enterprise Server uses the authentication mechanism configured for that resource to determine whether to grant access. For example, a user can enter a user name and password in a web browser, and if the application verifies those credentials, the user is authenticated. The user is associated with this authenticated security identity for the remainder of the session.

Authentication Types

Within its deployment descriptors, an application specifies the type of authentication that it uses. Enterprise Server supports the following types of authentication:

BASIC

Uses the server's built-in login dialog box. The communication protocol is HTTP (SSL optional). There is no user-credentialed encryption unless using SSL.

FORM

The application provides its own custom login and error pages. The communication protocol is HTTP (SSL optional). There is no user-credentialed encryption unless using SSL.

CLIENT-CERT

The server authenticates the client using a public key certificate. The communication protocol is HTTPS (HTTP over SSL). User-credentialed encryption is SSL.

Passwords

Passwords are your first line of defense against unauthorized access to the components and data of Enterprise Server. For information on how to use passwords for Enterprise Server, see Administering Passwords.

Administration Password

The administration password, also known as the admin password, is used to invoke the Administration Console and the asadmin utility. This password is usually set during installation, but it can be changed. For instructions, see To Change the Administration Password.

Encoded Passwords

Files that contain encoded passwords need to be protected using file system permissions. These files include the following:

For instructions, see To Set a Password From a File.

Single Sign-on

With single sign-on, a user who logs in to one application becomes implicitly logged in to other applications that require the same authentication information. Single sign-on is based on groups. All web applications whose deployment descriptor defines the same group and uses the same authentication method (BASIC, FORM, or CLIENT-CERT) share single sign-on.

On Enterprise Server, single sign-on is enabled by default for virtual servers, allowing multiple applications in one virtual server to share the user authentication state.

Authorization

Authorization, also known as access control, is the means by which users are granted permission to access data or perform operations. After a user is authenticated, the user's level of authorization determines what operations the owner can perform. A user's authorization is based on the user's role.

Roles

A role defines which applications and what parts of each application users can access and what those users or groups can do with the applications. For example, in a personnel application, all employees might be able to see phone numbers and email addresses, but only managers have access to salary information. This application would define at least two roles: employee and manager. Only users in the manager role are allowed to view salary information.

A role is different from a group in that a role defines a function in an application, while a group is a set of users who are related in some way. For example, the personnel application specify groups such as full-time, part-time, and on-leave. Users in these groups are all employees (the employee role). In addition, each user has its own designation that defines an additional level of employment.

Roles are defined in the deployment descriptor for the application. The application developer or deployer maps roles to one or more groups in the deployment descriptor for each application. When the application is being packaged and deployed, the application specifies mappings between users, groups, and roles, as illustrated in the following figure.

Figure 6–1 Role Mapping

Figure shows how users are assigned to groups, how users and groups are assigned to roles, and how applications use groups and roles.

Java Authorization Contract for Containers

Java Authorization Contract for Containers (JACC) is the part of the Java EE specification that defines an interface for pluggable authorization providers. This enables you to set up third-party plug-in modules to perform authorization. By default, the Enterprise Server provides a simple, file-based authorization engine that complies with the JACC specification. You can also specify additional third-party JACC providers.

JACC providers use the Java Authentication and Authorization Service (JAAS) APIs. JAAS enables services to authenticate and enforce access controls upon users. JAAS implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework.

Auditing

Auditing is the means used to capture security-related events for the purpose of evaluating the effectiveness of security measures. Enterprise Server uses audit modules to capture audit trails of all authentication and authorization decisions. Enterprise Server provides a default audit module, as well as the ability to customize the audit modules.

For administration instructions, see Administering Audit Modules.

Firewalls

A firewall controls the flow of data between two or more networks, and manages the links between the networks. A firewall can consist of both hardware and software elements. The following guidelines pertain primarily to Enterprise Server:

Certificates and SSL

The following topics are addressed here:

For administration instructions, see Administering JSSE Certificates .

Certificates

Certificates, also called digital certificates, are electronic files that uniquely identify people and resources on the Internet. Certificates also enable secure, confidential communication between two entities. There are different kinds of certificates:

Certificates are based on public key cryptography, which uses pairs of digital keys (very long numbers) to encrypt, or encode, information so the information can be read only by its intended recipient. The recipient then decrypts (decodes) the information to read it. A key pair contains a public key and a private key. The owner distributes the public key and makes it available to anyone. But the owner never distributes the private key, which is always kept secret. Because the keys are mathematically related, data encrypted with one key can only be decrypted with the other key in the pair.

Certificates are issued by a trusted third party called a Certification Authority (CA). The CA is analogous to a passport office: it validates the certificate holder's identity and signs the certificate so that it cannot be forged or tampered with. After a CA has signed a certificate, the holder can present it as proof of identity and to establish encrypted, confidential communications. Most importantly, a certificate binds the owner's public key to the owner's identity.

In addition to the public key, a certificate typically includes information such as the following:

Certificates are governed by the technical specifications of the X.509 format. To verify the identity of a user in the certificate realm, the authentication service verifies an X.509 certificate, using the common name field of the X.509 certificate as the principal name.

Certificate Chains

A certificate chain is a series of certificates issued by successive CA certificates, eventually ending in a root CA certificate.

Web browsers are preconfigured with a set of root CA certificates that the browser automatically trusts. Any certificates from elsewhere must come with a certificate chain to verify their validity.

Certificate Files

During Enterprise Server installation, a certificate is generated in Java Secure Socket Extension (JSSE) format suitable for internal testing. By default, Enterprise Server stores its certificate information in certificate databases in the domain-dir/config directory:

Keystore file

The key3.db file contains Enterprise Server certificate, including its private key. The keystore file is protected with a password.

Each keystore entry has a unique alias. After installation, the Enterprise Server keystore has a single entry with an alias of s1as.

Truststore file

The cert8.db file contains the Enterprise Server trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate's owner. Trusted certificates generally include those of CAs.

By default, Enterprise Server is configured with a keystore and truststore that will work with the example applications and for development purposes.

Secure Sockets Layer

Secure Sockets Layer (SSL) is the most popular standard for securing Internet communications and transactions. Secure web applications use HTTPS (HTTP over SSL). The HTTPS protocol uses certificates to ensure confidential and secure communications between server and clients. In an SSL connection, both the client and the server encrypt data before sending it. Data is decrypted upon receipt.

The newest version of the SSL standard is called Transport Layer Security (TLS). The Enterprise Server supports the SSL 3.0 and the TLS 1.0 encryption protocols.

To use SSL, Enterprise Server must have a certificate for each external interface or IP address that accepts secure connections. The HTTPS service of most web servers will not run unless a certificate has been installed.

Ciphers

A cipher is a cryptographic algorithm used for encryption or decryption. SSL and TLS protocols support a variety of ciphers used to authenticate the server and client to each other, transmit certificates, and establish session keys.

Some ciphers are stronger and more secure than others. Clients and servers can support different cipher suites. During a secure connection, the client and the server agree to use the strongest cipher that they both have enabled for communication, so it is usually sufficient to enable all ciphers.

Application Security

Unlike system security, which affects all the applications on Enterprise Server, Application security affects a particular application. There are basically two types of application security: programmatic and declarative.

Information on application security is contained in the Chapter 4, Securing Applications, in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.

Tools for Managing System Security

Enterprise Server provides the following tools for managing system security:

Administration Console

The Administration Console is a browser-based utility used to configure security for the entire server. Tasks include managing certificates, users, groups, and realms, and performing other system-wide security tasks. For a general introduction to the Administration Console, see Administration Console.

The asadmin utility

The asadmin command-line utility performs many of the same tasks as the Administration Console. You might be able to do some things with the asadmin utility that you cannot do with the Administration Console. For a general introduction to asadmin, see Command-Line Utility for Administration (asadmin).

The keytool utility

The keytool Java 2 Platform, Standard Edition (J2SE) command-line utility is used for managing digital certificates and key pairs. For more information, see Administering JSSE Certificates .

The policytool utility

The policytool J2SE graphical utility is used for managing system-wide Java security policies. As an administrator, you rarely use policytool.

For more information on using keytool, policytool, and other Java security tools, see Java 2 SDK Tools and Utilities at http://java.sun.com/j2se/1.4.2/docs/tooldocs/tools.html#security.

Administering Passwords

There are multiple ways to administer passwords. You can rely on administrators to keep passwords secret and change the passwords regularly. You can set up files for storing passwords so that asadmin commands can access these files rather than having users type the commands.

The following topics are addressed here:

ProcedureTo Change the Administration Password

The remote change-admin-password command allows you to change the administration password. You are prompted for the old and new admin passwords, with confirmation.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Change the admin password by using the change-admin-password(1) command.

  3. Enter the old and new admin password as prompted.

Example 6–1 Changing the Admin Password

The following example changes the admin password for user anonymous from adminadmin to newadmin:


asadmin change-admin-password --user anonymous

Information similar to the following is displayed:


Enter admin password>adminadmin
Enter new admin password>newadmin
Enter new admin password again>newadmin
Command change-admin-password executed successfully.
See Also

To see the full syntax and options of the command, type asadmin change-admin-password --help at the command line.

ProcedureTo Set a Password From a File

Instead of typing the password at the command line, you can access the password for a command from a file such as passwords.txt. The --passwordfile option of the asadmin utility takes the name of the file that contains the passwords. The entry for a password in the file must have the AS_ADMIN_ prefix followed by the password name in uppercase letters.

The following other types of passwords can be specified: 


AS_ADMIN_MASTERPASSWORD
AS_ADMIN_USERPASSWORD
AS_ADMIN_ALIASPASSWORD

  1. Edit the password file.

    For example, to specify the password for the domain administration server (DAS), add an entry similar to the following to the password file, where adminadmin is the administrator password:

    AS_ADMIN_PASSWORD=adminadmin

  2. Save the password file.

  3. Specify the password file in an asadmin command.

    For example:


    asadmin delete-jdbc-resource --user admin --password passwords.file jdbc/DerbyPool
Troubleshooting

If AS_ADMIN_PASSWORD has been exported to the global environment, specifying the --passwordfile option will produce a warning about using the --passwordfile option. To prevent this warning situation from happening, unset AS_ADMIN_PASSWORD.

Administering Audit Modules

The following topics are addressed here:

ProcedureTo Create an Audit Module

The remote create-audit-module command enables you to create an audit module for the add-on component that implements the audit capabilities.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Create an audit module by using the create-audit-module(1) command.

Example 6–2 Creating an Audit Module

The following example command creates an audit module named sampleAuditModule on localhost:


asadmin create-audit-module 
--classname com.sun.appserv.auditmodule --property defaultuser=
admin:Password=admin sampleAuditModule

Information similar to the following is displayed:


Creation of AuditModule sampleAuditModule completed successfully

Command create-audit-module executed successfully.

ProcedureTo List Audit Modules

The remote list-audit-modules command enables you to list the audit modules on one of the following targets:

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. List the audit modules by using the list-audit-modules(1) command.

Example 6–3 Listing Audit Modules

The following example command lists the audit modules on localhost:


asadmin list-audit-modules

Information similar to the following is displayed:


audit-module : default
audit-module : sampleAuditModule
Command list-audit-modules executed successfully.

ProcedureTo Delete an Audit Module

The remote delete-audit-module command allows you to delete an existing audit module.

  1. Ensure that the server is running.

    Remote commands require a running server.

  2. Delete an audit module by using the delete-audit-module(1) command.

Example 6–4 Deleting an Audit Module

The following example command deletes sampleAuditModule from localhost:


asadmin delete-audit-module sampleAuditModule

Information similar to the following is displayed:


Deletion of Audit Module sampleAuditModule completed successfully

Command delete-audit-module executed successfully.

Administering JSSE Certificates

The J2SE SDK ships with the keytool utility, which enables you to set up and work with Java Secure Socket Extension (JSSE) digital certificates. You can administer public/private key pairs and associated certificates, and cache the public keys (in the form of certificates) of their communicating peers.

The following topics are addressed here:

ProcedureTo Generate a Certificate by Using keytool

By default, the keytool utility creates a keystore file in the directory where the utility is run.

Before You Begin

To run the keytool utility, your shell environment must be configured so that the J2SE /bin directory is in the path, otherwise the full path to the utility must be present on the command line.

  1. Change to the directory that contains the keystore and truststore files.

    Always generate the certificate in the directory containing the keystore and truststore files. The default is domain-dir/config.

  2. Generate the certificate in the keystore file, keystore.jks, using the following command format:


    keytool -genkey -alias keyAlias-keyalg RSA
 -keypass changeit
 -storepass changeit
keystore keystore.jks

    Use any unique name as your keyAlias. If you have changed the keystore or private key password from the default (changeit), substitute the new password for changeit. The default key password alias is s1as.

    A prompt appears that asks for your name, organization, and other information.

  3. Export the generated certificate to the server.cer file (or client.cer if you prefer), using the following command format:


    keytool -export -alias keyAlias-storepass changeit
 -file server.cer
 -keystore keystore.jks

  4. If a certificate signed by a certificate authority is required, see To Sign a Certificate by Using keytool.

  5. Create the cacerts.jks truststore file and add the certificate to the truststore, using the following command format:


    keytool -import -v -trustcacerts
-alias keyAlias
 -file server.cer
-keystore cacerts.jks
 -keypass changeit

    If you have changed the keystore or private key password from the default (changeit), substitute the new password.

    Information about the certificate is displayed and a prompt appears asking if you want to trust the certificate.

  6. Type yes, then press Enter.

    Information similar to the following is displayed:


    Certificate was added to keystore
[Saving cacerts.jks]

  7. To apply your changes, restart Enterprise Server.

    1. Stop Enterprise Server.

      For instructions, see To Stop a Domain (or Server).

    2. Start Enterprise Server.

      For instructions, see To Start a Domain (or Server).

Example 6–5 Creating a Self-Signed Certificate in a JKS Keystore by Using an RSA Key Algorithm

RSA is public-key encryption technology developed by RSA Data Security, Inc.


keytool  -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias} 
-dname  ${dn.name} -keypass ${key.pass} -keystore ${keystore.file} 
-storepass ${keystore.pass}
Example 6–6 Creating a Self-Signed Certificate in a JKS Keystore by Using a Default Key Algorithm


keytool -genkey -noprompt -trustcacerts -alias ${cert.alias} -dname  
${dn.name} -keypass ${key.pass} -keystore ${keystore.file} -storepass 
${keystore.pass}
Example 6–7 Displaying Available Certificates From a JKS Keystore


keytool -list -v  -keystore ${keystore.file} -storepass ${keystore.pass}
Example 6–8 Displaying Certificate information From a JKS Keystore


keytool -list -v  -alias ${cert.alias} -keystore ${keystore.file} 
-storepass ${keystore.pass}
See Also

For more information on keytool, see the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.

ProcedureTo Sign a Certificate by Using keytool

After creating a certificate, the owner must sign the certificate to prevent forgery. E-commerce sites, or those for which authentication of identity is important, can purchase a certificate from a well-known Certificate Authority (CA).

Note –

If authentication is not a concern, for example if private secure communications are all that is required, you can save the time and expense involved in obtaining a CA certificate by using a self-signed certificate.

  1. Follow the instructions on the CA's web site for generating certificate key pairs.

  2. Download the generated certificate key pair.

    Save the certificate in the directory containing the keystore and truststore files. The default is domain-dir/config.

  3. In your shell, change to the directory containing the certificate.

  4. Import the certificate into the local keystore and, if necessary, the local truststore using the following command format:


    keytool -import -v -trustcacerts
-alias keyAlias
 -file server.cer
-keystore cacerts.jks
 -keypass changeit
-storepass changeit

    If the keystore or private key password is not the default password, then substitute the new password for the default (changeit).

  5. To apply your changes, restart Enterprise Server.

    1. Stop Enterprise Server.

      For instructions, see To Stop a Domain (or Server).

    2. Start Enterprise Server.

      For instructions, see To Start a Domain (or Server).

Example 6–9 Importing an RFC/Text-Formatted Certificate Into a JKS Keystore

Certificates are often stored using the printable encoding format defined by the Internet Request for Comments (RFC) 1421 standard instead of their binary encoding. This certificate format, also known as Base 64 encoding, facilitates exporting certificates to other applications by email or through some other mechanism.


keytool -import -noprompt -trustcacerts -alias ${cert.alias} -file 
${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}
Example 6–10 Exporting a Certificate From a JKS Keystore in PKCS7 Format

The reply format defined by the Public Key Cryptography Standards #7, Cryptographic Message Syntax Standard, includes the supporting certificate chain in addition to the issued certificate.


keytool -export -noprompt -alias ${cert.alias} -file ${cert.file} 
-keystore ${keystore.file} -storepass ${keystore.pass}
Example 6–11 Exporting a Certificate From a JKS Keystore in RFC/Text Format


keytool -export -noprompt -rfc -alias ${cert.alias} -file 
${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}
See Also

For more information on keytool, see the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html

ProcedureTo Delete a Certificate by Using keytool

The keytool -delete command enables you to delete an existing certificate.

  1. Delete a certificate using the following command format:

    keytool -delete
 -alias keyAlias
 -keystore keystore-name
 -storepass password
Example 6–12 Deleting a Certificate From a JKS Keystore


keytool -delete -noprompt -alias ${cert.alias}  -keystore ${keystore.file} 
-storepass ${keystore.pass}
See Also

For more information on keytool, see the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.