Managing Public Key Security

 

This topic includes the following sections:

• Requirements for Using Public Key Security

• Who Needs Digital Certificates and Private/Private Key Pairs

• Requesting a Digital Certificate

• Publishing Certificates in the LDAP Directory Service

• Editing the LDAP Search Filter File

• Storing the Private Keys in a Common Location

• Defining the Trusted Certificate Authorities

• Creating a Peer Rules File

Perform the tasks in this topic only if you are using the SSL protocol, or certificate-based authentication in your WebLogic Enterprise application.

 

---

Requirements for Using Public Key Security

To use the SSL protocol and public key security to protect communication between principals and the WebLogic Enterprise domain, you need to install the WebLogic Enterprise Security Pack. The WebLogic Enterprise Security Pack contains the files necessary to enable the use of the SSL protocol and the infrastructure for public key security. For complete information about installing the WebLogic Enterprise Security Pack, see the BEA WebLogic Enterprise Installation Guide.

You also need to choose a Lightweight Directory Access Protocol server and a certificate authority (either commercial or private) set up for your organization before implementing Public Key Security.

 

---

Who Needs Digital Certificates and Private/Private Key Pairs

To use the SSL protocol in the WebLogic Enterprise Security environment, you need a private key and a digitally-signed certificate containing the matching public key. How many digital certificates and private keys you need depends on how you plan to use the SSL protocol.

• If the SSL protocol is being used for protection of a network connection between a remote client and the IIOP Listener/Handler, you only need to obtain a digital certificate and private key for the IIOP Listener/Handler.

  In this case, the remote client must only be configured with a list of trusted certificate authorities.

• If the SSL protocol is being used with certificate-based authentication, you need to obtain a digital certificate and private key for the IIOP Listener/Handler and each principal that will access the WebLogic Enterprise application.

 

---

Requesting a Digital Certificate

To acquire a digital certificate, you need to submit your request for a digital certificate in a particular format called a certificate signature request (CSR). How you create a CSR depends on the certificate authority you use. Certificate authorities typically provide a means to generate a public key, private key, and a CSR which contains your public key. To create a CSR follow the steps outlined by your chosen certificate authority.

When you complete the steps to create a CSR, you receive the following files from the certificate authority:

File	Description
key.der	The private key file.
request.pem	The CSR file which you submit to the certificate authority. It contains the same data as the .dem file but the file is encoded in ASCII so that you can copy it into e-mail or paste it into a web form.

To purchase a digital certificate from a certificate authority, you submit the CSR to the certificate authority according to the enrollment procedure of the certificate authority. Some commerical certificate authorities allow you to purchase digital certificates over through the Web.

 

---

Publishing Certificates in the LDAP Directory Service

The use of a global directory service is the most popular way to store digital certificates. A directory service simplifies the management of information that needs to be globally available to an ever-growing number of users. An LDAP server provides access to a variety of directory services.

The WebLogic Enterprise product when configured to use the SSL protocol can retrieve digital certificates for principals and certificate authorities from an LDAP directory service, such as Netscape Directory Service or Microsoft Active Directory. Before you can use the SSL protocol or certificate-based authentication, you need to install an LDAP directory service and configure it for your organization. BEA Systems does not provide nor recommend any specific LDAP directory service. However, the LDAP directory service you choose should support the X.500 scheme definition and the LDAP version 2 or 3 protocol.

LDAP directory services define a hierarchy of object classes. While there are a number of different object classes, there is a small set associated with digital certificates. Figure 4-1 illustrates the object classes typically associated with digital certificates.

Figure 4-1 LDAP Directory Structure for Digital Certificates

Once you receive your digital certificates from the certificate authority, store them in the LDAP directory service as follows:

• Digital certificates for the IIOP Listener/Handler and any principals are stored in the LDAP directory service with an attribute of userCertificate on an object class with that attribute defined. Typically, these digital certificates are stored as an instance of the strongAuthenticationUser object class as defined by X.500.

• Digital certificates for certificate authorities are stored in LDAP directory service with an attribute of caCertificate on an object class with that attribute defined. Typically, these digital certificates are stored as an instance of the certificateAuthority class as defined by X.500.

If your LDAP scheme requires the use of different classes, you will need to modify the LDAP search file as described in Editing the LDAP Search Filter File.

The WebLogic Enterprise product requires that the digital certificates be stored in the directory service in Privacy Enhanced Mail (PEM) format.

