HP Open Source Security for OpenVMS Volume 2: HP SSL for OpenVMS

Table of Contents

Preface

Intended Audience

Document Structure

Related Documents

Reader's Comments

How to Order Additional Documentation

Conventions

1 Installation and Release Notes

Installation Requirements and Prerequisites

Hardware Prerequisites

Software Prerequisites

Account Quotas and System Parameters

New Features in HP SSL Version 1.3 for OpenVMS

OpenSSL Documentation from The Open Group

Installing HP SSL for OpenVMS Automatically During OpenVMS Installation or Upgrade

Downloading and Installing HP SSL for OpenVMS from Web Site

Before Installing HP SSL for OpenVMS

Installation Procedure

Postinstallation Tasks

After Automatic Installation of HP SSL During OpenVMS Installation or Upgrade

After Download and Installation of HP SSL from Web Site

HP SSL Directory Structure

Building an HP SSL Application

Building an Application Using 64-Bit APIs

Building an Application Using 32-Bit APIs

Release Notes

Legal Caution

HP SSL APIs Not Backward Compatible

Changes to APIs in OpenSSL 0.9.7e

Preserve Configuration Files Before Manually Uninstalling HP SSL

Warning Against Uninstalling HP SSL from OpenVMS Version 8.3 or Higher Using the PRODUCT REMOVE Command

SSL$DEFINE_ROOT.COM Removed From SSL$STARTUP.COM

SSL$STARTUP.TEMPLATE Removed From HP SSL Version 1.3

Configuration Command Procedure Template Files

HP SSL Requirement to Install on System Disk

Shut Down HP SSL Before Installing on Common System Disk

OpenSSL Version Command Displays HP SSL for OpenVMS Version

Shareable Images Containing 64-Bit and 32-Bit APIs Provided

Linking with HP SSL Shareable Images

Certificate Tool Cannot Have Simultaneous Users

Protect Certificates and Keys

Enhancements to the HP SSL Example Programs

SSL$EXAMPLES Logical Name

Environment Variables

IDEA and RC5 Symmetric Cipher Algorithms Not Supported

APIs RAND_egd, RAND_egd_bytes, and RAND_query_egd_bytes Not Supported

Documentation from the OpenSSL Web Site

Extra Certificate Files — *PEM

Known Problem: Certificate Verification with OpenVMS File Specifications

Known Problem: BIND Error in TCP/IP Application

Known Problem: Server Hang in HP SSL Session Reuse Example Program

Known Problem: Compaq C++ V5.5 CANTCOMPLETE Warnings

Problem Corrected: Possible Errors Using PRODUCT REMOVE

Problem Corrected: Error Running OpenSSL Command Line Utility on ODS-5 Disks

Problem Corrected: Attempt to Encrypt within SMIME Subutility Caused Access Violation

Problem Corrected: Race Condition When CRLs are Checked in a Multithreaded Environment

2 Overview of SSL

The SSL Protocol

The SSL Handshake

Public Key Encryption

Certificates

Cipher Suite

Digital Signatures

3 Using the Certificate Tool

Starting the Certificate Tool

Viewing a Certificate

View a Certificate Request File

Create a Certificate Signing Request

Installing Certificates

Create a Self-Signed Certificate

Create a Certificate Authority

Create a Certificate Chain

Creating an Intermediate CA (RA) Certificate

Creating a Client/Server Certificate Signed with an Intermediate CA Certificate

Creating a Certificate Chain File

Sign a Certificate Signing Request

Revoke a Certificate

Create a Certificate Revocation List

Hash Certificates

Hash Certificate Revocations

4 SSL Programming Concepts

HP SSL Data Structures

SSL_CTX Structure

SSL Structure

SSL_METHOD Structure

SSL_CIPHER Structure

CERT/X509 Structure

BIO Structure

Certificates for SSL Applications

Configuring Certificates in the SSL Client and Server

Obtaining and Creating Certificates

SSL Programming Tutorial

Initializing the SSL Library

Creating and Setting Up the SSL Context Structure (SSL_CTX)

Setting Up the Certificate and Key

Creating and Setting Up the SSL Structure

Setting Up the TCP/IP Connection

