|
 HP Open Source Security for OpenVMS Volume 2:... |
 Installation and Release Notes |
|
|
| |
Legal Caution
SSL data transport requires encryption. Many governments,including the United States, have restrictions on the import andexport of cryptographic algorithms. Please ensure that your useof SSL is in compliance with all national and international lawsthat apply to you.
Shareable Images Containing 64-Bit and 32-BitAPIs Provided
SSL for OpenVMS provides shareable images that contain 64-bitAPIs and shareable images that contain 32-bit APIs. You can choosewhich APIs to use when you compile your application. For more information,see Building an SSL Application.
Linking with HP SSL Shareable Images
If you have written an application that links against theOpenSSL object libraries, you must make a minor change to your codebecause SSL for OpenVMS provides only shareable images. To linkyour application against the shareable images, use code similarto the following:
$ LINK my_app.obj, VMS_SSL_OPTIONS/OPT
where VMS_SSL_OPTIONS.OPT is a text file that contains thefollowing lines:
SYS$SHARE:SSL$LIBCRYPTO_SHR.EXE/SHARESYS$SHARE:SSL$LIBSSL_SHR.EXE/SHARE
Certificate Verification
During the SSL handshake, the SSL Protocol verifies the certificatesby ensuring that the issue date is between the notBefore and notAfter dates,and that the trust settings and purpose are valid. The revocationstatus will not be checked until a version of HP SSL is releasedthat is based on OpenSSL Version 0.9.7, when the proper APIs willbe available.
Preserve Certificates, Keys, and ConfigurationFiles When Upgrading
If you are upgrading from a previous version of Compaq SSLto HP SSL V1.1, you must save the certificates, keys, and configurationfiles in the SSL subdirectory. HP recommends that you back up theseitems to either a different disk and directory or to tape. Whenyou have completed the V1.1 installation, move the saved items backinto the SSL directory structure. Then delete the backed up certificates,keys, and configuration files.
Startup and Shutdown Command Procedure TemplateFiles
In the V1.1 kit, the SYS$STARTUP:SSL$STARTUP.COM and SYS$STARTUP:SSL$SHUTDOWN.COM commandprocedures are named SYS$STARTUP:SSL$STARTUP.TEMPLATE and SYS$STARTUP:SSL$SHUTDOWN.TEMPLATE.This prevents PCSI from overwriting the .COM files, and allows youto preserve any modifications you made to SSL$STARTUP.COM and SSL$SHUTDOWN.COMif you installed a previous release of SSL for OpenVMS.
After you install the V1.1 kit, compare the new .TEMPLATEfiles with your existing SSL$STARTUP.COM and SSL$SHUTDOWN.COM filesand add any new information as required.
If you did not previously install an SSL for OpenVMS kit,both the .TEMPLATE and .COM files are provided.
Configuration files are provided in the same fashion -- both.CNF and .CNF_TEMPLATE files are included in SSL for OpenVMS.
SSL APIs Not Backward Compatible
SSL for OpenVMS is based on open-source code provided by TheOpen Group. The OpenVMS code is based on the 0.9.6G baselevel ofOpenSSL. Until The Open Group releases its Version 1.0 baselevel,The Open Group is not guaranteeing backward compatibility. Thismeans that any OpenSSL API, data structure, header file, command,and the like might be changed in a future version of OpenSSL.
As a result, HP cannot guarantee the backward compatibilityof SSL for OpenVMS until the release of SSL for OpenVMS that isbased on OpenSSL 1.0.0. The shareable images use EQUAL 1,0 whichmeans that applications will have to relink when new shareable imagesare distributed.
Certificate Tool Cannot Have SimultaneousUsers
Only one user/process should use the Certificate Tool at atime. The tool does not have a locking mechanism to prevent unsynchronizedaccesses of the database and serial file.
Protect Certificates and Keys
When you create certificates and keys with the CertificateTool, take care to ensure that the keys are properly protected toallow only the owner of the keys to use them. A private key shouldbe treated like a password. You can use OpenVMS file protectionsto protect the key file, or you can use ACLs to protect individualkey files within a common directory.
SSL$EXAMPLES Logical Name
In SSL V1.1, a new logical, SSL$EXAMPLES, has been added tothe SSL$STARTUP.TEMPLATE command procedure. This logical pointsto the directory SYS$COMMON:[SYSHLP.EXAMPLES.SSL].
DES_CBC_CKSUM Return Value Changed to MatchKerberos
The return value of the DES_CBC_CKSUM API has changed tomatch its intended compatibility with MIT Kerberos. The DES_CBC_CKSUMroutine returns the upper longword of a quadword. The quadworditself was calculated correctly, and has not been changed.
Prior to the change (in Compaq SSL V1.0-B and earlier), theAPI returned the value in the wrong order. For example:
Return value from des_cbc_cksum = 0xaedc29b6In SSL V1.1, the return value is as follows:
Return value from des_cbc_cksum = 0xb629dcaeThis change has been accepted by the OpenSSL.org, and willbe available in the 0.9.7A release of OpenSSL.
DES ImageIncluded in SSL V1.1
In the SSL V1.1, an additional image is being made available,called DES.EXE, which is located in the SSL$EXE directory. Createa foreign symbol to access this new image, as follows:
$ DES :== $SSL$EXE:DES.EXEThe new DES image provides some functionality that is notpresent in the DES subcommand in the OPENSSL command line interface,most notably the ability to enable uuencoding and uudecoding.
Following is the help text for the DES command and the DESsubcommand in the OPENSSL command line interface, which illustratesthe differences between the commands.
$ DES -?'?' unknown flagdes <options> [input-file [output-file]]options:-v : des(1) version number-e : encrypt using SunOS compatible user key to DES key conversion.-E : encrypt-d : decrypt using SunOS compatible user key to DES key conversion.-D : decrypt-c[ckname] : generate a cbc_cksum using SunOS compatible user key to DES key conversion and output to ckname (stdout default, stderr if data being output on stdout). The checksum is generated before encryption and after decryption if used in conjunction with -[eEdD].-C[ckname] : generate a cbc_cksum as for -c but compatible with -[ED].-k key : use key 'key'-h : the key that is entered will be a hexadecimal number that is used directly as the des key-u[uuname] : input file is uudecoded if -[dD] or output uuencoded data if -[eE] (uuname is the filename to put in the uuencode header).-b : encrypt using DES in ecb encryption mode, the default is cbc mode.-3 : encrypt using triple DES encryption. This uses 2 keys generated from the input key. If the input key is less than 8 characters long, this is equivalent to normal encryption. Default is triple cbc, -b makes it triple ecb. $ OPENSSL DES -?unknown option '-?'options are-in <file> input file-out <file> output file-pass <arg> pass phrase source-e encrypt-d decrypt-a/-base64 base64 encode/decode, depending on encryption flag-k key is the next argument-kfile key is the first line of the file argument-K/-iv key/iv in hex is the next argument-[pP] print the iv/key (then exit if -P)-bufsize <n> buffer size-engine e use engine e, possibly a hardware device.Cipher Typesdes : 56 bit key DES encryptiondes_ede :112 bit key ede DES encryptiondes_ede3:168 bit key ede DES encryptionrc2 :128 bit key RC2 encryptionbf :128 bit key Blowfish encryption -rc4 :128 bit key RC4 encryption -des-ecb -des-cbc -des-cfb -des-ofb -des (des-cbc) -des-ede -des-ede-cbc -des-ede-cfb -des-ede-ofb -desx -none -des-ede3 -des-ede3-cbc -des-ede3-cfb -des-ede3-ofb -des3 (des-ede3-cbc) -rc2-ecb -rc2-cbc -rc2-cfb -rc2-ofb -rc2 (rc2-cbc) -bf-ecb -bf-cbc -bf-cfb -bf-ofb -bf (bf-cbc) -cast5-ecb -cast5-cbc -cast5-cfb -cast5-ofb -cast (cast5-cbc)
Environment Variables
OpenSSL environmental variables have two formats, as follows:
Known Problem in Multithreaded, 64-bit Applications
If you are using HP SSL T1.1 with a multithreaded, 64-bitapplication, an ACCVIO occurs when the threads are reaped. Thisproblem is under investigation, and there is no known workaround. The ACCVIO looks similar to the following example:
%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000000000021, PC=00000000000A1558, PS=0000001B Improperly handled condition, image exit forced. Signal arguments: Number = 0000000000000005 Name = 000000000000000C 0000000000000000 0000000000000021 00000000000A1558 000000000000001B Register dump: R0 = 0000000080023488 R1 = 000000000000001B R2 = 0000000000018500 R3 = 0000000000000021 R4 = 0000000000000003 R5 = 000000000003A1C0 R6 = 000000000000008C R7 = 00000000800241C0 R8 = 0000000080023A20 R9 = 0000000000000000 R10 = 0000000000000001 R11 = 0000000000000001 R12 = 0000000000000000 R13 = 0000000000000001 R14 = 0000000000000001 R15 = 0000000000000000 R16 = 0000000080022FE8 R17 = 0000000000000000 R18 = 0000000000100000 R19 = 000000000000000F R20 = 0000000000010680 R21 = 0000000000000003 R22 = 0000000000000001 R23 = 0000000000231B78 R24 = 00000000800569A0 R25 = 0000000000000003 R26 = 00000000000A1558 R27 = 000000007BCD03E0 R28 = 0000000000071E20 R29 = 0000000000231B80 SP = 0000000000231B80 PC = 00000000000A1558 PS = 000000000000001B%CMA-F-EXIT_THREAD, current thread has been requested to exit$
BIND Error in TCP/IP Application
If you are running a TCP/IP-based SSL client/server application,the server occasionally fails to start up, and displays the followingerror message:
bind: address already in useTo avoid this error, use
setsockopt() with SO_REUSEADDR as follows:int on = 1;ret = setsockopt(listen_sock, SOL_SOCKET, SO_REUSEADDR, (void *)&on, sizeof(on));
IDEA and RC5 Symmetric Cipher AlgorithmsNot Supported
The IDEA and RC5 symmetric cipher algorithms are not availablein SSL for OpenVMS. Both of these algorithms are under copyrightprotection, and HP does not have the right to use these algorithms.
If you want to use either of these algorithms, HP recommendsthat you contact RSA Security at the following URL for the licensingconditions of the RC5 algorithm:
http://www.rsasecurity.com
If you want to use the IDEA algorithm, contact Ascom for theirlicense requirements at the following URL:
http://www.ascom.ch
Once you have obtained the proper licenses, download the sourcecode from the following URL:
http://www.openssl.org
Build the product using the command procedure named MAKEVMS.COMprovided in the download.
APIs RAND_egd, RAND_egd_bytes, and RAND_query_egd_bytesNot Supported
The RAND_egd(), RAND_egd_bytes(), and RAND_query_egd_bytes() APIs are not available on OpenVMS.
To obtain a secure random seed on OpenVMS, use the RAND_poll() API.
Compaq C++ V5.5 CANTCOMPLETE Warnings
When you compile programs that contain OpenSSL APIs, CompaqC++ Version 5.5 issues warnings about incomplete classes. This erroroccurs when you use a structure definition before it has been defined.You can resolve these warnings in one of two ways:
$ cxx/list/PREFIX=(ALL_ENTRIES) serv.c struct CRYPTO_dynlock_value *data; ........^ %CXX-W-CANTCOMPLETE, In this declaration, the incomplete class "unnamed struct::CRYPTO_dynlock_value" cannot be completed because it is declared within a class or a function prototype. at line number 161 in file CRYPTO$RES:[OSSL.BUILD_0049_ALPHA_32.INCLUDE.OPENSSL]CRYPTO.H;3
Documentation from the OpenSSL Website
The documentation on the OpenSSL website is under development.It is likely that the API and command-line documentation shippedwith this kit will differ from the documentation on the OpenSSL websiteat some point. If such a situation arises, you should consider theAPI documentation on the OpenSSL website to have precedence overthe documentation included in this kit.
Use Certificate Tool for Certificate andKey Creation
HP recommends the use of the Certificate Tool (SSL$COM:SSL$CERT_TOOL.COM)when creating certificates and keys to test your SSL application.The Certificate Tool provides both ease of use and consistency whencreating your certificates and keys to test and demonstrate yourSSL client and server application.
nsCertType No Longer Written in Certificates
In the SSL T1.0 field test kit, the Certificate Tool incorrectlyset the nsCertType field with both server and client values. Thefield should have been set with one value, either server or client,but not both. In Version 1.0 and higher releases, this field isnot set in the Certificate Tool. Your application is still ableto pass certificates as either server or client certificates, butobject signing cannot be completed with a null nsCertType field.
If object signing is required in your application, see thefollowing paragraphs about setting values in the nsCertType field.
HP recommends that you delete the nsCertType field from theexisting SSL$CONF:SSL$CA.CNF file by editing the file and deletingthe line that begins with nsCertType =.
If you have an application that requires the nsCertType field,edit the file SSL$CONF:SSL$CA.CNF and enter the value that yourapplication requires. For example, if your application needs a certificatewith the client nsCertType field value, enter the following:
nsCertType = client
Valid values for the nsCertType field are server, client,email, objsign, sslCA, emailCA, and objCA.
Extra Certificate Files -- *PEM
When you sign a certificate request using either the CertificateTool or the OpenSSL utility, you may notice that an extra certificateis produced with a name similar to SSL$CRT01.PEM. This certificateis the same as the certificate that you produced with the name youchose. These extra files are the result of the OpenSSL demonstrationCertificate Authority (CA) capability, and are used as a CA accountingfunction. These extra files are kept by the CA and can be used togenerate Certificate Revocation Lists (CRLs) if the certificate becomescompromised.
INDEX.TXT and SERIAL.TXT Location
In the Compaq SSL T1.0 field test kit, INDEX.TXT and SERIAL.TXTwere located in SSL$ROOT:[DEMOCA.PRIVATE]. In Compaq SSL Version1.0 and higher releases, these files are located in SSL$ROOT:[DEMOCA].
The location of INDEX.TXT and SERIAL.TXT is controlled bythe OPENSSL-VMS.CNF file, and consumed by the OpenSSL utility andthe Certificate Tool as part of the OpenSSL demonstration CertificateAuthority (CA) database.
|
|