• Skip Headers

    Oracle® Database Advanced Security Administrator' s Guide
    10g Release 1 (10.1)
    Part Number B10772-01
    Go to Documentation Home
    Home    		 Go to Book List
    Book List    		 Go t o Table of Contents
    Contents
    Index    		 Go to Master Index
    Master Index    		 Go to Feedback page
    Feedback
    Go to previous page
    Previous         		Go to next page
    Next
    		View PDF

    7
    Configurin g Secure Sockets Layer Authentication

    This chapter describes h ow to configure and use the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols which are supported by Oracle Adv anced Security. It contains the following topics:

    SSL and TLS in an Oracle Environment

    Secure Sockets Layer (SSL) is an industry standard protocol originally designed by Netscape Commu nications Corporation for securing network connections. SSL uses RSA public key cryptography in conjunction with symmetric key crypto graphy to provide authentication, encryption, and data integrity.

    This section discusses the following topics:

    Difference between SSL and TLS

    Although SSL was primarily develope d by Netscape Communications Corporation, the Internet Engineering Task Force (IETF) took over development of it, with Netscape's ble ssing, and renamed it Transport Layer Security (TLS). Essentially, TLS is an incremental improvement to SSL version 3.0.

    < /table>
    See Also:

    The TLS Protocol Version 1.0 [RFC 2246] at the IETF Web site, which can be found at the followi ng URL:

    http://www.ietf.org
    Note:

    To simplify discussion, this document uses the term "SSL" where either SSL or TLS may be appropriate becau se SSL is the most widely recognized term. However, where distinctions occur between how you use or configure these protocols, this d ocument specifies what is appropriate for either SSL or TLS.

    About Using SSL

    Oracle Advanced Security supports authentication by using digital certificates over SSL in addition to the native encryption and data integrity capabilities of these protocols.

    By using Oracle A dvanced Security SSL functionality to secure communications between clients and servers, you can

    • Use SSL to encrypt the connection between clients and servers
    • Authenticate any client or server, such as Oracle Application Server 10g, to any Oracle da tabase server that is configured to communicate over SSL

    You can use SSL features by themselves or in combination with other authentication methods supported by Oracle Advanced Security. For example, you can use the en cryption provided by SSL in combination with the authentication provided by Kerberos. SSL supports any of the following authenticatio n modes:

    • Only the server authenticates itself to the client
    • Both client and server authenticate themselves to each other
    • Neither the client nor the server authenticates itself to the other, thus using the SSL encryptio n feature by itself

      See Also:

    How SSL Works in an Or acle Environment: The SSL Handshake

    When a network connection over SS L is initiated, the client and server perform an SSL handshake that includes the following steps:

    • The client and server establish which cipher suites to use. This includes which encryption algorithms are used for data transfers.
    • The server sends its certificate to the client, and the client verifies that the server's certificate was signed by a trusted CA. This step verifies the identity of the server.
    • Similarly, if client authentication is required, the client sends its own certificate to the server, and the se rver verifies that the client's certificate was signed by a trusted CA.
    • The cl ient and server exchange key information using public key cryptography. Based on this information, each generates a session key. All subsequent communications between the client and the server is encrypte d and decrypted by using this set of session keys and the negotiated cipher suite.

    Th e authentication process consists of the following steps:

    1. On a client, the user initiates an Oracle Net connection to the server by using SSL.
    2. SSL performs the handshake between the client and the server.
    3. If the handshake is successful, the server verifies that the user has the appropriate < a href="asogls.htm#996758">authorization to access the database.

    Public Key Infrastructure i n an Oracle Environment

    A public key infrastructure (PKI) is a substr ate of network components that provide a security underpinning, based on trust assertions, for an entire organization. A PKI exists s o that disparate network entities can access its security services, which use public-key cryptography, on an as-needed basis. Oracle provides a complete PKI that is based on RSA Security, Inc., Public-Key Cryptography Standards, and which interoperates with Oracle s ervers and clients.

    About Public Key Cryptography

    Traditional private-key or s ymmetric-key cryptography requires a single, secret key that is shared by two or more parties to a secure communication. This key is used to both encrypt and decrypt secure messages sent between the parties, requiring prior, secure distribution of the key to each pa rty. The problem with this method is that it is difficult to securely transmit and store the key.

    Public-key cryptography provides a solution to this problem, by employing publ ic and private key pairs and a secure method for key distribution. The freely available public key is used to encrypt messages that can only be decrypted by the holder of the associated private key. The private key is securely stored, tog ether with other security credentials, in an encrypted container called a wallet.

    Public-key algorithms can guarantee the secrecy of a message, but they don't nece ssarily guarantee secure communications because they don't verify the identities of the communicating parties. In order to establish secure communications, it is important to verify that the public key used to encrypt a message does in fact belong to the target reci pient. Otherwise, a third party can potentially eavesdrop on the communication and intercept public key requests, substituting its ow n public key for a legitimate key (the man-in-the-middle attack).

    < a name="1009657">

    In order to avoid such an attack, it is necessary to verify the owner of the public key, a proces s called authentication. Authentication can be accomplished through a < a href="asogls.htm#996784">certificate authority (CA), which is a third party that is trusted by bo th of the communicating parties.

    The CA issues public key certificates that contain an entit y's name, public key, and certain other security credentials. Such credentials typically include the CA name, the CA signature, and t he certificate effective dates (From Date, To Date).

    The CA uses its private key to encrypt a message, while the public key is used to decrypt it, thus verifying that the message was encrypted by the CA. The CA public key is well known, and does not have to be authenticated each time it is accessed. Such CA public keys are stored in wallets.

    Public Key Infrastructu re Components in an Oracle Environment

    Public key infrastructure (PKI ) components in an Oracle environment include the following:

    Certificate Authority

    A certificate authority (CA) is a trusted third party that certifies the identity of entities, such as users, databases, administrators, clients, and servers. When an entity requests certification, the CA verifies its identity and g rants a certificate, which is signed with the CA's private key.

    Different CAs may have diffe rent identification requirements when issuing certificates. Some CAs may verify a requester's identity with a driver's license, some may verify identity with the requester's fingerprints, while others may require that requesters have their certificate request form n otarized.

    The CA publishes its own certificate, which includes its public key. Each network entity has a list of trusted CA certificates. Before communicating, network entities exchange certificates and check that each other' s certificate is signed by one of the CAs on their respective trusted CA certificate lists.

    Network entities can obtain their certificates from the same or different CAs. By default, Oracle Advanced Security automatically ins talls trusted certificates from VeriSign, RSA, Entrust, and GTE CyberTrust when you create a new wallet.

    < p class="BP">Oracle Application Server Certificate Authority, part of Oracle Identity Management Infrastructure, is a new Oracle PKI component available in Oracle Application Server 10g (9.0.4).

    See Also:

    "Wallets"

    Certificates

    < /a>

    A certificate is created when an entity's public key is signed by a trusted certificate authority (CA). A certifica te ensures that an entity's identification information is correct and that the public key actually belongs to that entity.

    A certificate contains the entity's name, public key, and an expiration date--as well as a serial numb er and certificate chain information. It can also contain information a bout the privileges associated with the certificate.

    When a network entity receives a certif icate, it verifies that it is a trusted certificate, that is, one that has been issued and signed by a trusted certif icate authority. A certificate remains valid until it expires or until it is revoked.

    Certificate Revocation L ists

    Typically, when a CA signs a certificate binding a public ke y pair to a user identity, the certificate is valid for a specified period of time. However, certain events, such as user name change s or compromised private keys, can render a certificate invalid before the validity period expires. When this happens, the CA revokes the certificate and adds its serial number to a Certificate Revocation List (CRL). CAs periodically publish CRLs to alert the user p opulation when it is no longer acceptable to use a particular public key to verify its associated user identity.

    When servers or clients receive user certificates in an Oracle environment, they can validate the certificate by checking its expiration date, signature, and revocation status. Certificate revocation status is checked by validating it against pu blished CRLs. If certificate revocation status checking is turned on, then the server searches for the appropriate CRL depending on h ow this feature has been configured. The server searches for CRLs in the following locations:

    1. Local file system
    2. Oracl e Internet Directory
    3. C RL Distribution Point, a location specified in the CRL Distribution Point (CRL DP) X.509, version 3, certificate extensi on when the certificate is issued.

      < /tr>
      See Also:

      "Certificate Validation with Certificate Revocation Lists" for information about configuring and managing this PKI component

    Note:

    To use CRLs with other Oracle products, refer to the specific pro duct documentation. This implementation of certificate validation with CRLs is only available in the Oracle Database 10g Release 1 (10.1) SSL adapter.

    Wallets

    A wallet is a container that is used to store authentication and signing credentials, including private keys, certificates, and t rusted certificates needed by SSL. In an Oracle environment, every entity that communicates over SSL must have a wallet containing an X.509 version 3 certificate, private key, and list of trusted certificates (with the exception of Diffie-Hellman).

    Security administrators use Oracle Wallet Manager to manage security credentials on the server. Wallet owners use it to manage security credentials on clients. Specifically, you use Oracle Wallet Manager to do the following:

    Hardware security modules

    Oracle Advanced Security uses these devices for the following functions:

      Store cryptographic information, such as private keys
    • Perform cryptographic operations to off load RSA operations from the server, freeing the CPU to respond to ot her transactions

    Cryptographic information can be stored on two types of hardware dev ices:

    • (Server-side) Hardware boxes where keys are stored in th e box, but managed by using tokens.
    • (Client-side) Smart card readers, which su pport storing private keys on tokens.

    An Oracle environment supports hardware devices using APIs that conform to the RSA Security, Inc., Public-Key Cryptography Standards (PKCS) #11 specification.

    < /tr>
    Note:

    Curre ntly only nCipher devices are certified with Oracle Advanced Security. Certificate with other vendors is in progress.

    See Also:

    "Configuring Your System to Use Hardwa re Security Modules" for details configuration details.

    SSL Combined with Oth er Authentication Methods

    You can configure Oracle Advanced Security to use SSL concurrently with database usernames and passwords, RADIUS, and Kerberos, which are discussed in the following sections:

    Architecture: Oracle Advanced Secur ity and SSL

    Figure 1-5, which displays the Oracle Advanced Security implementation architecture, shows that Oracle Advanced Sec urity operates at the session layer on top of SSL and uses TCP/IP at th e transport layer. This separation of functionality lets you employ SSL concurrently with other supported protocols.

    See Also:

    Oracle Net Services Administrator's Guide, for information about stack communications in an Oracle n etworking environment

    How SSL Works with Other Authentication Methods

    Figure 7-1 illustrates a configuration in which SSL is used in combination with another authentication method supported by Oracle Advanced Security. In this example, SSL is used to establish the initial hands hake (server authentication), and an alternative authentication method is used to authenticate the client.

    Figure 7-1 SSL in Relation to Other Authentication Methods< /h4> Text description of asoag018.gif follows

    Text description of the illustration asoag018.gif

    1. The client seeks to connect to the Oracle database server.
    2. SSL performs a handshake during which the server authenticates itself to the client and both the client and server establish which ciphe r suite to use.
    3. Once the SSL handshake is successfully completed, the u ser seeks access to the database.
    4. The Oracle database server authentica tes the user with the authentication server using a non-SSL authentication method such as Kerberos or RADIUS.
    5. Upon validation by the authentication server, the Oracle database server grants access and aut horization to the user, and then the user can access the database securely by using SSL.

      SSL and Firewalls

      Oracle Advanced Security supports two type s of firewalls:

      • Application proxy-based firewalls, such as Net work Associates Gauntlet, or Axent Raptor.
      • Stateful packet inspection firewall s, such as Check Point Firewall-1, or Cisco PIX Firewall.

      When you enable SSL, statef ul inspection firewalls behave like application proxy firewalls because they do not decrypt encrypted packets.

      Firewalls do not inspect encrypted traffic. When a firewall encounters data addressed to an SSL port on an intrane t server, it checks the target IP address against its access rules and lets the SSL packet pass through to permitted SSL ports, rejec ting all others.

      With the Oracle Net Firewall Proxy kit, a product offered by some firewall vendors, firewall applications can provide specific support for database network traffic. If the proxy kit is implemented in the fire wall, the following processing takes place:

      • The Net Proxy (a c omponent of the Oracle Net Firewall Proxy kit) determines where to route its traffic.
      • The database listener requires access to a certificate in order to participate in the SSL handshake. The listener inspects the SSL packet and identifies the target database, returning the port on which the target database listens to the client. This port must be designated as an SSL port.
      • The client communicates on this server-designated port in all subsequent connections.
      • The number of ports that are open in the firewall increase as a function of the number of database connection s requested for different databases. This approach prohibits the database server from using randomly chosen SSL ports, because the SS L ports on the firewall must match those chosen by the database. You can avoid this condition by deploying Oracle Connection Manager, an application included with Oracle Database Enterprise Edition.

      Oracle Connection M anager lets you route client connections over multiple Oracle Net protocols. Each client connection request establishes an SSL connec tion between the client and Oracle Connection Manager, which in turn establishes a TCP/IP connection with the target database. Multip le clients can thus connect to multiple databases behind the firewall, using a single SSL port through the firewall.

      See Also:

      "How SSL Works in an Oracle Environment: The SSL Handshake"
      Note:

      Although Oracle Connection Manager can be used to avoid opening up multiple SSL ports through the firewall, consider the following:

      • The internal connection, between Oracle Connection Manager and th e database, is not an SSL connection. You should encrypt such connections, using Oracle Advanced Security nat ive encryption.
      • Because such connections do not use SSL, clients cannot use cer tificate-based authentication.
      See Also:

      Oracle Net Services Administrator's Guide for information about Oracle Connection Manager

      SSL Usage Issues

      Consid er the following issues when using SSL:

      • SSL use enables secure communication with other Oracle products, such as Oracle Internet Directory.
      • Because SSL supports both authentication and encryption, the client/server connection is somewhat slower than the standard Oracle Net TCP/IP transport (using native encryption).
      • Each SSL authentication mode requ ires configuration settings.

        Note:
        • U.S. government regulations prohib it double encryption. Accordingly, if you configure Oracle Advanced Security to use SSL encryption and another encryption method conc urrently, the connection fails (you also cannot configure SSL authentication concurrently with non-SSL authentication).
        • If you configure SSL encryption, you must disable non-SSL encryption. To disable such encryp tion, see: "Disabling Oracle Advanced Security Authentication".
        See Also:

      Enabling SSL

      To enable SSL:

      Task 1: Install Oracle Advanced Security and Related Products

      < h3 class="H2">Task 2: Configure SSL on the Server

    Step 1: Confirm Wallet Creation on the Server

    Before proceeding with the next step, you must confirm that a wallet has been created. To co nfirm that your wallet is ready, open it by using Oracle Wallet Manager. The wallet should contain a certificate with a status of "Re ady" and auto login turned on. If auto login is not on, then select it from the Wallet menu and re-save the wallet. This turns auto l ogin on.

    Step 2: Specify the Database W allet Location on the Server

    Use Oracle Net Manager to specify requir ed configuration parameters for the server (See "Starting Oracle Net Manager"):

    1. Navigate to the Oracle Advanc ed Security profile. (See "Navigating to the Oracle Advanced Security Profile") The Oracle Advanced Security SSL window appears (Figure 7-5).
    2. Choose the SSL tab and select Configure SSL for: Server.< /li>
    3. In the Wallet Directory box, enter the di rectory in which the Oracle wallet is located, or click Browse to find it by searching the file system.

      Note that if you are configuring the database-to-directory SSL connection for Enterpris e User Security, then Database Configuration Assistant automatically creates a database wallet while registering the database with th e directory. You must use that wallet to store the database PKI credentials for SSL-authenticated Enterprise User Security.

      Important:
    4. Use Oracle Wallet Manager to create the wallet. See "Creating a New Wallet".
    5. Us e Oracle Net Manager to set the wallet location in the sqlnet.ora file.

      6. Be sure to enter the same wallet location when you create it and when you set the location in the sqlnet.ora file.

      < hr>
    1. Choose File > Save Network Configuration.

      The sqlnet.ora and listener.ora files are updated with the following entri es:

      wallet_location = 
 (SOURCE=
  (METHOD=Fi
le)
  (METHOD_DATA=
   (DIRECTORY=wallet_location)))
      Note:

      The list ener uses the wallet defined in listener.ora (it can use any database wallet). When SSL is configured for a server using Net Manager, the wallet location is entered into the listener.ora and the sqlnet.ora files. The list ener.ora file is not relevant to the Oracle client.

      To change the listener wallet loc ation (so that the listener has its own wallet), you can edit listener.ora to enter the new location.

    Step 3: Set the SSL Cipher Suites on the Server (Optional)

    A cipher suite is a set of authentication, encryption, and data integrity algorithms used for exchanging messages between netw ork entities. During an SSL handshake, two entities negotiate to see which cipher suite they will use when transmitting messages back and forth.

    When you install Oracle Advanced Security, the SSL cipher suites listed in Table 7-1 are set for you by default and negotiated in the order they are listed. You can override t he default order by setting the SSL_CIPHER_SUITES parameter. For example, if you use Oracle Net Manager to add the ciphe r suite SSL_RSA_WITH_RC4_128_SHA, all other cipher suites in the default setting are ignored.

    You can prioritize the cipher suites. When the client negotiates with servers regarding which cipher suite to use, it follows the prioritization you set. When you prioritize the cipher suites, consider the following:

    • Server and client must be configured to use compatible cipher suites for a successful connection .
    • The level of security you want to use. For example, triple-DES encryption is stronger than DES.
    • The impact on performance. For example, triple-DES encrypt ion is slower than DES.
    • Prioritize cipher suites starting with the strongest a nd moving to the weakest to ensure the highest level of security possible.

      Note:

      If you set a cipher suite employing Dif fie-Hellman anonymous authentication on the server, then you must also set the same cipher suite on the client. Otherwise, the connec tion fails.

      If you use a cipher suite employing Diffie-Hellman anonymous, then you must set the SSL_CLIENT_AUTHENTICATION parameter to FALSE. See: "Step 5: Set SSL Client Authentication on the Server (Optional)".

    Table 7-1 lists the SSL cipher suites supported in the current release of Oracle Advanced Security. These cipher suites are set by default when you install Oracle Advanced Security. This table als o lists the authentication, encryption, and data integrity types each cipher suite uses.

    < a name="1023522"> Table 7-1  Oracle Advanced Sec urity Cipher Suites
    Cipher Suites Authentication Encryption < /a> Data Integrity

    SSL_RSA_WITH_3DES_EDE_CBC_SHA

    RSA

    3DES EDE CBC

    < /td>

    SHA-1

    SSL_RSA_WITH_RC4_128_SHA

    RSA

    RC4 128

    SHA-1

    SSL_RSA_WITH_RC4_128_MD5

    RSA

    RC4 128

    MD5

    SSL_RSA_WITH_DES_CBC_SHA

    < /td>

    RSA

    DE S CBC

    SHA-1

    SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

    DH anon

    3DES EDE CBC

    SHA-1

    SSL_DH_anon_WITH_RC4_128_MD5

    DH anon

    RC4 128

    		 < /a>

    MD5

    SSL_DH_anon_WITH_DES_CBC_SHA

    DH anon

    DES CBC

    SHA-1

    SSL_RSA_EXPORT_WITH_RC4_4 0_MD5

    RSA

    RC4 40

    MD5

    SSL_RSA_EXPORT_WITH_DES40_CBC_SHA

    RSA

    DES40 CBC

    SHA-1

    SSL_RSA_WITH_AES_128_CBC_SHAFoot 1

    RSA

    AES 128 CBC

    SHA-1

    SSL_RSA_WITH_AES_256_CBC_SHAFootref 1

    RSA

    AES 256 CBC

    SHA-1

    1 AES cipher s work with Transport Layer Security (TLS 1.0) only
    To specify cipher suites for the server:
  • Navigate to the SSL ta b of the Oracle Advanced Security window in Oracle Net Manager, and select Configure SSL for: Server.
  • Click Add. A dialog box displays available cipher suites (Figure 7-2).

    • Figure 7-2 SSL Cipher Suites Window

    Text description of ssl0002.gif follows.

    Text description of the illustration ssl0002.gif

    1. Select a suite and click OK. The Cipher Suite Configuration list is updated (Figure 7-3):

    Figure 7-3 Oracle Advanced Security SSL Window (Server)

    Text description of ssl0 004.gif follows.

    Text description of the illustration ssl0004.gif

    < /a>
    1. Use the up and down arrows to prioritize the c ipher suites.
    2. Choose File > Save Network Configuration.

      The sqlnet.ora file is upda ted with the following entry:

      SSL_CIPHER_SUITES= (SSL_cipher_suite1 [,
SSL_cipher_suite2])

    Step 4: Set the Required SSL Version on the Server (Optional)

    You can set the SSL_VERSION parameter in the sqlnet.ora file. This parameter defines the version of SSL that must run on the systems with which the server communicates. You can require these systems to use any valid v ersion. The default setting for this parameter in sqlnet.ora is undetermined, which is set by selecting Any from the list in the SSL tab of the Oracle Advanced Security window.

    To set the SSL version for the server:
    1. Navigate to the SSL tab of the Oracle Advanced Security window in Oracle Net Manager, and select Configure SSL for: Server.
    2. In the Require SSL Version: list, the default is Any. Accept this default or select the SSL version you want to use.
    3. Choose File > Save Network Configuration.

      If you chose Any, then the sqlnet.ora file is updated with the following entry:

      SSL_VERSION=UNDETERMINED
      Note:

      SSL 2.0 is not supported on the server side.

    Step 5: Set SSL Client Authentication on the Server (Optional)

    The SSL_CLIENT_ AUTHENTICATION parameter in the sqlnet.ora file controls whether the client is authenticated using SSL. The defau lt value is TRUE.

    You must set this parameter to FALSE if you are using a cipher suite that contains Diffie-Hellman anonymous authentication (DH_anon). Also, you can set this parameter t o FALSE for the client to authenticate itself to the server by using any of the non-SSL authentication methods supported by Oracle Advanced Security, such as Kerberos or RADIUS.

    To set SSL_CLIENT_AUTHENTICATION to FALSE on the server:
    1. Navigate to the SSL tab of the Oracle Advanced Security window in Oracle Net Manager, and select Configure SSL for: Server. The Or acle Advanced Security SSL window for server configuration appears (Figure 7-4).

    Figure 7-4 Oracle Advanced Security SSL Window (Serv er)

    Text description of ssl0005.gif follows.

    Text description of the illustration ssl0005.gif

    1. Uncheck Require Client Authentication.
    2. Choose File > Save Network Configura tion.

      The sqlnet.ora file is updated with the following entry:

      SSL_CLIENT_AUTHENTICATION=FALSE
    < /a>

    Step 6: Set SSL as an Authenticat ion Service on the Server (Optional)

    The SQLNET.AUTHENTICATION_ SERVICES parameter in the sqlnet.ora file sets the SSL authentication service.

    Set this parameter if you want to use SSL authentication in conjunction with another authentication method supported by Oracle Advanced Security. For example, use this parameter if you want the server to authenticate itself to the client by using SSL and the client to authenticate itself to the server by using Kerberos.

    To set the SQLNET.AUTHENTICATION_SERVICES parameter on the server:

    Add TCP/IP with SSL (TCPS) to this parameter in the sqlnet.ora file by usin g a text editor. For example, if you want to use SSL authentication in conjunction with RADIUS authentication, set this parameter as follows:

     SQLNET.AUTHENTICATION_SERVICES = (TCPS, radius)

    If you do not want to use SSL authentication in conjunction with another a uthentication method, then do not set this parameter.

    Step 7: Create Listening Endpoint that Uses TCP/IP with SSL on the Server

    Configure the listener with a TCP/IP with SSL listening endpoint in the liste ner.ora file. Oracle Corporation recommends using port number 2484 for typical Oracle Net clients.

    See Also:

    Task 3: Configure SSL on the Client

    To configure SSL on the client:

    Step 1: Confirm Cl ient Wallet Creation

    Before proceeding with the next step, you must c onfirm that a wallet has been created on the client and that the client has a valid certificate.

    Note:

    Oracle Corporation r ecommends that you use Oracle Wallet Manager to remove the trusted certificate in your Oracle wallet associated with each certificate authority that you do not use.
    < strong class="NH">See Also:
    • < a href="asowalet.htm#1006084">Chapter 8, "Using Oracle Wallet Manager", for general information about wallets
    • "Opening an Existing Wallet" , for information about opening an existing wallet
    • "Creating a New Wallet", for information about creating a new wallet

    Step 2: Configure Oracle Net Service Name to Include Server DNs and Use TCP/IP with SSL on the Client

    You must specify the server's distinguished nam e (DN) and TCPS as the protocol in the client network configuration files to enable server DN matching and TCP/IP with SSL connections. Server DN matching prevents the database server from faking its identity to the client during connection s by matching the server's global database name against the DN from the server certificate.

    You must manually edit the client network configuration files, tnsnames.ora and listener.ora, to specify th e server's DN and the TCP/IP with SSL protocol. The tnsnames.ora file can be located on the client or in the LDAP direct ory. If it is located on the client, then it typically resides in the same directory as the listener.ora file. Depending on your operating system, these files reside in the following directory locations:

    • (UNIX) ORACLE_HOME/network/admin/
    • (Windows) ORACLE_BASE\ORACLE_HOME\network\admin\

    To edit the tnsnames.ora and listener.ora files, use the fol lowing steps:

    1. In the client tnsnames.ora file, add the SSL_SERVER_CERT_DN parameter and specify the database server's DN as follows: 
      (SECURITY=

      (SSL_SERVER_CERT_DN="cn=finance,cn=OracleConte
xt,c=us,o=acme"))

      The client uses this informat ion to obtain the list of DNs it expects for each of the servers, enforcing the server's DN to match its service name. Example 7-1 shows an entry for the Finance database in the tnsnames.ora file.

      Alternatively, the administrator can ensure that the common name (CN) portion of the server's DN matc hes the service name.

    2. Also in the client tnsnames.ora file, enter tcps as the PROTOCOL in the ADDRESS parameter. This specifies that the client wil l use TCP/IP with SSL to connect to the database that is identified in the SERVICE_NAME parameter. Example 7-1 also shows an entry that specifies TCP/IP with SSL as the connecting protocol in the tnsnames.ora file.
    3. In the listener.ora file, enter tcps as the PROTOCOL in the ADDRESS parameter. Example 7-2 shows an entry that specifies TCP/IP with SSL as the protocol.

    Example 7-1 Sample tnsnames.ora File with Server Certificate DN and TCP/IP with SSL Specified

    finance=
(DESCRIPTION=

(ADDRESS_LIST=

    (ADDRESS= (PROTOCOL = tcps) (HOST = finance_server) (PORT = 15
75)))

    (CONNECT_DATA=

    (SERVICE_NAME
= Finance.us.acme.com))

    (SECURITY=

    (SSL_SERVER_CERT_DN="cn=finance,cn=OracleContext,c=us,o=acme"))

    Example 7-2 Sample listener.ora File with TCP/IP with SSL Specified as the Protocol 
    LISTENER=

(DESCRIPTION_LIST=

    (DESCRIPTION=

    (ADDRESS= (PROTOCOL = tcps) (HOST
 = finance_server) (PORT = 1575))))

    Step 3: Specify Required Client SSL Co nfiguration (Wallet Location)

    Use Oracle Net Manager to specify requi red configuration parameters for the client (See "Starting Oracle Net Manager"):

    1. Navigate to the Oracle Advan ced Security profile. (See "Navigating to the Oracle Advanced Security Profile") The Oracle Advanced Security SSL window appears (Figure 7-5):

    Figure 7-5 Oracle Advanced Security SSL Window (Client)

    Text description of ssl0001.gif follows.

    Text description of the illustration ssl0001.gif

    1. Choose the SSL tab.
    2. Select Configure SSL for: Client.
    3. In the Wallet Directory box, enter the directory in which the Oracle wallet is located, or click Brow se to find it by searching the file system.
    4. From the Match ser ver X.509 name list, choose one of the following options:
      • Yes: Requires that the server's distinguished name (DN) match its service name. SSL ensures that the certificate is from the server and connections succeed only if there is a match.

      • No (default): SSL checks for a match between the DN and the service name, but does not enforce it. Connections succeed regardless of the outcome, but an error is logged if the match fails.
      • Let Client Decide: Enables t he default.

        • Note:

        This check can be made only when RSA ciphers are selected, which is the default setting.
        < td class="Note">
        Note:

        The following alert appears when you select No:

        Security Aler t

        Not enforcing the server X.509 name match allows a server to potentially fake its identity . Oracle Corporation recommends selecting YES for this option so that connections are refused when there is a mismatch.

    5. Choose File > Save Network Configuration.

      The sqlnet.o ra file on the client is updated with the following entries:

      SSL_CLIENT_AUTHENTICA
TION =TRUE
wallet_location = 
 (SOURCE=
  (METHOD=File)
  (METHOD_DATA=
   (DIRECTORY=wallet_location)))

<
/a>SSL_SERVER_DN_MATCH=(ON/OFF)
      See Also:

      For info rmation about the server match parameters:

      For information about using Oracle Net Manager to configure TCP/IP with SSL:

    Step 4: Set the Client SSL Cipher Suites (Optional)

    A cipher suite is a set of au thentication, encryption, and data integrity algorithms used for exchanging messages between network entities. During an SSL handshak e, two entities negotiate to see which cipher suite they will use when transmitting messages back and forth.

    When you install Oracle Advanced Security,the SSL cipher suites listed in Table 7-1 are set for you by default. This table lists them in the order they are tried when two entities are negotiating a connection. You ca n override the default by setting the SSL_CIPHER_SUITES parameter. For example, if you use Oracle Net Manager to add the cipher suite SSL_RSA_WITH_RC4_128_SHA, all other cipher suites in the default setting are ignored.

    You can prioritize the cipher suites. When the client negotiates with servers regarding which cipher suite to us e, it follows the prioritization you set. When you prioritize the cipher suites, consider the following:

    • The level of security you want to use. For example, triple-DES encryption is stronger than DES.
    • The impact on performance. For example, triple-DES encryption is slower than DES. See "Configuring Your System to Use Hardware Security Modules" for information about using SSL hardware accelerators with Oracle Advanced Security.
    • Administrative requirements:

      The cipher suites selected for a client must b e compatible with those required by the server. For example, in the case of an Oracle Call Interface (OCI) user, the server requires the client to authenticate itself. You cannot, in this case, use a cipher suite employing Diffie-Hellman anonymous authentication whi ch disallows the exchange of certificates.

    You typically prioritize cipher suite s starting with the strongest and moving to the weakest.

    Table 7-1 lists the SSL cipher suites supported in the current release of Oracle Advanced Security. These cipher suites are set by defa ult when you install Oracle Advanced Security. This table also lists the authentication, encryption, and data integrity types each ci pher suite uses.

    Note:

    If the SSL_CLIENT_AUTHENTICATION parameter is set to true in the sql net.ora file, then disable all cipher suites that use Diffie-Hellman anonymous authentication. Otherwise, the connection fails .
    To specify client cipher suites:
    1. Navigate to the SSL tab of the Oracle Advanced Security window in Oracle Ne t Manager, and select Configure SSL for Client.
    2. In the Cipher Suite Configuration region, click Add. A dialog box displays available cipher suit es (Figure 7-2).
    3. Select a suite and cl ick OK. The Cipher Suite Configuration list is updated (Figure 7-6):

    Figure 7- 6 Oracle Advanced Security SSL Window (Client)

    Text description of ssl 0003.gif follows.

    Text description of the illustration ssl0003.gif

    1. Use the up and down arrows to prioritize the cipher suites.
    2. Choose File > Save Network Configuration.

      The sqlnet.ora file is upd ated with the following entry:

      SSL_CIPHER_SUITES= (SSL_cipher_suite1 [
,SSL_cipher_suite2])

    Step 5: Set the Required SSL Version on the Client (Optional)

    You can set the SSL_VERSION parameter in the sqlnet.ora file. This parameter define s the version of SSL that must run on the systems with which the client communicates. You can require these systems to use any valid version. The default setting for this parameter in sqlnet.ora is undetermined, which is set by selecting Any from the list in the SSL tab of the Oracle Advanced Security window. Wh en Any is selected, TLS 1.0 is tried first, then SSL 3.0 and SSL 2.0 are tried in that order. Ensure th at the client SSL version is compatible with the version the server uses.

    To set the required SSL version for the client:
    1. Navigate to the SSL tab of the Oracle Advanced Security window in Oracle Net Manager, and select Configure SSL for: Client. (See Figure 7-5).
    2. In the Require SSL Version list, the default setting is Any. Accept this default or select t he SSL version you want to configure.
    3. Choose File< /strong> > Save Network Configuration.

      The sqlnet .ora file is updated. If you selected Any, then it is updated with the following entry:

      SSL_VERSION=UNDETERMINED

    Step 6: Set SSL as an Authentication Service on the Client (Optional )

    The SQLNET.AUTHENTICATION_SERVICES parameter in the sqlnet.ora file sets the SSL authentication service. Typically, the sqlnet.ora file is located in the same di rectory as the other network configuration files. Depending on your platform, the sqlnet.ora file is in the following di rectory location:

    • (UNIX) ORACLE_HOME/network/admin
    • (Windows) ORACLE_BASE\ORACLE_HOME\network\admin\

    Set the SQLNET .AUTHENTICATION_SERVICES parameter if you want to use SSL authentication in conjunction with another authentication method sup ported by Oracle Advanced Security. For example, use this parameter if you want the server to authenticate itself to the client by us ing SSL and the client to authenticate itself to the server by using RADIUS.

    To set the client SQLNET.AUTHENTICATION_SERVICES parameter:

    Add TCP/IP with SSL (TCPS) to this parameter in the sqlnet.ora file by using a text editor. For example, if you want to use SSL authentication in conjunction with RADIUS authentication, se t this parameter as follows:

     SQLNET.AUTHENTICATION_SERVICES = (TCPS, r
adius)

    If you do not want to use SSL authentication in conjun ction with another authentication method, then do not set this parameter.

    Task 4: Log on to the Database

    If you are using SSL authentication for the client (SSL_CLIENT_AUTHENTICATION=true in the listener.ora file), then launch SQL*Plus and enter the following:

    CONNECT/@net_service_name

    If you are not using SSL authentication (SSL_C LIENT_AUTHENTICATION=false in the listener.ora file), launch SQL*Plus and enter the following:

    CONNECT username/password@net_service_name

    Tro ubleshooting SSL

    The following section lists the most common errors y ou may receive while using the Oracle Advanced Security SSL adapter.

    It may be necessary to enable Oracle Net tracing to determine the cause of an error. For information about setting tracing parameters to enable Oracle Net t racing, see Oracle Net Services Administrator's Guide.


    ORA-28759: Failure to Open File

    Cause: The system could not open the specified file. Typically, this erro r occurs because the wallet cannot be found.

    Action: Check the f ollowing:

    • Ensure that the correct wallet location is specified in the sqlnet.ora file. Note: this should be the same directory location where you saved the wallet.
    • Enable Oracle Net tracing to determine the name of the file that cannot be opened and the reason .
    • Ensure that auto login was enabled when you saved the wallet. See "Using Auto Login"
    < br> ORA-28786: Decryption of Encrypted Private Key Failure

    Cause: An incorrect password was used to decrypt an encrypted private key. Frequently, this happens because an auto login wallet is not being used.

    < /a>

    Action: Use Oracle Wallet Manager to turn the auto login feature on for the wallet. Then re-save the wallet. See "Using Auto Login".


    ORA-28858: SSL Protocol Error

    Cause: This is a generic error that can occur during SSL handshake negotiation between two processes.

    Action: Enable Oracle Net tracing and attempt the connection again to produce trace output. Then cont act Oracle customer support with the trace output.


    ORA-28859 SSL Negotiati on Failure

    Cause: An error occurred during the negotiati on between two processes as part of the SSL protocol. This error can occur when two sides of the connection do not support a common c ipher suite.

    Action: Check the following:

      < li class="LB2" type="disc">Use Oracle Net Manager to ensure that the SSL versions on both the client and the se rver match, or are compatible. For example, if the server accepts only SSL 3.0 and the client accepts only TLS 1.0, then the SSL conn ection will fail.
    • Use Oracle Net Manager to check what cipher suites are confi gured on the client and the server, and ensure that compatible cipher suites are set on both. See "Step 4: Set the Client SSL Cipher Suites (Optional)" for details about setting compatible cipher suit es on the client and the server. Note: if you do not configure any cipher suites, then all available cipher suites are enabled.

    ORA-28862: SSL Connection Failed

    Cause: This error occurred because the peer closed the connection.

    Action: Check the following:

    • Ensure that the correct wallet location is specified in the sqlnet.ora file so the system can find the wallet.
    • Use Oracle Net Manager to ensure that cipher suites are set correctly in the sqlnet.ora file. (Sometimes this error occurs because the sqlnet.ora has been manually edited and the cipher suite names are misspelled. Note that case sensitive string matching is used with cipher suite names.)
    • Use Oracle Net Manager to ensure that the SSL versions on both the client and the server match, or are compa tible. Sometimes this error occurs because the SSL version specified on the server and client do not match. For example, if the serve r accepts only SSL 3.0 and the client accepts only TLS 1.0, then the SSL connection will fail.
    • For more diagnostic information, enable Oracle Net tracing on the peer.

    ORA-28865: SSL Connection Closed

    Cause: The SSL connection closed because of an error in the underlying transport layer, or because the peer process quit unexpectedly.

    Action: Check the following:

    • Use Oracle Net Manager to ensure that the SSL versions on both the client and the server match, or are compatible. Sometimes this error occurs because the SSL version specified on the server and client do not match. For example, if the server accepts only SSL 3.0 and the client accepts only TLS 1.0, then the SSL connection will fail.
    • If you are using a Diffie-Hellman anonymous cipher suite and the SSL_CLIENT_AUTHENTICATION parameter is set to true in the server's listener.ora file, then the client does not pass its certificate t o the server. When the server does not receive the client's certificate, it (the server) cannot authenticate the client so the connec tion is closed. To resolve this use another cipher suite, or set this listener.ora parameter to false.
    • Enable Oracle Net tracing and check the trace output for network errors.
    • See Actions listed for "ORA-28862: SSL Connection Failed"

    ORA-28868: Peer Certificate Chain Check Fai led

    Cause: When the peer presented the certificate chain, it was checked and that check failed. This failure can be caused by a number of problems, including:

    • One of the certificates in the chain is expired.
    • A certificate authority for one of the certificates in the chain is not recognized as a trust point.
    • The signature in one of the certificates cannot be verified.

    Action: See "Opening an Existing Wallet" to use Oracle Wallet Manager to open your wallet and check the following:

    • Ensure that all of the certificates installed in your wallet are current (not expired).
    • Ensure that a certificate authority's certificate from your peer's certificate chain is added as a trusted certificate in your wallet. See "Imp orting a Trusted Certificate" to use Oracle Wallet Manager to import a trusted certificate.

    ORA-28885: No Certificate with Required Key Usage Was Found< br>

    Cause: Your certificate was not created with the appropriate X.50 9 Version 3 key usage extension.

    Action: Use Oracle Wallet Manag er to check the certificate's key usage. See Table 8-1, "KeyUsage Values".


    ORA-29024: Certificate Validation Failure

    Cause: The certificate sent by the other side could not be validated. This m ay occur if the certificate has expired, has been revoked, or is invalid for another reason.

    Action: Check the following:

    • Chec k the certificate to determine whether it is valid. If necessary, get a new certificate, inform the sender that her certificate has f ailed, or resend.
    • Check to ensure that the server's wallet has the appropriate trust points to validate the client's ce rtificate. If it does not, then use Oracle Wallet Manager to import the appropriate trust point into the wallet. See "Importing a Trusted Certificate" for details.
    • Ensure that the certificate has not been revoked and that certificate revocation list (CRL) checking is turned on. See "Configuring Certificate Validation with Certificate Revocation Lists"

    ORA-29223: Cannot Create Certificate Chain

    Cause: A certifica te chain cannot be created with the existing trust points for the certificate being installed. Typically, this error is returned when the peer does not give the complete chain and you do not have the appropriate trust points to complete it.

    Action: Use Or acle Wallet Manager to install the trust points that are required to complete the chain. See "Importin g a Trusted Certificate"

    Certificate Validation with Certificate Revocation Lists

    The process of determining whether a given certificate can be used in a given context is referred to as certificate validation. Certificate validation includes determining that

    • A trusted certificate authority (C A) has digitally signed the certificate
    • The certificate's digital signature co rresponds to the independently-calculated hash value of the certificate itself and the certificate signer's (CA's) public key
      • The certificate has not expired
    • The certificate has not been revoked

    The SSL network layer automatically performs t he first three validation checks, but you must configure certificate revocation list (CRL) checking to ensure that certificates have not been revoked. CRLs are signed data structures that contain a list of revoked certificates. They are usually issued and signed by the same entity who issued the original certificate. (See certificate revocation lis ts)

    This section contains the following topics:

    What CRLs Should You Use?

    You should have CRLs for all of the trust points that you honor. The trust points are the trusted certificates from a third party identity that is qualified with a level of trust. Typically, the certificate authorities you trust are called trust points.

    How CRL Checking Works

    Certificate revocation status is checked against CRLs which are located in file system directories, Oracle Internet Directory, or downloaded from the locati on specified in the CRL Distribution Point (CRL DP) extension on the ce rtificate. Typically, CRL definitions are valid for a few days. If you store your CRLs on the local file system or in the directory, then you must update them regularly. If you use CRL DPs then CRLs are downloaded each time a certificate is used so there is no need to regularly refresh the CRLs.

    The server searches for CRLs in the following locations in th e order listed. When the system finds a CRL that matches the certificate CA's DN, it stops searching.

      < li class="LN1" type="1" value="1">Local file system

      The system che cks the sqlnet.ora file for the SSL_CRL_FILE parameter first, followed by the SSL_CRL_PATH par ameter. If these two parameters are not specified, then the system checks the wallet location for any CRLs.

      Note: if you store CRLs on your local file system, then you must use the orapki utility to periodically update them. See "Renaming CRLs with a Hash Value for Certificate Validation"

    1. Oracle Internet Directory

      If the server cannot locate the CRL on the local file system and directory connection information has been configure d in an ldap.ora file, then the server searches in the directory. It searches the CRL subtree by using the CA's distinguished name (DN) and the DN of the CRL subtree.

      See "To create an ldap.ora file for your Oracle home:" (The server must have a properly configured ldap.ora file to search for CRLs in the directory. It cannot use t he Domain Name System (DNS) discovery feature of Oracle Internet Directory.) Also note that if you store CRLs in the directory, then you must use the orapki utility to periodically update them. See "Uploading CRLs to Oracle Internet Directory"

    2. CRL DP

      If the CA specifies a location in the CRL DP X.509, version 3, certificate extension when the certificate is issued, then the appropriate CRL that contains revocation information for that certificate is downloaded. Currentl y, Oracle Advanced Security supports downloading CRLs over HTTP and LDAP.

    See Also: < p class="NB">"Certificate Validation with Certificate Revocation Lists" for information about configuring the client for certificate validation with certificate revocation lists
    Note:
    • For performance reasons, only user certificates are checked.
    • Oracle rec ommends that you store CRLs in the directory rather than the local file system.

    Configuring Certificate Validation with Certificate Revocation Lists

    The S SL_CERT_REVOCATION parameter must be set to REQUIRED or REQUESTED in the sqlnet.ora fil e to enable certificate revocation status checking. By default this parameter is set to NONE indicating that certificate revocation status checking is turned off.

    Note:

    If you want to store CRLs on your local file system or in Oracle Internet Directory, then you must use the command line utility, orapki, to rename CRLs in your file system or upload them to the directory. See: "Certificate Revocation List Management" for inform ation about using orapki.
    To enable certificate revocation status checking for the client or the server:
    1. Navigate to the SSL tab of the Oracle Advanced Security window in Oracle Net Manager, and select either Client or Server for the Configure SSL for: field.

    Figure 7-7 Oracle Advanced Security SSL Window with Certificate Revocation Checking Selected

    Text description of ssl0006. gif follows.

    Text description of the illustration ssl0006.gif

    1. Choose one of the following options from the Revocation Check list (see Figure 7-7):
      • REQUIRED

        Requires certific ate revocation status checking. The SSL connection is rejected if a certificate is revoked or no CRL is found. SSL connections are ac cepted only if it can be verified that the certificate has not been revoked.

      • REQUESTED

        Performs certificate revocation status check ing if a CRL is available. The SSL connection is rejected if a certificate is revoked. SSL connections are accepted if no CRL is foun d or if the certificate has not been revoked.

        Note:

        For performance reasons, only user certificates are checked for revocat ion.
      1. (Optional) If CRLs are stored on your local file system, then set one or both of the following fields that specify where they are stored. These fields are available only when Revocation Check is set to REQUIRED or REQUESTED.
        • Certificate Revocation Lists Path:

          Enter the path to the directory where CRLs are stored, or click Browse to find it by searching the file system. Speci fying this path sets the SSL_CRL_PATH parameter in the sqlnet.ora file. If a path is not specified for this parameter, then the default is the wallet directory. Both DER-encoded (binary format) and PEM-encoded (BASE64) CRLs are supported.

        • Certificate Revocation Lists File:

          Enter the path to a comprehensive C RL file (where PEM-encoded (BASE64) CRLs are concatenated in order of preference in one file), or click Browse to find it by searching the file system. Specifying this file sets the SSL_CRL_FILE parameter in the sqlne t.ora file. If this parameter is set, then the file must be present in the specified location, or else the application will er ror out during startup.

          Note:

          If you want to store CRLs in a local file system directory by setting the Certificate Revocation Lists Path, then you must use the orapki utility to rename them so the system can loca te them. See "Renaming CRLs with a Hash Value for Certificate Validation"
      1. (Optional) If CRLs are fetched from Oracle Internet Directory, then directory server and port information must be specified in an ldap.ora file. See "To create an ldap.ora file for y our Oracle home:"

        Note:

        When configuring your ldap.ora file, you should specify o nly a non-SSL port for the directory. CRL download is done as part of the SSL protocol, and making an SSL connection within an SSL co nnection is not supported.

        Oracle Advanced Security CRL functionality will not work if the O racle Internet Directory non-SSL port is disabled.
    1. Choose File > Save Network Configuration. The sqlnet.ora file is updated.
    To disable certificate revocation status checking:
    1. Navigate to t he SSL tab of the Oracle Advanced Security window in Oracle Net Manager, and select Configure SSL for: Server.
    2. Choose NONE< /strong> from the Revocation Check list.
    3. Choose File > Save Network Configuration. The sqlnet.ora file is updated with the following entry: 
      SSL_CERT_REVOCATION=NONE
      < /a>
      See Also:

      "Troubleshooting Certificate Validation" for information about r esolving certificate validation errors.
    Certificate Revocation List Management

    Before you can enable certificate revocation status checking, you must ensure that the CRLs you receive from the CAs you use are in a form (renamed with a hash value) or in a location (uploaded to the directory) where your sy stem can use them. Oracle Advanced Security provides a command-line utility, orapki, that you can use to perform the fol lowing tasks:

    You can also use LDAP command-line tools to manage CRLs in Oracle Internet Directory.

    See Also:

    Appendix A, "Syntax for Command-Line Tools" in Oracle Internet Directory Application Developer's Guide for information about LDAP command-line tools and their syntax.< /p>

    Displaying orapki Help

    You can display all the orapki commands that are available for managing CRLs by entering the following at the command line:

    orapki crl help

    This command displays all avai lable CRL management commands and their options.

    < /tr>
    Note:

    Using the -summary, -complete, or -w allet command options is always optional. A command will still run if these command options are not specified.

    Renaming CRLs with a Hash Value for Certificate Validation

    Wh en the system validates a certificate, it must locate the CRL issued by the CA who created the certificate. The system locates the ap propriate CRL by matching the issuer name in the certificate with the issuer name in the CRL.

    When you specify a CRL storage location for the Certificate Revocation Lists Path field in Oracle Net Manager (sets the SSL_CRL_PATH parameter in the sqlnet.ora file), use the orapki utility to r ename CRLs with a hash value that represents the issuer's name. Creating the hash value enables the server to load the CRLs.

    On UNIX operating systems, orapki creates a symbolic link to the CRL. On Windows operat ing systems, it creates a copy of the CRL file. In either case, the symbolic link or the copy created by orapki are name d with a hash value of the issuer's name. Then when the system validates a certificate, the same hash function is used to calculate t he link (or copy) name so the appropriate CRL can be loaded.

    Depending on your operating sys tem, enter one of the following commands to rename CRLs stored in the file system.

    To rename CRLs stored in UNIX file systems:
    < dd> 
    orapki crl hash -crl crl_filename [-wallet 
wallet_location] -symlink crl_
directory [-summary]
    To rename CRLs stored in Windows file systems:
    < pre class="CE"> orapki crl hash -crl crl_filename [-wallet walle t_location] -copy crl_directory [-summary]

    where crl_filename is the name of the CRL file, wallet_location is the location of a wa llet that contains the certificate of the CA that issued the CRL, and crl_directory is the directory where the CRL is lo cated.

    Using -wallet and -summary are optional. Specifying - wallet causes the tool to verify the validity of the CRL against the CA's certificate prior to renaming the CRL. Specifying th e -summary option causes the tool to display the CRL issuer's name.

    < h4 class="H3">Uploading CRLs to Oracle Internet Director y

    Publishing CRLs in the directory enables CRL validation through out your enterprise, eliminating the need for individual applications to configure their own CRLs. All applications can use the CRLs stored in the directory where they can be centrally managed, greatly reducing the administrative overhead of CRL management and use.< /p>

    The user who uploads CRLs to the directory by using orapki must be a member of the directory group CRLAdmins (cn=CRLAdmins,cn=groups,%s_OracleContextDN%). This is a privileged operation because these CRLs are accessible to the entire enterprise. Contact your directory administrator to be added to this administrative d irectory group.

    To upload CRLs to the directory, enter the following at the command line:
    orapki crl upload -crl crl_location -ldap hostname:ssl_port -user username 
[-wallet wallet_location] [-summary]

    where crl_location is the file name or URL where the CRL is located, hostname and ssl_port (SSL po rt with no authentication) are for the system on which your directory is installed, username is the directory user who has permission to add CRLs to the CRL subtree, and wallet_location is the location of a wallet that contains the certificate of the CA that issued the CRL.

    Using -wallet and -summary are optional. Spe cifying -wallet causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory. Specifying the -summary option causes the tool to print the CRL issuer's name and the LDAP entry where th e CRL is stored in the directory.

    Note:
    • The orapki utility will prompt you for the directory password when you perform this operation.
    • Ens ure that you specify the directory SSL port on which the Diffie-Hellman-based SSL server is running. This is the SSL port that does n ot perform authentication. Neither the server authentication nor the mutual authentication SSL ports are supported by the orapk i utility.

    Listing CRLs Stored in Oracle Internet Directory

    You can display a list of all CRLs stored in the directory with orapki, which is useful for browsing to locate a particular CRL to view or download to your local system. This command displays the CA who issued the CRL (Issuer ) and its location (DN) in the CRL subtree of your directory.

    To list CRLs in Oracle Internet Directory, enter the following at the command line:
    orapki crl list -ldap hostname:ssl_port

    where the hostname and ssl_< /code>port are for the system on which your directory is installed. Note that this is the directory SSL por t with no authentication as described in the preceding section.


    CRL signature verification failed with RSA status

    Cause: The CRL signature cannot be verified.

    Action: Ensure that the downloaded CRL is issued by the peer's CA and that the CRL was not corrupted when it was downloaded. Note that the orapki utility verifies the CRL before renaming it with a hash value or before uploading it to the directory. See "Certificate Revocation List Management" f or information about using orapki for CRL management.


    CRL dat e verification failed with RSA status

    Cause: The current time is later than the time listed in the next update field. You should not see this error if CRL DP is used. The systems searches f or the CRL in the following order:

    1. File system
    2. Oracle Internet Directory
    3. CRL DP

    The first CRL found in this search may not be the latest.

    Action: Update the CRL with the most recent copy.


    CRL could not be found

    Cause: The CRL could not be found at the configured locations. This will return error ORA-29024 if the configuration speci fies that certificate validation is require.

    Action: Ensure that the CRL locations specified in the configuration are correct by performing the following steps:

    1. Use Oracle Net Manager to check if the correct CRL location is configured. See "Configuring Certificate Validation with Certificate Revocation Lists"
    2. If necessary, use the orapki utility to configure CRLs fo r system use as follows:

    OID hostname or port number not set

    Cause: Oracle Internet Directory (OID) connection information is not set. Note that this is not a fatal error. The search continues with CRL DP.

    Action: If you want to store the CRLs in Oracle Interne t Directory, then use Oracle Net Configuration Assistant to create and configure an ldap.ora file for your Oracle home. See "To create an ldap.ora file for your Oracle home:"


    Fetch CRL from CRL DP: No CRLs found

    Cause: The CRL could not be fetched by using the CRL DP. This happens if the certificate does not hav e a location specified in its CRL DP extension, or if the URL specified in the CRL DP extension is incorrect.

    Action: Manually download the CRL. Then depending on whether you want to store it on yo ur local file system or in Oracle Internet Directory, perform the following steps:

    If you w ant to store the CRL on your local file system:

    1. Use Oracle Net Manager to specify the path to the CRL directory or file. See "Configuring Certificate Validation with Certificate Revocation Lists"
    2. Use the orapki utility to configure the CRL for system use. See "Renaming CRLs with a Hash Value for Certificate Validation"

    I f you want to store the CRL in Oracle Internet Directory:

    1. Use Oracle Net Configuration Assistant to create and configure an ldap.ora file with directory connection in formation. See "To create an ldap.ora file for your Oracle home:"
    2. Use the orapki utility to upload the CRL to the directo ry. See "Uploading CRLs to Oracle Internet Directory"

    Configuring Your System to Use Hardware Security Modules

    Oracle Advanced Security supports hardware security modules that use APIs which conform to the RSA Security, Inc., PKCS #11 s pecification. Typically, these hardware devices are used to securely store and manage private keys in tokens or smart cards, or to ac celerate cryptographic processing.

    This section contains the following topics:

    General Guidelines for Using Hardware Security Modules with Oracle Ad vanced Security

    The following general guidelines apply if you are usi ng a hardware security module with Oracle Advanced Security:

    1. Contact your hardware device vendor to obtain the necessary hardware, software, and PKCS #11 libraries.
    2. Install the hardware, software, and libraries where appropriate for the hardware secu rity module you are using.
    3. Test your hardware security module installat ion to ensure that it is operating correctly. Refer to your device documentation for instructions.
    4. Create a wallet of the type PKCS11 by using Oracle Wallet Manager and specify the absolute p ath to the PKCS #11 library (including the library name) if you wish to store the private key in the token. Oracle PKCS11 wallets contain information that points to the token for private key access.

    You ca n use the wallet containing PKCS #11 information just as you would use any Oracle wallet, except the private keys are stored on the h ardware device and the cryptographic operations are performed on the device as well.

    Configuring Your System to Use nCipher Hardware Security Modules

    Hard ware security modules made by nCipher Corporation are certified to operate with Oracle Advanced Security. These modules provide a sec ure way to store keys and off load cryptographic processing. Primarily, these devices provide the following benefits:

    • Off load of cryptographic processing to free your server to respond to more r equests
    • Secure private key storage on the device
    • Administration of keys controlled through the use of smart cards

    See Also:

    "Creating a Wallet to Store Hardware Security Module Credentials"
    Note:

    You must contact your n Cipher representative to obtain certified hardware and software to use with Oracle Advanced Security.

    Oracle Components Required To Use an nCipher Hardware Security Module

    To use an nCipher hardware security module, you need the following components:

    • nCipher Hardware Security Module
    • Supporting nCipher PKCS #11 library for your platform as follows:
      • (UNIX 32 bit): libcknfast.so library
      • (UNIX 64 bit): libcknfast-64.so li brary
      • (Windows): cknfast.dll library

        < /p>

        Note:

        You mus t contact your nCipher representative to have the hardware security module or the secure accelerator installed and to acquire the nec essary library.

        These tasks must be performed before you can use an nCipher hardware securit y module with Oracle Advanced Security.

    About Installing an nCipher Hardware Security Module

    To use the secure accelerator, you must provide the absolute p ath to the directory that contains the nCipher PKCS #11 library (including the library name) when you create the wallet by using Orac le Wallet Manager. This enables the library to be loaded at runtime. Typically, the nCipher card is installed at the following locati ons:

    • (UNIX) /opt/nfast
    • (Windows) C:\nfast

    The nCipher PKCS #11 lib rary is located at the following file system directory locations for typical installations:

    • (UNIX 32 bit): /opt/nfast/toolkits/pkcs11/libcknfast.so
    • < a name="1024523">(UNIX 64 bit): /opt/nfast/toolkits/pkcs11/libcknfast-64.so
    • (Windows): C:\nfast\toolkits\pkcs11\cknfast.dll

      Note:

      Use the 32-bit library version when us ing the 32-bit release of Oracle Database and use the 64-bit library version when using the 64-bit release of Oracle Database. For ex ample, use the 64-bit nCipher PKCS #11 library for the Oracle Database for Solaris Operating System (SPARC 64-bit).

    Troubleshooting Using Hardware Security Modules

    To detect whether the module is being used, you can turn on Oracle Net tracing. If the wallet contains PKCS #11 information and the priv ate key on the module is being used, then you will see the following entries in the Oracle Net tracing file without error messages lo gged between entry and exit:

    nzpkcs11_Init: entry
nzpkcs11CP_ChangeProviders: entry
nzpkcs11CP_ChangeProviders: exit
nzpkcs11GPK_Ge
tPrivateKey: entry
nzpkcs11GPK_GetPrivateKey: exit
nzpkcs11_Init: exit

...
nzpkcs11_Decrypt: entry
nzpkcs11_Decrypt: exit

nzpkcs11_Sign: entry
nzpkcs11_Sign: exit
    See Also:

    Oracle Net Services Administrator's Guide for informat ion about setting tracing parameters to enable Oracle Net tracing

    Error Messages Associated with Using Hardwa re Security Modules

    The following errors are associated with using PK CS #11 hardware security modules:


    ORA-43000: PKCS11: library not found

    Cause: The system cannot locate the PKCS #11 libra ry at the location specified when the wallet was created. This happens only when the library is moved after the wallet is created.

    Action: Copy the PKCS #11 library back to its original location (w here it was when the wallet was created).


    ORA-43001: PKCS11: token not fou nd

    Cause: The smart card that was used to create the wal let is not present in the hardware security module slot.

    Action: Ensure that the smart card that was used when the wallet was created is present in the hardware security module slot.


    ORA-43002: PKCS11: passphrase is wrong

    Cause: This can occur when

    • An in correct password is specified at wallet creation, or
    • The PKCS #11 device pas sword is changed after the wallet is created and not updated in the wallet by using Oracle Wallet Manager.

    Action: Depending on the cause, take one of the following actions:

    • If you see this error during wallet creation, then check to ensure that you have the correct password and re-enter it.
    • If the password changed after wal let creation, then use Oracle Wallet Manager to open the wallet and enter a new password.

    Note:

    The nCipher log file is in the directory where the module is installed at the following location:

    /log/logfile
    See Also:

    nCipher documentation for further information abou t troubleshooting.
    Go to previous p age
    Previous    		 Go to next page
    Next
    		Oracle
    Copyright © 1996, 2003 Oracle Corporation
    All Rights Reserved.
    Go to Documentation Home
    Home    		 Go to Boo k List
    Book List    		 Go to Table of Contents
    Contents    		 Go to Index
    Index    		 Go to Master Index
    Master Index    		 Go to Feedback page
    Feedback

    Viewing CRLs in Oracle Internet Directory

    You can view specific CRLs that are stored in Oracle Internet Directory in a summarized format or you can request a complete listing of revoked certificates for the specified CRL. A summary listing provides the CRL issuer's name and its v alidity period. A complete listing provides a list of all revoked certificates contained in the CRL.

    To view a summary listing of a CRL in Oracle Int ernet Directory, enter the following at the command line:
    orapki crl
 display -crl crl_location [-wallet wallet_location] -summary
<
/a>

    where crl_location is the location of the CRL in the directory. It is conv enient to paste the CRL location from the list that displays when you use the orapki crl list command. See: "Listing CRLs Stored in Oracle Internet Directory".

    To view a list of all revoked certificates contained in a specified CRL, which is stored in Oracle Internet Directory, enter the following at the command line:< /dt> 
    orapki crl display -crl crl_location [-wallet wallet_location] -complete

    For example, t he following orapki command:

    orapki crl display -crl $T_WORK/pki/wlt_crl/nzcr
l.txt -wallet $T_WORK/pki/wlt_
crl -complete

    produces the followin g output, which lists the CRL issuer's DN, its publication date, date of its next update, and the revoked certificates it contains: 

    issuer = CN=root,C=us, thisUpdate = Sun Nov 16 10:56:58 PST 2003, nextUpdate = 
Mon Sep 30
11:56:58 PDT 2013, revokedCertificates = {(serialNo = 
153328337133459399575438325845117876415, revocationDate - Sun Nov 16 10:56:58

PST 2003)}
CRL is valid

    Using the -wa llet option causes the orapki crl display command to validate the CRL against the CA's certificate.

    Depending on the size of your CRL, choosing the -complete option may take a long time to dis play.

    You can also use Oracle Directory Manager, a graphical user interface tool that is pro vided with Oracle Internet Directory, to view CRLs in the directory. CRLs are stored in the following directory location:

    cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext

    Deleting CRLs from Oracle Internet Direct ory

    The user who deletes CRLs from the directory by using orapk i must be a member of the directory group CRLAdmins. See "Uploading CRLs to Oracle I nternet Directory" for information about this directory administrative group.

    To delete CRLs from the directory, enter the following at the command line:
    orapki crl delete -issuer
issuer_name -ldap host:ssl_port -user username 
[-summa
ry]

    where issuer_name is the name of the CA who issued the CRL, the hostname and ssl_port are for the system on which your directory is installed, and username is the directory user who ha s permission to delete CRLs from the CRL subtree. Note that this must be a directory SSL port with no authentication. See "Uploading CRLs to Oracle Internet Directory" for more information about this port.

    Using the -summary option causes the tool to print the CRL LDAP entry tha t was deleted.

    For example, the following orapki command:

    orapki crl delete -issuer "CN=root,C=us" -ldap machine1:3500 -user cn=orcladmin 
-summary

    produces the following output, which lists the location of the deleted CRL in the direc tory:

    Deleted CRL at cn=root 
cd45860c.rN,cn=CRLValidation,cn=Validation,cn=PKI,cn=Product
s,cn=OracleContext

    Troubleshooting Certificate Validation

    To determine wheth er certificates are being validated against CRLs, you can enable Oracle Net tracing. When a revoked certificate is validated by using CRLs, then you will see the following entries in the Oracle Net tracing file without error messages logged between entry and exit:

    nzcrlVCS_VerifyCRLSignature: entry
nzcrlVCS
_VerifyCRLSignature: exit

nzcrlVCD_VerifyCRLDate: entry
nzcrlVCD_V
erifyCRLDate: exit

nzcrlCCS_CheckCertStatus: entry
nzcrlCCS_CheckC
ertStatus: Certificate is listed in CRL
nzcrlCCS_CheckCertStatus: exit

    Note that when certificate validation fails, the peer in the SSL handshake sees an ORA-29024: Certif icate Validation Failure. If this message displays, see "ORA-29024: Certificate Validation Failur e" for information about how to resolve the error.

    See Also:

    Oracle Net Services Administrator's Guide f or information about setting tracing parameters to enable Oracle Net tracing
    < /a>

    Oracle Net Tracing File Error Me ssages Associated with Certificate Validation

    The following trace mes sages, relevant to certificate validation, may be logged between the entry and exit entries in the Oracle N et tracing file. Oracle SSL looks for CRLs in multiple locations, so there may be multiple errors in the trace.

    Check the following list of possible error messages for information about how to resolve them.