Refer to the BEA WebLogic Enterprise Installation Guide for information about integrating an LDAP directory service into the WebLogic Enterprise environment.

 

---

Editing the LDAP Search Filter File

When configuring a WebLogic Enterprise application to use the SSL protocol or certificate-based authentication, you may need to customize the LDAP search filter file to limit the scope of the search of the directory service or specify the object classes that will be used to hold the digital certificates. Customizing the LDAP search filter file can result in significant performance gains. The WebLogic Enterprise Security Pack ships with the following LDAP search filters:

• A filter stanza that searches the directory service for digital certificates assigned to certificate authorities. The filter limits its search to instances of the certificationAuthority object class.

• A filter stanza that searches the directory service for digital certificates assigned to principals. The filter limits its search to instances of the strongAuthenticationUser object class.

If the directory service scheme for your organization is defined to store digital certificates in object classes other than certificationAuthority and strongAuthenticationUser, the LDAP search filter file must be modified to specify those object classes.

You can specify a location of the LDAP search filter file during the installation of the WebLogic Enterprise Security pack. For more information, see the BEA WebLogic Enterprise Installation Guide.

The LDAP search filter file should be owned by the administrator account. BEA recommends that the file be protected so that only the owner has read and write privileges for the file and all other users have only read privileges for the file.

To limit the search of the directory service for digital certificates for principals and certificate authorities, you need to modify the filter stanzas identified by the following tags in the LDAP search filter file:

• BEA_person_lookup

• BEA_issuer_lookup

These tags identify the stanzas in the LDAP search filter file that contains the filter expression that will be used when looking up information in the directory service. These BEA-specific tags allow the stanzas of an LDAP search filter file to be stored in a common LDAP search filter file with stanzas used by other LDAP-enabled applications that might be found in your organization.

The following is an example of the stanzas of an LDAP search filter file used by the WebLogic Enterprise product for the SSL protocol and certificate-based authentication:

"BEA_person_lookup"
 ".*"  " " "(|(objectClass=strongAuthenticationUser) (mail=%v))" 
                                        "e-mail address"
           "(|(objectClass=strongAuthenticationUser) (mail=%v))" 
                                        "start of e-mail address"
"BEA_issuer_lookup"
 ".*" " " "(&(objectClass=certificationAuthority)
             (cn=%v)"  "exact match cn"
             (sn=%v))"   "exact match sn"

• BEA_person_lookup specifies to search the LDAP directory service for principals by their e-mail addresses.

• BEA_issuer_lookup specifies to search the LDAP directory service for principals by their common names (cn).

See the documentation for your LDAP-enabled directory service for additional information about LDAP search file filters.

 

---

Storing the Private Keys in a Common Location

When a principal generates a CSR, they typically get a file with a private key. Principals need this private key file to verify their identity in the authentication process. Assign the private key file protections so that only the owner of the private key file has read privileges and all other users have no privileges to access the file. Private key files must be stored as PEM-encoded PKCS #8 protected format.

The WebLogic Enterprise system uses the e-mail address of the principal to construct a name for the private key file as follows:

1. The @ character in the name is replaced by an underscore (_) character.

2. All characters after the dot (.) character are deleted.

3. A .PEM file extension is appended to the file.

For example, if the name of the principal is [e-mail] the resulting private key file is milozzi_bigcompany.pem. This naming convention allows an enterprise to have multiple principals that share a common username but are in different e-mail domains.

The WebLogic Enterprise software looks in the following directories for private key files:

Window NT

%HOMEDRIVE%\%HOMEPATH%

UNIX

$HOME

The WebLogic Enterprise software also looks in the following directory for private key files:

$TUXDIR/udataobj/security/keys

The /keys directory should be protected so that only the owner has read privileges for the directory and all other users do not have privileges to access the directory.

Listing 4-1 provides an example of a private key file.

Listing 4-1 Example of Private Key File

---

-----BEGIN ENCRYPTED PRIVATE KEY-----
MIICoDAaBgkqhkiG9w0BBQMwDQQItSFrtYcfKygCAQUEggKAEgrMxo8gYB/MOSXG
...
-----END ENCRYPTED PRIVATE KEY-----

 

---

Defining the Trusted Certificate Authorities

When establishing an SSL connection, the WebLogic Enterprise processes (client applications and the IIOP Listener/Handler) check the identity of the certificate authority and certificates from the peer's digital certificate chain against a list of trusted certificate authorities to ensure the certificate authority is trusted by the organization. This check is similar to the check done in Web browsers. If the comparison fails, the initiator of the SSL connection refuses to authenticate the target and drops the SSL connection. It is typically the job of the system administrator to define a list of trusted certificate authorities.