Setting Up the Socket/Socket BIO in the SSL Structure

SSL Handshake

Transmitting SSL Data

Closing an SSL Connection

Resuming an SSL Connection

Renegotiating the SSL Handshake

Finishing the SSL Application

5 Example Programs

Example Programs Included in HP SSL Kit

Template for Creating Certificates and Keys for the Example Programs

Simple SSL Client Program

Simple SSL Server Program

6 OpenSSL Command Line Interface

Command-Line Help

Standard Commands

Message Digest Commands

Encoding and Cipher Commands

Password Arguments

Creating a DH Parameter (Key) File and a DSA Certificate and Key

OpenSSL Command Line Interface (CLI) Reference

asn1parse() - ASN.1 parsing tool

ca() - sample minimal CA application

ciphers() - SSL cipher display and cipher list tool

config() - OpenSSL CONF library configuration files

crl() - CRL utility

crl2pkcs7() - Create a PKCS#7 structure from a CRL and certificates

dgst() - message digests

dhparam() - DH parameter manipulation and generation

dsa() - DSA key processing

dsaparam() - DSA parameter manipulation and generation

enc() - symmetric cipher routines

gendsa() - generate a DSA private key from a set of parameters

genrsa() - generate an RSA private key

nseq() - create or examine a netscape certificate sequence

ocsp() - Online Certificate Status Protocol utility

openssl() - OpenSSL command line tool

passwd() - compute password hashes

pkcs12() - PKCS#12 file utility

pkcs7() - PKCS#7 utility

pkcs8() - PKCS#8 format private key conversion tool

rand() - generate pseudo-random bytes

req() - PKCS#10 certificate request and certificate generating utility.

rsa() - RSA key processing tool

rsautl() - RSA utility

s_client() - SSL/TLS client program

s_server() - SSL/TLS server program

s_time() - SSL/TLS performance timing program

sess_id() - SSL/TLS session handling utility

smime() - S/MIME utility

speed() - test library performance

spkac() - SPKAC printing and generating utility

verify() - Utility to verify certificates.

version() - print OpenSSL version information

x509() - Certificate display and signing utility

CRYPTO Application Programming Interface (API) Reference

ASN1_OBJECT_new() - object allocation functions

ASN1_STRING_dup() - ASN1_STRING utility functions

ASN1_STRING_new() - ASN1_STRING allocation functions

ASN1_STRING_print_ex() - ASN1_STRING output routines.

bio() - I/O abstraction

BIO_ctrl() - BIO control operations

BIO_f_base64() - base64 BIO filter

BIO_f_buffer() - buffering BIO

BIO_f_cipher() - cipher BIO filter

BIO_f_md() - message digest BIO filter

BIO_f_null() - null filter

BIO_f_ssl() - SSL BIO

BIO_find_type() - BIO chain traversal

BIO_new() - BIO allocation and freeing functions

BIO_push() - add and remove BIOs from a chain.

BIO_read() - BIO I/O functions

BIO_s_accept() - accept BIO

BIO_s_bio() - BIO pair BIO

BIO_s_connect() - connect BIO

BIO_s_fd() - file descriptor BIO

BIO_s_file() - FILE bio

BIO_s_mem() - memory BIO

BIO_s_null() - null data sink

BIO_s_socket() - socket BIO

BIO_set_callback() - BIO callback functions

BIO_should_retry() - BIO retry functions

blowfish() - Blowfish encryption

bn() - multiprecision integer arithmetics

BN_add() - arithmetic operations on BIGNUMs

BN_add_word() - arithmetic functions on BIGNUMs with integers

BN_bn2bin() - format conversions

BN_cmp() - BIGNUM comparison and test functions

BN_copy() - copy BIGNUMs

BN_CTX_new() - allocate and free BN_CTX structures

BN_CTX_start() - use temporary BIGNUM variables

BN_generate_prime() - generate primes and test for primality

bn_mul_words() - BIGNUM library internal functions

BN_mod_inverse() - compute inverse modulo n

BN_mod_mul_montgomery() - Montgomery multiplication

BN_mod_mul_reciprocal() - modular multiplication using reciprocal

