Subject: Configuring NET8 TCP/IP via SSL Creation Date: 13-JUN-2000 PURPOSE ------- This bulletin will show you how the Net8 TCP/IP via SSL Adapter available with Oracle8i V2 Release 8.1.6 can be configured and tested. SCOPE & APPLICATION ------------------- The bulletin is intended for all network administrators dealing with SSL encryption and authentication services provided by Net8 Release 8.1.6. It covers the necessary configuration steps for enabling database connects via the Net8 SSL adapter but it does not cover the Enterprise User Security feature of Oracle8i V2 Release 8.1.6 (see Oracle Advanced Security Administrator's Guide Release 8.1.6, Part III Oracle8i Security/Directory Integration). CONFIGURING NET8 TCP/IP VIA SSL ------------------------------- There are two major configuration steps that need to be done. First you need to obtain SSL certificates for all involved operating system users and second Net8 must be configured for SSL. The third step, configuring the database, is optional. 1. Obtaining SSL certificates from your favorite Certificate Authority (CA) The Oracle Wallet Manager (owm) will generate a ITU X.509 V3 based certificate request which can be sent to your CA. The requested certificate will then be loaded into the wallet manager. 1.1 Start owm as the operating system user who wants to get the certificate and create a wallet: UNIX: $ORACLE_HOME/bin/owm WINNT: Start -> Programs -> Oracle -> Network Administration -> Wallet Manager OWM: Wallet -> New -> Select YES to create the user's default directory -> Enter the user's password -> Select YES to create a certificate request 1.2 Create the PKCS#10 certificate request Mandatory fields are 'Common Name' and 'Country' all others are optional but keep in mind that the resulting distinguished name (DN) of the user's identity must exactly match the global identity when you create a database schema for the user (see 3.2) or, if you plan to use the Enterprise User Security feature, the enterprise user DN configured via the Enterprise Security Manager (not covered in this bulletin). i.e. Common Name = csupport Organization = oss Company = oracle Country = Germany Requested Identity looks like: CN=csupport, OU=oss, O=oracle, C=DE Select also a key size which is supported by your CA. Higher key sizes mean higher security (i.e key size = 512 bits). The request will look like a long string of characters enclosed by "-----BEGIN NEW CERTIFICATE REQUEST-----" and "-----END NEW CERTIFICATE REQUEST-----". Export the request into a file or Cut & Paste everything including the comment lines. Send the request to your CA and make sure that you request a server certificate. If you are asked about Data Integrity choose either MD5 or SHA1. The encryption type is always RSA. The certificate sent back by the CA will look like a long string of characters enclosed by "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". 1.3 Import User Certificate OWM: Operations -> Import User Certificate -> Select the import method -> Paste the certificate or select your certificate file You might get the following message box during import 'User certificate import has failed because the CA certificate doesn't exists. Do you want to import CA certificate now?' This means that the Wallet Manager does not know your CA. In this case you must obtain a Trusted Certificate from your CA also. It has the same format as a user certificate and you can import it right now or later via Operations -> Import Trusted Certificate -> Paste certificate or Open File. If everything works fine you will see the status of your user certificate as ready. 1.4 Save the Wallet OWM: Wallet -> Make sure Auto Login is enabled Wallet -> Save In System Default Under your Wallet Directory UNIX: /etc/ORACLE/WALLETS/ WINNT: \winnt\profiles\\ORACLE\WALLETS you should now find two files ewallet.der <- this is your certificate cwallet.sso <- this means that your wallet is open If the Wallet is closed (no cwallet.sso file) you cannot connect via SSL. 1.5 Working with Wallets Oracle provides two Tools to open or close a users wallet. 1.5.1 The wallet manager Open Wallet: Wallet -> select Auto Login -> Save In System Default -> Exit Close Wallet: Wallet -> deselect Auto Login -> Save In System Default -> Close -> Exit 1.5.2 Enterprise Login Assistant UNIX: $ORACLE_HOME/bin/elogin WINNT: Start -> Programs -> Oracle -> Network Administration -> Enterprise Login Assistant Open Wallet: AutoLogin -> Logout -> red light Close Wallet: AutoLogin -> Login -> Enter Wallet Password -> green light 1.6 You need to repeat steps 1.1 to 1.5 for every operating system user (also for your oracle os user who starts the rdbms instance) who wants to use SSL authentication via NET8. 2. Net8 TCP/IP with SSL configuration Now we need to configure the Net8 client and server files with the Net8 Configuration Assistant. This is very well documented in the Chapter 10 of the Oracle Advanced Security Administrator's Guide Release 8.1.6. In general you need to configure your client and server profile for SSL (locating the user's wallet, choosing the encryption type), create a listener address using TCP/IP via SSL as protocol type (TCPS) and create a Net8 service name using TCPS as protocol type. Below you'll find some sample Net8 files with additional comments: 2.1 Client configuration for SSL: SQLNET.ORA: SSL_CIPHER_SUITES= (SSL_RSA_EXPORT_WITH_RC4_40_MD5) # The cipher suites determines the type of encryption. This is optional # because client and server will determine the highest possible encryption # during SSL handshake. OSS.SOURCE.MY_WALLET = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = c:\winnt\profiles\csupport\ORACLE\WALLETS) ) ) # Every user needs his own Wallet. Therefore it is necessary that every # user has also his own sqlnet.ora file which might be referenced via # TNS_ADMIN environment variable. SSL_CLIENT_AUTHENTICATION = TRUE # The client will be authenticated. This is the default. SQLNET.AUTHENTICATION_SERVICES = (BEQ,TCPS) # TCPS enables the authentication service via SSL NAMES.DIRECTORY_PATH= (TNSNAMES) SQLNET.CRYPTO_SEED = 4fhfguweotcadsfdsafjkdsfqp5f201p45mxskdlfdasf TNSNAMES.ORA O8IV2_SSL = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCPS)(HOST = server)(PORT = 2484)) ) (CONNECT_DATA = (SERVICE_NAME = o8iv2) ) ) # TCPS is the mandatory parameter for the NET8 SSL adapter # The port 2484 is the recommended port for NET8 SSL connect. It must # be the same as on the server. (See corresponding listener.ora below) 2.2 Server configuration for SSL: SQLNET.ORA SSL_CIPHER_SUITES= (SSL_RSA_EXPORT_WITH_RC4_40_MD5) OSS.SOURCE.MY_WALLET = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = /etc/ORACLE/WALLETS/oracle8i) ) ) # This wallet location point to an os users directory. In this case # a UNIX box. SSL_CLIENT_AUTHENTICATION = TRUE # The server will authenticate the client NAMES.DIRECTORY_PATH= (TNSNAMES) SQLNET.CRYPTO_SEED = sdkflk46709lkfjw039436gjotu456gjlkfjw40935i09 LISTENER.ORA OSS.SOURCE.MY_WALLET = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = /etc/ORACLE/WALLETS/oracle8i) ) ) # The listener can use the same wallet as the database as long as it gets # started as the same os user SSL_CLIENT_AUTHENTICATION = FALSE # the listener does not need to authenticate the client because this is done # by the database instance. LISTENER_SSL= (DESCRIPTION_LIST = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCPS)(HOST = server)(PORT = 2484)) ) ) # The port 2484 is the recommended Port for Net8 SSL connections # (see also [NOTE:99721.1] Listening Port numbers) 3. The database The last two configuration steps are optional but will occur in practical situations. If you are going to configure the Enterprise User Security feature which uses Enterprise Roles and Application Schemas in the database to map SSL users to database schemas then do not follow step 3.2 because this will overwrite the Enterprise User Security configuration. 3.1 MTS configuration (optional) If you want to use MTS for SSL connects just add the following line to your MTS parameters within the init.ora file of your instance in order to start two additional dispatchers using the TCPS protocol. mts_dispatchers = "(protocol=TCPS)(DISP=2)" 3.2 Create your SSL users (optional) At last you can create schemas for your SSL users within the database. This is optional because with SSL you can still connect to every database schema identified by a regular password with the additional value of data encryption. But you can also use SSL authentication for your database schemas. In this case you identify your database schema globally with the identity from the user's wallet (see 1.2): create user csupport identified globally as 'cn=csupport, ou=oss, o=oracle, c=DE'; grant connect, resource to csupport; 4. Test it. On the server: a) stop the listener b) stop the instance c) start elogin (Enterprise Login Assistant) and check the if light is green. If necessary choose AutoLogin -> Login and open your wallet using the user's wallet password d) start the listener with the SSL configuration e) start the instance f) execute 'lsnrctl services listener_ssl' and verify that the instance was able to register with the listener. If not then check the init.ora parameter LOCAL_LISTENER if it points to the SSL listener. On the client: a) start the Enterprise Login Assistant and check if the light is green. If necessary choose AutoLogin -> Login and open your wallet using the user's wallet password b) start your application and connect with /@o8iv2_ssl if you have a global database schema for this user or use any available database schema identified by a regular password, i.e. scott/tiger@o8iv2_ssl. c) To verify that you are indeed connected via TCPS check the listener.log file: Your entry should look like 13-JUN-2000 13:56:00 * (CONNECT_DATA=(SERVICE_NAME=o8iv2)(SERVER=SHARED) (CID=(PROGRAM=)(HOST=supsunm3)(USER=csupport))) * (ADDRESS=(PROTOCOL=tcps) (HOST=111.222.333.444)(PORT=49306)) * establish * o8iv2 * 0 5. Troubleshooting 5.1 Typical error messages which might occur: ORA-1004: Default username feature not supported Indicates that your instance was not started with a valid OSS.SOURCE.MY_WALLET sqlnet parameter (see also ORA-28759 below). Also check your sqlnet.ora for the followng entry (see also [NOTE:130037.1]): SQLNET.AUTHENTICATION_SERVICES = (BEQ,TCPS) ORA-1017: invalid username/password If you created a user identified globally check his global identity. It must exactly case match the user's identity from the certificate as seen in the wallet manager. ORA-28759: Failed to open file Check the sqlnet.ora for OSS.SOURCE.MY_WALLET if the directory location for the wallet is correct. Check also the permission on this directory for the user and make sure the a cwallet.sso file is present under this directory. ORA-28786: Decryption of encrypted private key failed This error indicates that the wallet was opened as the wrong os user. If this occurs during listener startup or client connect against a Windows NT server than check whether the Oracle services where started as the right user. This can be done via Control Panel -> Services -> double click on the service (TNSListener or OracleService) -> Log On As -> This Account. It must match the os user who saved the wallet. RELATED DOCUMENTS ----------------- [NOTE:69725.1]: Configuring TNSNAMES.ORA, SQLNET.ORA and LISTENER.ORA [NOTE:130037.1]: ORA-1004 Connecting via SSL as globally identified user Oracle Advanced Security Administrator's Guide Release 8.1.6 Chapter 10, Configuring Secure Socket Layer Authentication