Retrieve from the LDAP directory service the digital certificates for the certificate authorities that are to be trusted. Cut and paste the PEM formatted digital certificates into a file named trust_ca.cer which is stored in $TUXDIR/udataobj/security/certs. The trust_ca.cer can be edited with any text editor.

The trust_ca.cer file should be owned by the administrator account. BEA recommends that the file be protected so that only the owner has read and write privileges for the file and all other users have only read privileges for the file.

Listing 4-2 provides an example of a Trusted Certificate Authority file.

Listing 4-2 Example of Trusted Certificate Authority File

---

-----BEGIN CERTIFICATE----

-MIIEuzCCBCSgAwIBAgIQKtZuM5AOzS9dZaIATJxIuDANBgkqhkiG9w0BAQQFADCB
zDEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xHzAdBgNVBAsTFlZlcmlTaWduIFRy
dXN0IE5ldHdvcmsxRjBEBgNVBAsTPXd3dy52ZXJpc2lnbi5jb20vcmVwb3NpdG9y
eS9SUEEgSW5jb3JwLiBCeSBSZWYuLExJQUIuTFREKGMpOTgxSDBGBgNVBAMTP1Zl
cmlTaWduIENsYXNzIDEgQ0EgSW5kaXZpZHVhbCBTdWJzY3JpYmVyLVBlcnNvbmEg
...
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE----

-MIIEuzCCBCSgAwIBAgIQKtZuM5AOzS9dZaIATJxIuDANBgkqhkiG9w0BAQQFADCB
zDEXMBUGA1UEChMOVmVyaVNpZ24sIEluYy4xHzAdBgNVBAsTFlZlcmlTaWduIFRy
dXN0IE5ldHdvcmsxRjBEBgNVBAsTPXd3dy52ZXJpc2lnbi5jb20vcmVwb3NpdG9y
...
-----END CERTIFICATE-----

 

---

Creating a Peer Rules File

When communicating across network links, it is important to validate the peer to which you are connected is the intended or authorized peer. Without this check, it is possible to make a secure connection, exchange secure messages, and receive a valid chain of digital certificates but still be vulnerable to a Man-in-the-Middle attack. You perform peer validation by verifying a set of specified information contained in the peer digital certificate against a list of information that specifies the rules for validating peer trust. The system administrator maintains the Peer Rules file.

The Peer Rules are maintained in an ASCII file named peer_val.rul. Store the peer_val.rul file in the following location in the WebLogic Enterprise directory structure:

$TUXDIR/udataobj/security/certs

Listing 4-3 provides an example of a Peer Rules file.

Listing 4-3 Example of Peer Rules File

---

#
# This file contains the list of rules for validating if 
# a peer is authorized as the target of a secure connection
#
O=Ace Industry
O="Acme Systems, Inc."; OU=Central Engineering;L=Herkimer;S=NY
O="Ball, Corp.", C=US
o=Ace Industry, ou=QA, cn=www.ace.com

Each rule in the Peer Rules file is comprised of a set of elements that are identified by a key. The WebLogic Enterprise product recognizes the key names listed in Table 4-1.

Table 4-1 Supported Keys for Peer Rules File

Key	Attribute
CN	CommonName
SN	SurName
L	LocalityName
S	StateOrProvinceName
O	OrganizationName
OU	OrganizationalUnitName
C	CountryName
E	EmailAddress

Each key is followed by an optional white space, the character =, an optional white space, and finally the value to be compared. The key is not case sensitive. A rule is not a match unless the subject's distinguished name contains each of the specified elements in the rule and the values of those elements match the values specified in the rule, including case and punctuation.

Each line in the Peer Rules file contains a single rule that is used to determine if a secure connection is to be established. Rules cannot span lines; the entire rule must appear on a single line. Each element in the rule can be separated by either a comma (,) or semi-colon (;) character.

Lines beginning with the pound character (#) are comments. Comments cannot appear on the same line as the name of an organization.

A value must be enclosed in single quotation marks if one of the following cases is true:

• Strings contain any of the following characters:

  , + = "" <CR> < > # ;

• Strings have leading or trailing spaces

• Strings contain consecutive spaces

By default, the WebLogic Enterprise product verifies peer information against the Peer Rules file. If you do not want to perform this check, create an empty Peer Rules file.