BN_new() - allocate and free BIGNUMs

BN_num_bits() - get BIGNUM size

BN_rand() - generate pseudo-random number

BN_set_bit() - bit operations on BIGNUMs

BN_swap() - exchange BIGNUMs

BN_zero() - BIGNUM assignment operations

BUF_MEM_new() - simple character arrays structure

CONF_modules_free() - OpenSSL configuration cleanup functions

CONF_modules_load_file() - OpenSSL configuration functions

crypto() - OpenSSL cryptographic library

CRYPTO_set_ex_data() - internal application specific data functions

d2i_ASN1_OBJECT() - ASN1 OBJECT IDENTIFIER functions

d2i_DHparams() - PKCS#3 DH parameter functions.

d2i_DSAPublicKey() - DSA key encoding and parsing functions.

d2i_PKCS8PrivateKey_bio() - PKCS#8 format private key functions

d2i_RSAPublicKey() - RSA public and private key encoding functions.

d2i_X509() - X509 encode and decode functions

d2i_X509_ALGOR() - AlgorithmIdentifier functions.

d2i_X509_CRL() - PKCS#10 certificate request functions.

d2i_X509_NAME() - X509_NAME encoding functions

d2i_X509_REQ() - PKCS#10 certificate request functions.

d2i_X509_SIG() - DigestInfo functions.

DES_random_key() - DES encryption

Modes() - the variants of DES and other crypto algorithms of OpenSSL

dh() - Diffie-Hellman key agreement

DH_generate_key() - perform Diffie-Hellman key exchange

DH_generate_parameters() - generate and check Diffie-Hellman parameters

DH_get_ex_new_index() - add application specific data to DH structures

DH_new() - allocate and free DH objects

DH_set_default_method() - select DH method

DH_size() - get Diffie-Hellman prime size

dsa() - Digital Signature Algorithm

DSA_do_sign() - raw DSA signature operations

DSA_dup_DH() - create a DH structure out of DSA structure

DSA_generate_key() - generate DSA key pair

DSA_generate_parameters() - generate DSA parameters

DSA_get_ex_new_index() - add application specific data to DSA structures

DSA_new() - allocate and free DSA objects

DSA_set_default_method() - select DSA method

DSA_SIG_new() - allocate and free DSA signature objects

DSA_sign() - DSA signatures

DSA_size() - get DSA signature size

engine() - ENGINE cryptographic module support

err() - error codes

ERR_clear_error() - clear the error queue

ERR_error_string() - obtain human-readable error message

ERR_get_error() - obtain error code and data

ERR_GET_LIB() - get library, function and reason code

ERR_load_crypto_strings() - load and free error strings

ERR_load_strings() - load arbitrary error strings

ERR_print_errors() - print error messages

ERR_put_error() - record an error

ERR_remove_state() - free a thread's error queue

evp() - high-level cryptographic functions

EVP_BytesToKey() - password based encryption routine

EVP_MD_CTX_init() - EVP digest routines

EVP_CIPHER_CTX_init() - EVP cipher routines

EVP_OpenInit() - EVP envelope decryption

EVP_PKEY_new() - private key allocation functions.

EVP_PKEY_set1_RSA() - EVP_PKEY assignment functions.

EVP_SealInit() - EVP envelope encryption

EVP_SignInit() - EVP signing functions

EVP_VerifyInit() - EVP signature verification functions

HMAC() - HMAC message authentication code

lh_stats() - LHASH statistics

lh_new() - dynamic hash table

MD2() - MD2, MD4, and MD5 hash functions

MDC2() - MDC2 hash function

OBJ_nid2obj() - ASN1 object utility functions

OpenSSL_add_all_algorithms() - add algorithms to internal table

OPENSSL_config() - simple OpenSSL configuration functions

OPENSSL_load_builtin_modules() - add standard configuration modules

OPENSSL_VERSION_NUMBER() - get OpenSSL version number

PEM() - PEM routines

PKCS12_create() - create a PKCS#12 structure

PKCS12_parse() - parse a PKCS#12 structure

PKCS7_decrypt() - decrypt content from a PKCS#7 envelopedData structure

PKCS7_encrypt() - create a PKCS#7 envelopedData structure

PKCS7_sign() - create a PKCS#7 signedData structure

PKCS7_verify() - verify a PKCS#7 signedData structure

rand() - pseudo-random number generator

RAND_add() - add entropy to the PRNG

RAND_bytes() - generate random data

RAND_cleanup() - erase the PRNG state

RAND_egd() - query entropy gathering daemon

RAND_load_file() - PRNG seed file

RAND_set_rand_method() - select RAND method

RC4_set_key() - RC4 encryption

RIPEMD160() - RIPEMD-160 hash function

rsa() - RSA public key cryptosystem

RSA_blinding_on() - protect the RSA operation from timing attacks

RSA_check_key() - validate private RSA keys

RSA_generate_key() - generate RSA key pair

RSA_get_ex_new_index() - add application specific data to RSA structures

RSA_new() - allocate and free RSA objects

RSA_padding_add_PKCS1_type_1() - asymmetric encryption padding

RSA_print() - print cryptographic parameters

RSA_private_encrypt() - low level signature operations

RSA_public_encrypt() - RSA public key cryptography

RSA_set_default_method() - select RSA method

RSA_sign() - RSA signatures

RSA_sign_ASN1_OCTET_STRING() - RSA signatures

RSA_size() - get RSA modulus size

SHA1() - Secure Hash Algorithm

SMIME_read_PKCS7() - parse S/MIME message.

SMIME_write_PKCS7() - convert PKCS#7 structure to S/MIME format.

CRYPTO_set_locking_callback() - OpenSSL thread support

UI_new() - New User Interface

des_read_password() - Compatibility user interface functions

X509_NAME_add_entry_by_txt() - X509_NAME modification functions

X509_NAME_ENTRY_get_object() - X509_NAME_ENTRY utility functions

X509_NAME_get_index_by_NID() - X509_NAME lookup and enumeration functions

X509_NAME_print_ex() - X509_NAME printing routines.

X509_new() - X509 certificate ASN1 allocation functions

SSL Application Programming Interface (API) Reference

d2i_SSL_SESSION() - convert SSL_SESSION object from/to ASN1 representation

SSL() - OpenSSL SSL/TLS library

SSL_accept() - wait for a TLS/SSL client to initiate a TLS/SSL handshake

SSL_alert_type_string() - get textual description of alert information

SSL_CIPHER_get_name() - get SSL_CIPHER properties

SSL_clear() - reset SSL object to allow another connection

SSL_COMP_add_compression_method() - handle SSL/TLS integrated compression methods

SSL_connect() - initiate the TLS/SSL handshake with an TLS/SSL server

SSL_CTX_add_extra_chain_cert() - add certificate to chain

SSL_CTX_add_session() - manipulate session cache

SSL_CTX_ctrl() - internal handling functions for SSL_CTX and SSL objects

SSL_CTX_flush_sessions() - remove expired sessions

SSL_CTX_free() - free an allocated SSL_CTX object

SSL_CTX_get_ex_new_index() - internal application specific data functions

SSL_CTX_get_verify_mode() - get currently set verification parameters

SSL_CTX_load_verify_locations() - set default locations for trusted CA certificates

SSL_CTX_new() - create a new SSL_CTX object as framework for TLS/SSL enabled functions

SSL_CTX_sess_number() - obtain session cache statistics

SSL_CTX_sess_set_cache_size() - manipulate session cache size

SSL_CTX_sess_set_new_cb() - provide callback functions for server side external session caching

SSL_CTX_sessions() - access internal session cache

SSL_CTX_set_cert_store() - manipulate X509 certificate verification storage

SSL_CTX_set_cert_verify_callback() - set peer certificate verification procedure

SSL_CTX_set_cipher_list() - choose list of available SSL_CIPHERs

SSL_CTX_set_client_CA_list() - set list of CAs sent to the client when requesting a client certificate

SSL_CTX_set_client_cert_cb() - handle client certificate callback function

SSL_CTX_set_default_passwd_cb() - set passwd callback for encrypted PEM file handling

SSL_CTX_set_generate_session_id() - manipulate generation of SSL session IDs (server only)

SSL_CTX_set_info_callback() - handle information callback for SSL connections

SSL_CTX_set_max_cert_list() - manipulate allowed for the peer's certificate chain

SSL_CTX_set_mode() - manipulate SSL engine mode

SSL_CTX_set_msg_callback() - install callback for observing protocol messages

SSL_CTX_set_options() - manipulate SSL engine options

SSL_CTX_set_quiet_shutdown() - manipulate shutdown behaviour

SSL_CTX_set_session_cache_mode() - enable/disable session caching

SSL_CTX_set_session_id_context() - set context within which session can be reused (server side only)

SSL_CTX_set_ssl_version() - choose a new TLS/SSL method

SSL_CTX_set_timeout() - manipulate timeout values for session caching

SSL_CTX_set_tmp_dh_callback() - handle DH keys for ephemeral key exchange

SSL_CTX_set_tmp_rsa_callback() - handle RSA keys for ephemeral key exchange

SSL_CTX_set_verify() - set peer certificate verification parameters

SSL_CTX_use_certificate() - load certificate and key data

SSL_do_handshake() - perform a TLS/SSL handshake

SSL_free() - free an allocated SSL structure

SSL_get_ciphers() - get list of available SSL_CIPHERs

SSL_get_client_CA_list() - get list of client CAs

SSL_get_current_cipher() - get SSL_CIPHER of a connection

SSL_get_default_timeout() - get default session timeout value

SSL_get_error() - obtain result code for TLS/SSL I/O operation

SSL_get_ex_data_X509_STORE_CTX_idx() - get ex_data index to access SSL structure from X509_STORE_CTX

SSL_get_ex_new_index() - internal application specific data functions

SSL_get_fd() - get file descriptor linked to an SSL object

SSL_get_peer_cert_chain() - get the X509 certificate chain of the peer

SSL_get_peer_certificate() - get the X509 certificate of the peer

SSL_get_rbio() - get BIO linked to an SSL object

SSL_get_session() - retrieve TLS/SSL session data

SSL_get_SSL_CTX() - get the SSL_CTX from which an SSL is created

SSL_get_verify_result() - get result of peer certificate verification

SSL_get_version() - get the protocol version of a connection.

SSL_library_init() - initialize SSL library by registering algorithms

SSL_load_client_CA_file() - load certificate names from file

SSL_new() - create a new SSL structure for a connection

SSL_pending() - obtain number of readable bytes buffered in an SSL object

SSL_read() - read bytes from a TLS/SSL connection.

SSL_rstate_string() - get textual description of state of an SSL object during read operation

SSL_SESSION_free() - free an allocated SSL_SESSION structure

SSL_SESSION_get_ex_new_index() - internal application specific data functions

SSL_SESSION_get_time() - retrieve and manipulate session time and timeout settings

SSL_session_reused() - query whether a reused session was negotiated during handshake

SSL_set_bio() - connect the SSL object with a BIO

SSL_set_connect_state() - prepare SSL object to work in client or server mode

SSL_set_fd() - connect the SSL object with a file descriptor

SSL_set_session() - set a TLS/SSL session to be used during TLS/SSL connect

SSL_set_shutdown() - manipulate shutdown state of an SSL connection

SSL_set_verify_result() - override result of peer certificate verification

SSL_shutdown() - shut down a TLS/SSL connection

SSL_state_string() - get textual description of state of an SSL object

SSL_want() - obtain state information TLS/SSL I/O operation

SSL_write() - write bytes to a TLS/SSL connection.

A Data Structures and Header Files

Header Files

SSL_CTX Structure

SSL Structure

SSL_METHOD Structure

SSL_SESSION Structure

SSL_CIPHER Structure

BIO Structure

X509 Structure

B New and Changed APIs in OpenSSL 0.9.7d and 0.9.7e

New AES APIs in OpenSSL 0.9.7e

New CRYPTO APIs in OpenSSL 0.9.7e

Changed DES APIs in OpenSSL 0.9.7e

New EVP APIs in OpenSSL 0.9.7e

New SSL APIs in 0.9.7d

Changed SSL APIs in 0.9.7d

C Open Source Notices

OpenSSL Open Source License

Original SSLeay License

Index