OpenVMS Notes: SSL • TLS • OpenSSL

  1. The information presented here is intended for educational use by qualified OpenVMS technologists.
  2. The information presented here is provided free of charge, as-is, with no warranty of any kind.
Edit: 2021-03-26

(a simple) Introduction to SSL/TLS for OpenVMS people

The name game (part-1)

ssl basic connectivity
  1. SSL (secure sockets layer) is a communication protocol developed by Netscape Communications and RSA Data Security to add privacy and security to internet communications

    • original work by Diffie and Hellman (two Stanford academics) was done in 1976
    • original work by RSA (three MIT academics: Rivest, Shamir and Adleman) was done in 1977 but wasn't publicly described until 1995 during the creation of VeriSign
    • a lot of this stuff was tied together by Taher Elgamal who was then working at Netscape
       
  2. Versions:
    1. SSLv1 (a.k.a. SSL1 and SSL-1) was a proof-of-concept which was never released
    2. SSLv2 (a.k.a. SSL2 and SSL-2.0) was released in 1995 and considered by many to be a work in progress. For example, it does not support client authentication
    3. SSLv3 (a.k.a. SSL3 and SSL-3.0) was released in 1996 and adds support for client authentication as well as additional ciphers
    4. TLSv1.0 (1999)
      The fourth revision was so important that the name was changed to TLS (transport layer security) even though many people today think of TLSv1.0 as SSLv4 if not SSLv3.1. From a programmer's view, some of the API labels and data structures were changed. This was done so new SSL applications are unable to accidentally link to older SSL libraries. The new TLS stack supports older SSL protocols (if enabled) which are implemented with newer code
      A few more details:
      1. The main reason for changing the API begins with an unintentional security bug. Before the sale of Netscape to AOL in 1999, Netscape published much of their source code into the Mozilla Project (an open source software site). A short time later, a paranoid programmer at company name deleted modified the SSL library so it would would execute a random number function three additional times during key generation. Apparently, the programmer inadvertently used a 32-bit variable rather than a 64-bit variable which had the unintended effect of reducing the effective key size by 50% and reducing the effective key space by 75%. This code was then published through the Mozilla Project and no one knows how much of it escaped into the wild. Shortly after the revelation, many software publishers quickly realized it was better to introduce security changes cooperatively through the IETF (Internet Engineering Task Force) where more eyes get to see the code before it is published. The TLS stack represents the efforts of IETF (e.g. TLS is an IETF standards track protocol)
      2. The aforementioned bug may not be as obvious as you may might think. Remember that everything in the API was originally written in C which is the only truly portable computer programming language. Rumor has it that the programmer who broke SSL declared "a 32-bit variable" thinking it was "a 64-bit variable" so it's a classic case of the computer doing exactly as it was told.
        As HAL-9000 once said: "This sort of thing has cropped up before, and it has always been due to human error".
        I am not sure if the programmer "thought long meant 64-bit because he was on a native 64-bit architecture" or "was unaware of the fact that long long is required to declare a 64-bit variable". This is why the IETF changed the type of that variable to uint64_t (unsigned integer 64-bit) which is now the source of much frustration as new programmers learn the c-language.
      3. I have always thought that long long was a really dumb idea for a number of reasons with the main one being that you would need to know that the mainframe definition of long meant 32-bit while word meant 16-bit. How many programmers have encountered the terms quadword (64-bit) and octaword (128-bit)? So perhaps the IETF solution is the least confusing after all.
    5. TLSv1.1 (2006)
    6. TLSv1.2 (2008)
    7. TLSv1.3 (2018)
      • Some computer professionals have commented that this protocol has changed significantly so should be relabeled TLSv2.0
         
  3. SSL/TLS is now used in numerous other places like:
    •  communicating securely with a POP3 server over TCP port 995 (the default insecure port is 110)
    • FTPS (FTP over SSL) which must not be confused with SFTP (FTP over SSH)
       
  4. Server authentication (mandatory) is one way that a client can ensure the server is who it claims to be.
     
  5. Client authentication (optional) is one way that a server can ensure the client system is who it claims to be. In the early days of e-commerce, a credit card was thought to be the only necessary piece of client identification but how will you communicate securely without making a credit-card purchase?
     
  6. OpenSSL is (primarily) a C-language library used to implement:
    1. the Secure Socket Layer (SSL) protocol. This facilitates the implementation of SSL into software without needing to reinvent the wheel every time a developer needs to do so.
    2. a library of cryptographic functions meant to encrypt as well as decrypt. This means you do not need to set up an SSL connection in order to just use the cryptographic library
    3. a CLI (command line interface) tool for:
      1. testing library functionality (which can also be used as a training tool)
      2. testing SSL/TLS connectivity
      3. key generation
      4. certificate generation
      5. generating hashes

A 3-km (10,000 foot) Overview of SSL

SSL/TLS cryptography is based upon:

  1. symmetric key cryptography (session keys)
    • symmetric key algorithms both encrypt and decrypt data using a single key
    • messaging with an asymmetric key
      • in 2015 the minimum key-size is usually 2048 bits which is a lot like using a binary pass-phrase 256 characters in length
  2. asymmetric key cryptography (e.g. public key cryptography)
    • public key algorithms employ a pair of asymmetric keys which have a mathematical relationship to each other
    • key-1 (also called the public key) is normally used to encrypt
      • contrary to what you might think, key-1 is much larger than key-2 (from the theory: it is the product of two very large primes)
    • key-2 (also called the private key) is normally used to decrypt
    • asymmetric messaging is much more computationally expensive than symmetric messaging, so ...
    • The initial SSL handshake begins with asymmetric keys which are primarily used to:
      • conceal the handshake of the shared secret which produces the "symmetric key" (also known as the "session key")
      • conceal the dialog where client and server agree on a particular cipher
      • ensure that only the designated receiver can read the message
      • optionally, ensure that the designated sender is who he claims to be
    • From this point on only the symmetric "session key" is used to encrypt/decrypt the channel data
  3. cryptographic hash functions
  4. message authentication codes (MAC)
  5. digital signatures
A few more details
  • If Bob wants to send to Alice (Eve is a potential eavesdropper)
    • Bob acquires Alice's public certificate which contains Alice's public key (theory: this key is the product of two primes)
    • Bob uses Alice's public key to encrypt the message then sends it to Alice
    • Alice uses her private key to decrypt the message. Only she can do this (because she has never made it public).
      *** stuff to keep you awake at night ***
      Only she can do this in real time. But if you can make a T-connection, then...
      • Anyone with a supercomputer along with a database of "pre-computed primes" and "partial solutions" would be able to keep up in real-time (e.g. rather than attempt to factor a public key into its products in real-time, just do a look-up)
      • Similarly, anyone "able to record the whole conversation" would (eventually) be able to read the message off-line using a traditional computer
      • Anyone at a corporate firewall could keep up: https://www.bluecoat.com/inspect-your-ssl-traffic
Document Signing
  • If Bob wants to send a message to Alice with proof it come from him (signing)
    • Bob encrypts the message using his private key (only he can do this since his private key was never made public)
    • Bob encrypts again using Alice's public key then sends to Alice
    • Alice decrypts using her private key (only she can do this since her private key was never made public)
    • Alice decrypts again using Bob's public key (message must have come from Bob because it was encrypted with Bob's private key)
  • From this point on only the symmetric "session key" is used to encrypt/decrypt the channel data

Trusted Third Parties

  • How does a client ensure that the designated server is who he claims to be and not some man-in-the-middle with a bogus certificate?
    • The server's certificate (which contains the server's public key) is issued by a trusted third party also called a certificate authority or CA
    • The authority signs (encrypts) the server's certificate with the authority's private key which anyone can decrypt by obtaining the authority's public key from the authority's certificate
      • Think "government Issued passports" where you trust the passport holder based upon the reputation of the issuer
    • *** stuff to keep you awake at night ***
      • who signed the authority's certificate?
        • In an ideal world, authority-x might sign for authority-y who might sign for authority-z (but this is not the usual behavior of competitors in a capitalistic marketplace)
        • Many times, a large CA will employ a self-signed certificate (then you just say "I trust that authority"). Because of this limitation, self-signed CA certificates are not usually fetched from the internet. For example, the browser you are using to read this article might have several hundred certificates loaded into the root cache (BTW, many times a browser update will be updating or deleting entries in this cache).

OpenSSL on OpenVMS

On an OpenVMS system you could find SSL in one, or more, locations depending upon your setup:

  • LOCATION #1 :: Apache (CSWS)
     
    a Fully baked into Apache module "mod_ssl.exe" apache$common:[modules]mod_ssl.exe
    b Before OpenVMS-8.4 you might find a copy of the OpenSSL CLI utility under
    Apache root (or Apache common) primarily for creating CSRs specific to Apache
    apache$common:[openssl.exe]
    c This application has its own DCL-based certificate tools but should consider only
    using tools under ssl$root:[000000]
    apache$common:[000000]apache$cert_tool.com
    apache$common:[openssl.com]
     
    Use this method to display the SSL software fully baked into your web server:
    Legend (for all my examples):
    <sr>		= system response
    <ur>		= user response
    <enter>		= hit the enter key (in my newer examples this is assumed)
    <ctrl-c>	= hit "control c"
    <ctrl-z>	= hit "control z"
    <space>		= hit the space bar
    <tab>		= hit the tab key
    -------------------------------------------------------------------------
    Procedure for TCPware:
    <sr> $									! my DCL prompt
    <ur> telnet www.bellics.net 80<enter>					! telnet to server on port 80 (using TCPware)
    <sr> %TCPWARE_TELNET-I-TRYING, trying bellics.com,http (207.35.137.66,80) ...
         %TCPWARE_TELNET-I-ESCCHR, escape (attention) character is "^\"
    <ur> HEAD / HTTP/1.0<enter>						! request default HEAD using HTTP/1.0
         <enter>								! blank line ends the HTTP header (signals: start)
    <sr> HTTP/1.1 200 OK							! server response: "I can do HTTP/1.1" and "success"
         Date: Fri, 22 Jun 2012 23:02:15 GMT				! server current date + time
         Server: Apache/2.0.63 (OpenVMS) mod_ssl/2.0.63 OpenSSL/0.9.8h	! "server type" and "feature list"
         Last-Modified: Thu, 13 Aug 2009 16:59:51 GMT			! requested page was modified at this date/time
         ETag: "c357e-3dc-dd296fc0"						! optional line to support caching
         Accept-Ranges: bytes						! server can accept bytes
         Connection: close							! connection closed because we requested HTTP/1.0
         Content-Type: text/html						! requested page is in HTML format
    -------------------------------------------------------------------------
    Procedure for MultiNet:
    <sr> $									!
    <ur> telnet www.bellics.net /port=80<enter>				! telnet to server on port 80 (using MultiNet)
    <sr> bla...

     
  • LOCATION #2 :: As an optional standalone client-side OpenSSL package which is always present with OpenVMS 8.3 and higher.
    It only supports OpenSSL-0.9 and lower. (see the next item for information about OpenSSL-1.0 and higher on OpenVMS systems)
    This application has its own DCL-based certificate tools (see: ssl$com:ssl$cert_tool.com)
    Installation of this package will deposit example C programs here: ssl$examples
     
    Use this DCL command to check for it on your system:
    <sr>	$
    <ur>	product show product ssl
    <sr>
    	------------------------------------ ----------- ---------
    	PRODUCT                              KIT TYPE    STATE
    	------------------------------------ ----------- ---------
    	HP AXPVMS SSL V1.4-471               Full LP     Installed
    	------------------------------------ ----------- ---------
    	$

    On OpenVMS 8.x the ciphers built into OpenSSL are now also used for things like "validation of patch kits" as well as "encrypting backup save sets" to only name two applications or many. But the primary purpose of this package is to provide SSL/TLS capabilities for your client software which does not run under your Apache. It also provides command line tools to help technical people debug SSL/TLS connections to remote servers.
     
  • LOCATION #3 :: As an optional standalone client-side OpenSSL package which is only available with OpenVMS 8.4 patch-kit 1200 and higher.
    It only supports OpenSSL-1.0 and higher (click here to learn more about the HP NAME GAME)
    This application has its own DCL-based certificate tools (see: ssl1$com:ssl1$cert_tool.com)
    Installation of this package will deposit example C programs here: ssl1$examples
     
  • I just mentioned that both Apache on OpenVMS and OpenSSL on OpenVMS have their own CERT TOOLS. By default, they also have their own certificates and this might not be what you want. I ran into some problems in 2012 involving a gSOAP application which employed the PUSH-PUSH method (remote clients use https to push requests to a gSOAP service on my Apache server which immediately returns a response); no problem here since this all happens under Apache. A short time later, a local stand-alone client uses https to push a reply back to the requesting server (my Apache is not involved); Initially I was using two different certificate caches (and SSL engines) which caused security people at the remote end (a different company) to raise an eyebrow of concern. Here is an HP-recommended method to have both subsystems use the same certificates on OpenVMS systems:
     
    1. all "our" production certificate files are located in this read-only directory on the system disk:

      sys$sysdevice:[certificates]

    2. a system-wide logical name (vms_cert_dir) is defined (in script "sys$manager:systartup_vms.com") to reference the certificate directory:

      $ define/system  vms_cert_dir  sys$sysdevice:[certificates]

    3. Apache config files like apache$common[.conf]ssl.conf must reference certificates via the logical name vms_cert_dir
    4. before experimenting with the certificate tools in directory SSL$COM you might consider copying production certificates to SSL$CERTS
    5. while certificates can be generated directly from the OpenSSL CLI, DCL scripts provided by HPE are less prone to error (at least for occasional users). But I am of the opinion that every computer professional should be familiar with the OpenSSL CLI
    6. If you use these scripts to make self-signed certificates (only recommended on local intranet sites; not the public internet) then then make sure you modify script opensll_self_cert.com changing all instances of 365 days to 1825 or 3650 or you'll drive your users crazy as these need to be manually installed in browser certificate repositories (changes to IE11 in 2015 make this a little more difficult than you would expect). Of course, individual VMS users may still use personalized certificates stored in their local directories.
      Self-signed Caveats:
      • Newer versions of Chrome refuse to work with self-signed certificates.
      • How will an AJAX call on port 443 deal with a self-signed certificate warning in Chrome?
    7. As a self-signed work around
      1. create a CA (Certificate Authority) which includes a key and self-signed cert
        • starting 2016: ensure you create a unique CN (Common Name)
          comment: in my hacks I used "ICSIS CA"
      2. create a v3 CSR
        • starting 2016: ensure you create a unique CN (Common Name)
          comment: in my hacks I used "ICSIS LEAF (DVLP)"
        • one, or more, DNS entries should be placed in the SAN (SubjectAltName) rather than the CN
      3. use the CA-cert to sign the CSR which creates a CRT
        • ensure you enable v3 extensions
        • ensure you include -extfile with directives to process SAN entries
More VMS-Specific Information:
  1. The CERT TOOL under the standalone SSL product(s) can also be used to create documents for Apache 
  2. All CERT TOOLS are written via DCL scripts but call the OpenSSL CLI (command line interface) program.
    Caveat: I think Compaq (the company that added internet software to OpenVMS before Compaq merged with HP) made a huge mistake by hiding the OpenSSL CLI in this fashion. I suggest everyone learn how to use this tool directly. Why?
    1. You never know when you will find yourself doing SSL work on another OS with no DCL script to help you
    2. Not all openssl subcommands are available from the DCL script. For example, s_client is invaluable for debugging connections to other systems while s_server can be used by programmers to test their own SSL-based client software.
       
  3. Why have 1-3 versions of SSL on your system? As mentioned earlier, openssl is baked-into Apache and used by anything served-up by Apache (secure web page, secure soap service, etc). But what if you need a standalone SSL-based client  to communicate with a distant SSL-based server? Answer: Your compiled application is linked to the SSL run-time libraries associated with the standalone OpenSSL package.
     
  4. On 2012-02-14 I realized that the command openssl s_client does not work properly with OpenVMS kit HP-OpenSSL-1.4-453
    • Symptom: After using s_client to successfully make a secure connection (which works), sending data through the secure connection appears to work but you will not be able to view the response.
    • The bug is found in all HP versions starting with HP-OpenSSL-1.2 (December 2004) and running through HP-OpenSSL-1.4-467 (June 2012).
    • The bug is not found on CPQ-OpenSSL-1.1B which was the last version published by Compaq
    • The bug only affects Alpha and Itanium since there were no official SSL releases for VAX after CPQ-OpenSSL-1.1B
    • All CLI examples listed below work properly with OpenSSL implementations on Linux, Macintosh OS-X, Solaris, Windows but not OpenVMS
    • The problem was reported to HP in March 2012 but their latest kit (June 2012) still contains the bug and it looks like this will not be fixed until 2013.
    • Click here for more information including how to build your own fix (requires a C compiler and HP's SSL Source Code Kit)
    • Excerpt from 2006 manual: HP Open Source Security for OpenVMS Volume 2: HP SSL for OpenVMS
      • http://h41379.www4.hpe.com/doc/83final/ba554_90007/rn01re25.html (page title: s_client)
      • quote from section: Restrictions
        "Because this program has a lot of options and also because some of the techniques used are rather old,
         the C source of s_client is rather hard to read and not a model of how things should be done. A typical
         SSL client program would be much simpler"
      • NSR comments:
        1. I agree with HP on this statement. The authors of s_client.c should be shot for producing something which would have been rejected by every introductory programing course (many claim it is difficult to write spaghetti logic in the c-language; s_client.c proves otherwise). To make matters worse, this program underwent subsequent feature development without any programmers doing a code cleanup (probably everyone threw up their hands in bewilderment). This program is now so large and ugly that it appears nearly impossible to do a rewrite without breaking something.
        2. While s_client.c is of little use as an example program, the user community still needs it as a connectivity diagnostic tool
           
  5. On 2013-03-07 HP released HP-OpenSSL-1.4-471 and it appears that OpenSSL s_client now works properly. Yay!

The OpenSSL CLI (command line interpreter)

note: Connecting Windows to OpenVMS? Click here for Windows instructions

The OpenSSL CLI (command line interpreter) exists for the following reasons:
  1. to prove the underlying routines and libraries work properly (the developers of OpenSSL use this feature all the time)
     
  2. creating certificate signing requests (and associated keys), self-signed certificates, etc.
     
  3. Testing client-server connectivity
    1. can you connect at all?
    2. is there an SSL handshake after you connect?
    3. is there something wrong with the far-end server certificate?
    4. is the far-end server requesting a client certificate (this is usually optional) but would be an error if you have not defined one
    5. are near-end certificates usable?
    6. is your client trusted certificate chain usable?
    7. is a cipher missing?
       
    comments:
    1. Browsers will hide error information only presenting an error icon. Using OpenSSL CLI as a test tool will present details for you to begin failure-mode analysis.
    2. Modern OpenVMS servers have no modern browsers so the OpenSSL CLI will be the only tool to get you out of most jams.
      p.s. one of our systems sits behind a firewall with the server's IP address gen'd into a firewall ACL (Access Control List). If we wanted to use a PC to debug some weird connectivity problem we would need to unplug the server from the network then replace it with a properly configured PC. Since we run 24/7 this is not possible
     
  4. As a teaching tool
    • use s_client to connect to Google or Twitter (they won't mind)
    • use s_client to connect to your Apache web server
    • Hacker Heaven: connect any two platforms end-to-end; one running s_server while the other running s_client
      • if you are on a really tight budget, run the client and server sessions from two different command-line sessions on the same computer system
      • click here for more details
         
  5. Proves that the underlying SSL library routines are functional (your SSL-based client software will link to the OpenSSL libraries; if the CLI programs work properly and your client software does not, then the problem most likely exists in your code)
     
  6. As a tool to test client (or server) software you just wrote
     
  7. CLI source code, as well as the example programs, can be used to teach you how to write an SSL program (although s_server.c and s_client.c are in horrible shape; and whoever wrote s_client.c should be forced to endure the embarrassment of a public code review)

Official OpenSSL Documentation

Apps and Tools

HP OpenSSL Documentation for OpenVMS

UNIX notation on OpenVMS?
Openssl.exe on OpenVMS appears to have been built with all the DECC logical names required to enable UNIX compatibility in the C-RTL. This means that passing UNIX-style file specifications to openssl.exe like this:
    certs/index
will be treated like this on an OpenVMS system:
    [.certs]index.
Even more neat/strange things can be viewed in file ssl$root:[000000]openssl-vms.conf

Example 1: OpenSSL introductory stuff

OpenVMS caveats:
1) DCL (Digital Command Language) is the default command Line interpreter for OpenVMS
2) in DCL, comments begin with an exclamation (!)
3) in DCL, use a dash (-) as a line continuation character
4) unlike Unix or Linux systems, your DCL account is probably set up to be "case insensitive"
which will complicate these demos. I suggest you switch over your account to "case sensitive".
change to sensitive: $SET PROC/CASE=SENS/PARSE=EXTEN
return to default: $SET PROC/CASE=BLIND/PARSE=TRAD
5) If you do not switch to "case sensitive" then you will need to do the following: a) double-quote upper-case or mixed-case parameters like -CApath , -CAfile , -WWW b) use properly cased file names (eg. the "$create" command will always create an upper-case
filename even if you typed a lower-case filename

Like most security software, OpenSSL seems deliberately unfriendly so does not include verbose help. You must read the official CLI docs or type something illegal then hope for the best.

Legend (for all my examples):
<sr>		= system response
<ur>		= user response
<enter>		= hit the enter key (in my newer examples this is "assumed")
<ctrl-c>	= hit "control c"
<ctrl-z>	= hit "control z"
<space>		= hit the space bar
<tab>		= hit the tab key
# = start of BASH comment
\ = line continuation character in BASH -------------------------------------------------------- <sr> $ ! this is my DCL prompt <ur> openssl ! start the OpenSSL CLI application <sr> OpenSSL> ! this is the application prompt <ur> version ! display version (add -a for all) <sr> OpenSSL 0.9.8y 5 Feb 2013 ! SSL for OpenVMS V1.4 Mar 7 2013. ! OpenSSL> ! <ur> help ! request help (an illegal command) <sr> openssl:Error: 'help' is an invalid command. ! ...major topics and sub-topics are displayed... ! read this stuff OpenSSL> ! application prompt <ur> s_client -help ! request s_client specific help <sr> unknown option -help ! usage: s_client args ! ...s_client arguments are displayed... ! OpenSSL> ! <ur> exit ! exit to DCL <sr> $ ! my DCL prompt

Example 2: pseudo-commands

<ur>	openssl list-standard-commands			!
<sr>	{ displays available commands (like s_client) }	! read this
	$						!
<ur> openssl list-message-digest-commands ! <sr> { displays available digests } ! read this $ !
<ur> openssl list-cipher-commands ! <sr> { display available ciphers } ! read this $ !
<ur> openssl no-rsa ! is 'rsa' available? <sr> rsa ! yes, 'rsa' is available $ !
<ur> openssl no-dsa ! is 'dsa' available? <sr> dsa ! yes, 'dsa' is available $ !
<ur> openssl no-yada ! is 'yada' available? <sr> no-yada ! no, 'yada' is not available $ !

Example 3: delving deeper (what ciphers are available?)

<ur>	openssl ciphers -?				!
<sr>	usage: ciphers args
	 -v	- verbose mode, a textual listing of the SSL/TLS ciphers in OpenSSL
	 -V	- even more verbose (OpenVMS users should enter -"V" to preserve case)
	 -ssl2	- SSL2 mode
	 -ssl3	- SSL3 mode
	 -tls1	- TLS1 mode
	$
<ur> openssl ciphers -ssl2 ! display available + enabled ssl2 ciphers <sr> bla...bla...bla... ! might be an error message in 2014 $
<ur> openssl ciphers -ssl3 ! display available + enabled ssl3 ciphers <sr> bla...bla...bla... ! might be an error message in 2020 $
<ur> openssl ciphers -tls1 ! display available + enabled tls1 ciphers <sr> bla...bla...bla... ! $
<ur> openssl ciphers -v ! display all available + enabled ciphers <sr> bla...bla...bla... ! 100 lines is typical $
<ur> pipe openssl ciphers -v | search sys$input SSL3 ! display SSL3-related stuff <sr> bla...bla...bla... ! 60 lines is typical $
<ur> pipe openssl ciphers -v | search sys$input TLS1 ! display TLS1-related stuff bla...bla...bla... ! 35 lines is typical $

OpenSSL CLI :: non-connection examples

1) This content of this section is more of an academic/pedagogical nature
2) Click skip this section if you are in a hurry to solve a connectivity problem
3) The following examples manipulate files rather than data streams but you will get the general idea 4) Anything typed into the OpenSSL CLI can also be done from the OpenSSL C-API

Cryptographic Exercises

exercise-01 "encrypt with base64"
=================================
<sr>	$								! my DCL prompt
<ur>	create hack1a.txt<enter>					! use DCL to create a new message file
	These are the voyages of the starship Enterprise<ctrl-z>	! type this phrase; hit CTRL-z to exit
<sr>	exit
	$
<ur> openssl enc -base64 -in hack1a.txt ! encrypt using base64 (out to screen) <sr> VGhlc2UgYXJlIHRoZSB2b3lhZ2VzIG9mIHRoZSBzdGFyc2hpcCBFbnRlcnByaXNl Cg== $
<ur> openssl enc -base64 -in hack1a.txt -out hack1b.txt ! repeat command but output to a file <sr> $ ! no news is good news :-)
<ur> openssl enc -base64 -d -in hack1b.txt ! now decrypt the file <sr> These are the voyages of the starship Enterprise ! success... $ Notes: 1) As Philippe Camacho properly pointed out, while "base64" is listed as a cipher, it is not a form of secret encryption since it does not support the use of a secret key. But it does prove that this part
of the CLI is working properly when "base64" is treated as a module. 2) type "openssl list-cipher-commands" to see a list of ciphers offered by your installed product. Notice that the listing does include "base64" 3) One of the ciphers is "des3" which we will use in the next exercise 4) Newer versions of OpenSSL also include "base64" as a command to use in place of "enc"


exercise-02 "encrypt with des3"
===============================
<sr>	$								! my DCL prompt
<ur>	create hack2a.txt<enter>					! create a new file
	To boldly go where no man has gone before<ctrl-z>		! type this phrase; ctrl-z to exit
<sr>	exit								!
	$
<ur>	openssl enc -des3 -in hack2a.txt -out hack2b.bin		! encrypt file using des3 (output to file)
<sr>	enter des-ede3-cbc encryption password:				! prompt for a mandatory KEY
<ur>	secret789<enter>						! you will be typing this blind (no echo)
<sr>	Verifying - enter des-ede3-cbc encryption password:		! this is for KEY verification
<ur>	secret789<enter>						! you will be typing this blind (no echo)
<sr>	$								! no news is good news :-)
<ur> dump hack2b.bin ! more hacking... <sr> EAF669D0 D6C86018 CC300C75 DD7A3780 30873EFA 104F8F21 5F5F6465 746C6153 Salted__!.O.ú>.0.7zŸu.0Ì.`ÈÖ.iöê 000000 6AB157A8 8AC290FF 7BDE9AA4 7D9155E5 FED1AFB4 BC213EAE E1E7357C 3B9A5362 bS.;|5çá.>!¼..Ñ.åU.}...{..Â.¤W±j 000020 00000000 00000000 00000000 00000000 00000000 00000000 65B18A6C 86FADB6E nÛú.l.±e........................ 000040 $
note: <<< numbers are right-to-left <<< | >>> ascii is left-to-right >>>
<ur> openssl enc -des3 -d -in hack2b.bin ! decrypt the message file (out to screen) <sr> enter des-ede3-cbc decryption password: ! prompt for a KEY <ur> secret789<enter> ! you will be typing this blind (no echo) <sr> To boldly go where no man has gone before ! yay! $
<ur> openssl enc -des3 -d -in hack2b.bin -k secret789 ! decrypt without prompting <sr> To boldly go where no man has gone before ! $
<ur> openssl enc -des3 -d -in hack2b.bin -k "secret789" ! double quotes work as well <sr> To boldly go where no man has gone before $
<ur> create hack2c.txt<enter> ! create a third file secret789<ctrl-z> ! enter the pass phrase into the file <sr> exit $
<ur> openssl enc -des3 -d -in hack2b.bin -pass file:hack2c.txt ! decrypt without prompting (password file) <sr> To boldly go where no man has gone before $ <ur> openssl enc -des3 -d -in hack2b.bin -pass pass:secret789 ! decrypt without prompting (inline password) <sr> To boldly go where no man has gone before $ Notes: 1) the "encryption password" is really a KEY used to both encrypt and decrypt 2) be very careful when you enter the pass phrase because some hidden characters (like <tab> and <space>) are processed as-is; for example, these are all legal, but different, inputs a) secret789<space> b) secret789<space><space> c) <space>secret789<space> d) <tab>secret789<space> 3) if you enter any double-quote characters at the interactive passphrase prompt they will be used to encrypt! But it will be impossible to decrypt using the -k option which first strips quotes before processing (yikes)
4) Notice the embedded phrase "Salted__" which is always present. Salt (randomized 64-bit data stored in the file)
 is combined with pepper (data not stored in the file (the pass phrase)) to cause every encryption of the same
data to produce different results. This used to stop dictionary hacks. Try it your self: every time you type
"openssl enc -des3" you will produce a different result. Now go back and store just a lower case 'a' as plain text
then use a lower case 'a' as the pass phrase. The result will always contain 24-bytes.
5) Note: SALT is really a combination of the IV + the key which is generated from the passphrase


*** And Now For a Little Theory ***

RSA Notes:
	1) RSA encryption/decryption is asymmetric and so requires two keys (one public, one private)
	2) RSA keys are based upon upon the product of two carefully chosen prime numbers
	3) https://en.wikipedia.org/wiki/RSA_(cryptosystem)
RSA Data:	
	d = private key
	n = public key
	e = 65537	(constant with RSA)
	c = m^e mod n	(formula for cipher text)
m = c^d mod n (formula for message text)


exercise-03 "create a new 32-bit key"
=====================================
Notes:	32-bits is too small for a certificate but okay for this demo on primes

<sr>	$							! my DCL prompt
<ur>	openssl genrsa -out hack3a.key 32			! create a small 32-bit key
<sr>	Generating RSA private key, 32 bit long modulus
	.+++++++++++++++++++++++++++
	.+++++++++++++++++++++++++++
	e is 65537 (0x10001)
	$
<ur>	openssl rsa -in hack3a.key -text -noout			! interpret the key file 
	Private-Key: (32 bit)
	modulus: 4057358269 (0xf1d65fbd)			! 32-bit public key
	publicExponent: 65537 (0x10001)				! same every time
	privateExponent: 1322158157 (0x4ece884d)
	prime1: 65123 (0xfe63)					! different every genrsa
	prime2: 62303 (0xf35f)					! different every genrsa
	exponent1: 51313 (0xc871)
	exponent2: 47415 (0xb937)
	coefficient: 60666 (0xecfa)
	$

Notes:	65123 x 62303 = 4057358269				! public key (product of two primes)


exercise-04 "create a new 512-bit key (store it in a file)"
===========================================================
<sr>	$							! my DCL prompt
<ur>	openssl genrsa -out hack4a.key 512			! 512 bits just for this demo
<sr>	Generating RSA private key, 512 bit long modulus
	......++++++++++++
	.....++++++++++++
	e is 65537 (0x10001)
	$
<ur>	type hack4a.key						! view raw ASCII data
<sr>	-----BEGIN RSA PRIVATE KEY-----
	MIIBOgIBAAJBAKIwjuJiJJalNN6uQYW+JAn26uipqT8/VvDNIGhqJDxrI2wMj5sN
	cWn5MmQsZFdl/pxioQvlsdFb8Idk1ZsLc9kCAwEAAQJAVVzTRyk6cqM/AVibmcWq
	eCgiGRR6xJQUsSZ1QR9kNPukKeW7wOw/rhJgbO+xZXgzJ6zg06+nNg4UOCsUOUyg
	kQIhAMv1pMCsvNHGjm/IfI/8Z+6FP5kFJVrEWrGApYEgfjw9AiEAy5KQhuH3DYm1
	H3W9AhZb0VjyFpsjn0ZDCdM5GpnKg80CIAosbZRiyWRZWB+BS51PBMwj/2EdnZhi
	dPenqBnByiotAiBbcnt6HAffDP1QJJPDXEfiwxH9FbPq2KVExJ3iVTOkAQIhAMvF
	pY+dUiDSWk6sC1MX+fASe/Eu5oA9CV0q7BLNt/VQ
	-----END RSA PRIVATE KEY-----
	$
<ur>	openssl rsa -in hack4a.key -text -noout			! interpret the key file
<sr>	Private-Key: (512 bit)					! means this is a private key file
	modulus:						! but this is our public key
	00:a2:30:8e:e2:62:24:96:a5:34:de:ae:41:85:be:		! "00:" is just padding
	24:09:f6:ea:e8:a9:a9:3f:3f:56:f0:cd:20:68:6a:
	24:3c:6b:23:6c:0c:8f:9b:0d:71:69:f9:32:64:2c:
	64:57:65:fe:9c:62:a1:0b:e5:b1:d1:5b:f0:87:64:
	d5:9b:0b:73:d9						! 64 x 8 = 512 bits
	publicExponent: 65537 (0x10001)
	privateExponent:
	55:5c:d3:47:29:3a:72:a3:3f:01:58:9b:99:c5:aa:
	78:28:22:19:14:7a:c4:94:14:b1:26:75:41:1f:64:
	34:fb:a4:29:e5:bb:c0:ec:3f:ae:12:60:6c:ef:b1:
	65:78:33:27:ac:e0:d3:af:a7:36:0e:14:38:2b:14:
	39:4c:a0:91
	prime1:
	00:cb:f5:a4:c0:ac:bc:d1:c6:8e:6f:c8:7c:8f:fc:
	67:ee:85:3f:99:05:25:5a:c4:5a:b1:80:a5:81:20:
	7e:3c:3d
	prime2:
	00:cb:92:90:86:e1:f7:0d:89:b5:1f:75:bd:02:16:
	5b:d1:58:f2:16:9b:23:9f:46:43:09:d3:39:1a:99:
	ca:83:cd
	exponent1:
	0a:2c:6d:94:62:c9:64:59:58:1f:81:4b:9d:4f:04:
	cc:23:ff:61:1d:9d:98:62:74:f7:a7:a8:19:c1:ca:
	2a:2d
	exponent2:
	5b:72:7b:7a:1c:07:df:0c:fd:50:24:93:c3:5c:47:
	e2:c3:11:fd:15:b3:ea:d8:a5:44:c4:9d:e2:55:33:
	a4:01
	coefficient:
	00:cb:c5:a5:8f:9d:52:20:d2:5a:4e:ac:0b:53:17:
	f9:f0:12:7b:f1:2e:e6:80:3d:09:5d:2a:ec:12:cd:
	b7:f5:50
	$

Certificate Exercises / Examples

exercise-05 "create a CSR (certificate signing request)"
========================================================
note:	use the 512-bit key file just created in exercise-04

<sr>	$								! my DCL prompt
<ur>	copy SSL$ROOT:[000000]OPENSSL-VMS.CNF	openssl.cnf		! copy template to your directory
<sr>	$
<ur>	openssl req -new -key hack4a.key -out hack5b.csr -config openssl.cnf
<sr>	You are about to be asked to enter information that will be incorporated
	into your certificate request.
	What you are about to enter is what is called a Distinguished Name or a DN.
	There are quite a few fields but you can leave some blank
	For some fields there will be a default value,
	If you enter '.', the field will be left blank.
	-----
	Country Name (2 letter code) [AU]:CA				! my responses are in red 
	State or Province Name (full name) [Some-State]:Ontario
	Locality Name (eg, city) []:Waterloo
	Organization Name (eg, company) [Internet Widgits Pty Ltd]:United Federation of Planets
	Organizational Unit Name (eg, section) []:Star Fleet
	Common Name (eg, YOUR name) []:Jean-Luc Pickard			! or: www.server.com
	Email Address []:jean-luc.picard@star-fleet.ufp
	Please enter the following 'extra' attributes
	to be sent with your certificate request
	A challenge password []:<enter>
	An optional company name []:<enter>
	$
<ur>	type hack5b.csr							! view CSR as raw ASCII data
<sr>	-----BEGIN CERTIFICATE REQUEST-----
	MIIBdDCCAR4CAQAwgbgxCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdPbnRhcmlvMREw
	DwYDVQQHEwhXYXRlcmxvbzElMCMGA1UEChMcVW5pdGVkIEZlZGVyYXRpb24gb2Yg
	UGxhbmV0czETMBEGA1UECxMKU3RhciBGbGVldDEZMBcGA1UEAxMQSmVhbi1MdWMg
	UGlja2FyZDEtMCsGCSqGSIb3DQEJARYeamVhbi1sdWMucGljYXJkQHN0YXItZmxl
	ZXQudWZwMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAKIwjuJiJJalNN6uQYW+JAn2
	6uipqT8/VvDNIGhqJDxrI2wMj5sNcWn5MmQsZFdl/pxioQvlsdFb8Idk1ZsLc9kC
	AwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAILOaqUUSsb0vgTyXqUKsBi12mgSbsLgu
	rZEEyu0gSsTdVIkkwkVvhavYpxCENbCqiRxH+uHZLkYvbTTfmvUapA==
	-----END CERTIFICATE REQUEST-----
	$
<ur>	openssl req -noout -text -in hack5b.csr				! view interpreted CSR data
<sr>	Certificate Request:
	Data:
	Version: 0 (0x0)
	Subject:Subject: C=CA, ST=Ontario, L=Waterloo,
		O=United Federation of Planets, OU=Star Fleet,
		CN=Jean-Luc Pickard/emailAddress=jean-luc.picard@star-fleet.ufp
	Subject Public Key Info:
	Public Key Algorithm: rsaEncryption
	RSA Public Key: (512 bit)
	Modulus (512 bit):						! public key
	00:a2:30:8e:e2:62:24:96:a5:34:de:ae:41:85:be:
	24:09:f6:ea:e8:a9:a9:3f:3f:56:f0:cd:20:68:6a:
	24:3c:6b:23:6c:0c:8f:9b:0d:71:69:f9:32:64:2c:
	64:57:65:fe:9c:62:a1:0b:e5:b1:d1:5b:f0:87:64:
	d5:9b:0b:73:d9
	Exponent: 65537 (0x10001)
	Attributes:
	a0:00
	Signature Algorithm: sha1WithRSAEncryption
	20:b3:9a:a9:45:12:b1:bd:2f:81:3c:97:a9:42:ac:06:2d:76:
	9a:04:9b:b0:b8:2e:ad:91:04:ca:ed:20:4a:c4:dd:54:89:24:
	c2:45:6f:85:ab:d8:a7:10:84:35:b0:aa:89:1c:47:fa:e1:d9:
	2e:46:2f:6d:34:df:9a:f5:1a:a4
	$


exercise-06 "create a self-signed certificate"
caveat: Chrome began rejecting these in 2016
========================================================
<sr>	$						! my DCL prompt
<ur>	openssl req			-		! this is a signing request
		-new			-		!
		-x509			-		! x509 as a switch indicates "self signed"
		-config openssl.cnf	-		! use this config file
		-days 365		-		! this will expire in one year
		-set_serial 20160101	-		! Here I used ccyymmdd
		-key hack4a.key		-		! I could have created/used a new key with -keyout
		-out hack6b.crt				! certificate data will be written here
<sr>	You are about to be asked to enter information that will be incorporated
	into your certificate request.
	What you are about to enter is what is called a Distinguished Name or a DN.
	There are quite a few fields but you can leave some blank
	For some fields there will be a default value,
	If you enter '.', the field will be left blank.
	-----
	Country Name (2 letter code) [AU]:CA				! my responses in RED (CA=Canada)
	State or Province Name (full name) [Some-State]:Ontario		! Canada has provinces
	Locality Name (eg, city) []:Waterloo
	Organization Name (eg, company) [Internet Widgits Pty Ltd]:United Federation of Planets
	Organizational Unit Name (eg, section) []:Star Fleet
	Common Name (eg, YOUR name) []:Jean-Luc Pickard			! or: www.server.com
	Email Address []:jean-luc.picard@star-fleet.ufp			!
	$
<ur>	openssl x509 -in hack6b.crt -text -noout			! let's see it (processed)
<sr>	Certificate:
	    Data:
	        Version: 3 (0x2)
	        Serial Number: 20160101 (0x1339e65)
	        Signature Algorithm: sha1WithRSAEncryption
	        Issuer: C=CA, ST=Ontario, L=Waterloo,
			O=United Federation of Planets,
			OU=Star Fleet,
			CN=Jean-Luc Pickard/emailAddress=jean-luc.picard@star-fleet.ufp
	        Validity
	            Not Before: Jan  1 21:06:15 2016 GMT
	            Not After : Dec 31 21:06:15 2016 GMT
	        Subject: C=CA, ST=Ontario, L=Waterloo,
			O=United Federation of Planets,
			OU=Star Fleet,
			CN=Jean-Luc Pickard/emailAddress=jean-luc.picard@star-fleet.ufp
	        Subject Public Key Info:
	            Public Key Algorithm: rsaEncryption
	            RSA Public Key: (512 bit)
	                Modulus (512 bit):
	                    00:a2:30:8e:e2:62:24:96:a5:34:de:ae:41:85:be:
	                    24:09:f6:ea:e8:a9:a9:3f:3f:56:f0:cd:20:68:6a:
	                    24:3c:6b:23:6c:0c:8f:9b:0d:71:69:f9:32:64:2c:
	                    64:57:65:fe:9c:62:a1:0b:e5:b1:d1:5b:f0:87:64:
	                    d5:9b:0b:73:d9
	                Exponent: 65537 (0x10001)
	        X509v3 extensions:
	            X509v3 Subject Key Identifier:
	                83:79:4A:B8:D5:ED:C4:C5:58:A8:4B:0F:07:E6:8B:FB:A3:22:19:9C
	            X509v3 Authority Key Identifier:
	                keyid:83:79:4A:B8:D5:ED:C4:C5:58:A8:4B:0F:07:E6:8B:FB:A3:22:19:9C
	                DirName:/C=CA/ST=Ontario/L=Waterloo
				/O=United Federation of Planets
				/OU=Star Fleet
				/CN=Jean-Luc Pickard/emailAddress=jean-luc.picard@star-fleet.ufp
	                serial:01:33:9E:65

	            X509v3 Basic Constraints:
	                CA:TRUE
	    Signature Algorithm: sha1WithRSAEncryption
	        08:36:67:15:01:c4:8c:e6:2d:10:de:ed:bb:13:4f:cb:9d:4f:
	        9a:c9:8b:61:ee:84:16:e8:9b:0f:db:a5:05:c7:d5:94:e6:9b:
	        b1:0f:40:d5:bc:be:09:75:5e:7a:33:46:f7:3a:4c:c2:8b:61:
	        c2:85:ad:a0:f2:cf:00:d2:e1:0d
	$
<ur>	type hack6b.crt							! let's see it (raw)
<sr>	<...hex dump...>						!


exercise-7 "certificates: compound operations, private companies AND development platforms"

operations:
1) create a CA (certificate authority) key
2) create a CA (certificate authority) certificate with v3 extensions
3) create a CSR (certificate signing request) with v3 extensions
4) use the CA certificate to sign the CSR with v3 extensions
=====================================================================
coming soon (it works on my server)
	-or-
follow the steps documented here:
    https://www.feistyduck.com/library/openssl-cookbook/
    Starts on page 39 of the free PDF

OpenSSL CLI :: connection examples

Example 3: Using "s_client" to connect to public sites

Notes:

  1. the following examples are for machines directly connected to the internet. Firewalls and proxy servers present additional challenges 
  2. if the following commands do not work on your OpenVMS system then read this caveat
  3. here we use ssl3 because it is much more lenient than any version of  tls
    caveat: most web sites disabled support for ssl3 in 2014 (see: POODLE) but twitter still supports it in 2020

Connecting to Twitter

<sr>	$								! my DCL prompt
<ur>	openssl s_client -connect www.twitter.com:443 -ssl3		! connect to Twitter
<sr>	...handshake verbage...						! bla...bla...bla...
	---								! your s_client prompt
<ur>	GET / HTTP/1.0<enter>						! get default document; use HTTP 1.0
	<enter>								! signal end of HTTP header
<sr>	HTTP/1.0 200 OK							! response
	Date: Fri, 22 Jun 2012 23:16:38 GMT				!
	Status: 200 OK							!
	Pragma: no-cache						!
	Content-Type: text/html; charset=utf-8				!

Connecting to Google USA (non-USA sites will be redirected)

<sr>	$								!
<ur>	openssl s_client -connect www.google.com:443 -ssl3		! connect to Google USA
<sr>	...handshake verbage...						! bla...bla...bla...
	---								! your s_client prompt
<ur>	GET / HTTP/1.0<enter>						! get default document; use HTTP 1.0
	<enter>								! signal end of HTTP header
<sr>	HTTP/1.0 302 Found						! 302 = moved
	Location: https://www.google.ca/				! so redirect to Canada
	Cache-Control: private
	Content-Type: text/html; charset=UTF-8
	Set-Cookie: expires=; expires=Mon, 01-Jan-1990 00:00:00 GMT; path=/; domain=www.google.com

Connecting to Google Canada (non-Canadian sites will be redirected)

<sr>	$								!
<ur>	openssl s_client -connect www.google.ca:443 -ssl3		! connect to Google Canada
	...handshake verbage...						! bla...bla...bla...
	---								! your s_client prompt
<ur>	GET / HTTP/1.1<enter>						! okay so let's try HTTP/1.1
	host: www.google.ca:443<enter>					! need this line for HTTP/1.1
	<enter>								! signal end of HTTP header 
<sr>	HTTP/1.1 200 OK							!
	Set-Cookie: NID=61=H7WfG9OQ6uHDvVU8OJyt_Z4x8a4cj0DUpLUfH9D9eeKVou1FwaP8ok16
	vDlgV3sX1JPzrd3G8tNc3mDgbdPZy8mGnmpKJ3WCKHVT6gbCV8Z56rKIVgXokgJkptJZ-i00;
	expires=Sat, 22-Dec-2012 22:51:17 GMT; path=/; domain=.google.ca; HttpOnly
	Date: Fri, 22 Jun 2012 22:51:17 GMT
	Expires: -1
	Cache-Control: private, max-age=0
	Content-Type: text/html; charset=windows-1252
	Set-Cookie: PREF=ID=3ba285f540771657:FF=0:TM=1340405477:LM=1340405477:S=TpABG903GxV7Ufhg;	
		expires=Sun, 22-Jun-2014 22:51:17 GMT; path=/; domain=.google.ca
	Set-Cookie: NID=61=H7WfG9OQ6uHDvVU8OJyt_Z4x8a4cj0DUpLUfH9D9eeKVou1FwaP8ok16vDlgV3sX1JPzrd	
		3G8tNc3mDgbdPZy8mGnmpKJ3WCKHVT6gbCV8Z56rKIVgXokgJkptJZ-i00;
		expires=Sat, 22-Dec-2012 22:51:17 GMT; path=/; domain=.google.ca; HttpOnly
	P3P: CP="This is not a P3P policy! See http://www.google.com/support/accounts			
		/bin/answer.py?hl=en&answer=151657 for more info."
	Server: gws
	X-XSS-Protection: 1; mode=block
	X-Frame-Options: SAMEORIGIN
	Transfer-Encoding: chunked

	1000								! byte count of chunked data block
	[...snip...]

Example 4: Using 'openssl s_client' to connect to my Apache webserver (I/P=142.180.221.226 port=443)

Three connect commands (responses not shown)

<ur>	openssl s_client -connect 142.180.221.226:443 -showcerts	! what far-end certificates are available?

<ur>	openssl s_client -connect 142.180.221.226:443 -debug		! show more info hex and ASCII

<ur>	openssl s_client -connect 142.180.221.226:443 -state		! show ssl state transitions 

Note: after anyone of the above commands, type the following:

<ur>	GET / HTTP/1.0<enter>						! get default document using HTTP/1.0
	<enter>								! signal end of HTTP header

Four connect commands (responses not shown)

<ur>	define/sys  vms_cert_dir  sys$sysdevice:[certificates]		! an HP-recommended directory 

--------------------------------------------------------------

<ur>	openssl s_client -connect 142.180.221.226:443	-		!
		-cert vms_cert_dir/client.crt		-		! for optional client verification
		-key vms_cert_dir/client.key				! for optional client verification

<ur>	openssl s_client -connect 142.180.221.226:443	-		!
		-cert vms_cert_dir/client.pem				! key + crt inside of pem

<ur>	openssl s_client -connect 142.180.221.226:443	-
		-cert vms_cert_dir/client.crt		-
		-key vms_cert_dir/client.key		-
		-tls1							! only use TLS1 encryption

Note: after anyone of the above commands, type the following:

<ur> GET / HTTP/1.0<enter>						! get default document using HTTP/1.0
     <enter>								! signal end of HTTP header

Example 5: Using 'openssl s_client' to connect to SSL$SIMPLE_SERV.C  (I/P=142.180.39.15 port=5555)

Five connect commands (responses not shown)

<ur>	openssl s_client -connect 142.180.39.15:5555 -debug		! details while negotiating

<ur>	openssl s_client -connect 142.180.39.15:5555 -state		! watch SSL change states

<ur>	openssl s_client -connect 142.180.39.15:5555 -tls1 -debug	! use the TLS1 protocol

<ur>	openssl s_client -connect 142.180.39.15:5555 -ssl3 -debug	! use the SSL3 protocol 

<ur>	openssl s_client -connect 142.180.39.15:5555	-		!
		-cert vms_cert_dir/client.pem		-		! PEM files require a HASH file
		"-CAfile" vms_cert_dir/client_ca.pem	-		! list of trusted certificates
		"-CApath" vms_cert_dir					! double-quote mixed case parameters in VMS

Example Block 6: OpenSSL client/server examples

Notes:
  1. the client and server programs do not need to reside on different platforms but it is more fun if they do (two PCs also work)
  2. when connecting to the same machine use address "127.0.0.1" except in the case of the TLS protocol which contains additional security (with TLS just use the fully qualified domain name)
  3. Note: on the OpenVMS CLI (known as DCL)
    • lines ending with a dash are continued on the next line
    • an exclamation is used to start a comment
  4. click here for instructions on how to do this experiment on Windows

A very simple web server (cannot server up a file)

Server:

<ur>	openssl s_server -accept 4433		-
		-cert vms_cert_dir/server.crt	-
		-key vms_cert_dir/server.key	-
		-debug				-
		-www							! barely simulate a webserver (lower case)
<sr>	Using default temp DH parameters
	Using default temp ECDH parameters
	ACCEPT

Client:

<ur>	openssl s_client -connect 142.180.39.15:4433 -debug		! will connect to server
<sr>	...handshake verbage...						! bla...bla...bla...
<ur>	GET / HTTP/1.0<enter>						! request default page containing stats
	<enter>								! signal end of HTTP header

A simple web server (can serve up a file)

Server:

<ur>	set default sys$login						! run these tests from your home directory
<sr>	$
<ur>	create neil.txt							! create a small text file
	this is sample text<ctrl-z>					! place text in the file
<sr>	$								!
<ur>	openssl s_server -accept 4433		-
		-cert vms_cert_dir/server.crt	-
		-key vms_cert_dir/server.key	-
		-debug				-
		-"WWW"							! simulate a better webserver
<sr>	Using default temp DH parameters
	Using default temp ECDH parameters
	ACCEPT

Client:

<ur>	openssl s_client -connect 142.180.39.15:4433	-
		-cert vms_cert_dir/client.crt		-
		-key vms_cert_dir/client.key		-		! will connect to server
<sr>	...handshake verbage...						! bla...bla...bla...
<ur>	GET /neil.txt HTTP/1.0<enter>					! request file "neil.txt"
	<enter>								! signal end of HTTP header
<sr>	HTTP 200 (OK)
	...header verbage...
       
	this is sample text						! presto

Web server with certificate-based client verification (popular in B2B applications)

  • here I am showing a client presenting his own per-client certificate but in some B2B applications the client software will present the certificate of the local web server
  • high level view of proof (only used during the initial handshake):
    1. remember that the client employs the server's public key when sending encrypted messages to the server. The server uses a private key to decrypt the message. If this works then the client can assume that the server is who he claims to be
    2. but if client-verification is requested, the client will begin encrypting messages using the client's private key which is then encrypted a second time using the server's public key before being sent. The server will use the server's private key on the first decrypt followed by the client's public key on the second decrypt. If this works then the server can assume that the client is who he claims to be (a.k.a. digital signing)
Server:

<ur>	set default sys$login						! run these tests from your home directory
<sr>	$
<ur>	type neil.txt							! make sure test file exists
<sr>	this is sample text
	$								!
<ur>	openssl s_server -accept 4433		-
		-cert vms_cert_dir/server.crt	-
		-key vms_cert_dir/server.key	-
		-debug				-
		-"WWW"				-			! simulate a better webserver
		-"Verify" 9						! force client to require a certificate
<sr>	verify depth is 9, must return a certificate
	Using default temp DH parameters
	Using default temp ECDH parameters
	ACCEPT 

Client:

<ur>	openssl s_client -connect 142.180.39.15:4433	-
		-cert vms_cert_dir/client.crt		-
		-key vms_cert_dir/client.key		-		! will connect to server
<sr>	...handshake verbage...						! bla...bla...bla...
<ur>	GET /neil.txt HTTP/1.0<enter>					! request file "neil.txt"
	<enter>								! signal end of HTTP header
<sr>	HTTP 200 (OK)
	...header verbage...
       
	this is sample text						! presto
<ur>	openssl s_client -connect 142.180.39.15:4433			! reconnect "without any certs"
<sr>	CONNECTED(00000005)
	depth=0 /C=CA/ST=ON/L=KITCHENER/O=BELL CANADA/OU=BELL-ATS/CN=www.bellics.com/emailAddress=neil@bellics.com
	verify error:num=18:self signed certificate			! this is not really an error
	verify return:1
	depth=0 /C=CA/ST=ON/L=KITCHENER/O=BELL CANADA/OU=BELL-ATS/CN=www.bellics.com/emailAddress=neil@bellics.com
	verify return:1
	262761:error:14094410:SSL routines:SSL3_READ_BYTES:sslv3 alert handshake failure:S3_PKT:1102:SSL alert number 40
	262761:error:140790E5:SSL routines:SSL23_WRITE:ssl handshake failure:S23_LIB:182:

Server:

<sr>	...verbage...
	261215:error:140890C7:SSL routines:SSL3_GET_CLIENT_CERTIFICATE:peer did not return a certificate:S3_SRVR:2611:
	ACCEPT								! waiting for another transaction

Example 7: OpenSSL advanced stuff

<sr>	$										! my DCL prompt
<ur>	openssl ciphers									! what ciphers are available locally?
<sr>	DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA:DHE-RSA-CAMELLIA256-SHA:
	DHE-DSS-CAMELLIA256-SHA:CAMELLIA256-SHA:EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-
	CBC3-SHA:DES-CBC3-SHA:DES-CBC3-MD5:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:
	AES128-SHA:DHE-RSA-SEED-SHA:DHE-DSS-SEED-SHA:SEED-SHA:DHE-RSA-CAMELLIA128
	-SHA:DHE-DSS-CAMELLIA128-SHA:CAMELLIA128-SHA:RC2-CBC-MD5:DHE-DSS-RC4-SHA:
	RC4-SHA:RC4-MD5:RC4-MD5:EXP1024-DHE-DSS-DES-CBC-SHA:EXP1024-DES-CBC-SHA:E
	DH-RSA-DES-CBC-SHA:EDH-DSS-DES-CBC-SHA:DES-CBC-SHA:DES-CBC-MD5:EXP1024-DH
	E-DSS-RC4-SHA:EXP1024-RC4-SHA:EXP-EDH-RSA-DES-CBC-SHA:EXP-EDH-DSS-DES-CBC
	-SHA:EXP-DES-CBC-SHA:EXP-RC2-CBC-MD5:EXP-RC2-CBC-MD5:EXP-RC4-MD5:EXP-RC4-
	MD5
	$
<ur>	openssl s_client -connect www.google.ca:443 -cipher "RC4-SHA"			! connect to Google using the RED cipher
	...handshake verbage...								! bla...bla...bla...

note:	the requested cipher might not be available at the far end 

Creating/using a trusted client chain (add remote cert to local cache)

 This first example demonstrates connecting to a system which employs self-signed certificates
notes:	1) I am on my production node "KAWC96" connecting to my development node "KAWC09"
	2) We could just ignore the error 18 then continue
	3) Or save the remote certificate in a local repository
----------------------------------------------------------------------------------------
<sr>	$										! my DCL prompt
<ur>	set def sys$login								! start in home location
<sr>	$										!
<ur>	openssl s_client -connect kawc09.on.bell.ca:443	-				! connect to development platform
		-state -showcerts							! (without any local certificate)
<sr>	CONNECTED(00000005)
	SSL_connect:before/connect initialization
	SSL_connect:SSLv2/v3 write client hello A
	SSL_connect:SSLv3 read server hello A
	depth=0 /C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	verify error:num=18:self signed certificate		<<<--- oops (let's fix this)
	verify return:1
	depth=0 /C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	verify return:1
	SSL_connect:SSLv3 read server certificate A
	SSL_connect:SSLv3 read server key exchange A
	SSL_connect:SSLv3 read server done A
	SSL_connect:SSLv3 write client key exchange A
	SSL_connect:SSLv3 write change cipher spec A
	SSL_connect:SSLv3 write finished A
	SSL_connect:SSLv3 flush data
	SSL_connect:SSLv3 read finished A
	---
	Certificate chain
	0 s:/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	i:/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	---
	Server certificate
	-----BEGIN CERTIFICATE-----
	MIICtzCCAiACCQCOJDXcN8BI4TANBgkqhkiG9w0BAQUFADCBnzELMAkGA1UEBhMC
	[...snip...]
	S/To2pITuhif+f7Mec4qU/SDUXpj6Se/tJE9TjE2Mc5edTUmgX3amMpYUnQwBHti
	zQb9M8XXRU0RwBHZgqOYk/amVFeVCVFxw9jn
	-----END CERTIFICATE-----
	subject=/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	issuer=/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	---
	No client certificate CA names sent
	---
	SSL handshake has read 1270 bytes and written 361 bytes
	---
	New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-SHA
	Server public key is 1024 bit
	Secure Renegotiation IS supported
	Compression: NONE
	Expansion: NONE
	SSL-Session:
	Protocol : TLSv1
	Cipher : DHE-RSA-AES256-SHA
	Session-ID: DE5C43E6C8B445FCDA60894A08650E5B19D1E99DAF3F70D2661EE60956001CF1
	Session-ID-ctx: 
	Master-Key: CFF329BE8FFF7B8FD7E6201B16F1AC3663EFF5633CDDD6EA52C79ED4A5C1A7A1F796DECCD77FCD21D497DC2021402118
	Key-Arg : None
	Start Time: 1343864769
	Timeout : 300 (sec)
	Verify return code: 18 (self signed certificate)			<<<---oops (let's fix this)
	---
<ur> <ctrl-Y>										! we're done so hit <ctrl-Y> 
<sr> INTERRUPT
	$

Create a trusted chain (or add to an existing chain)

Note: This is similar to what happens when you import a certificate into your browser
<ur>	cre xxx_kawc09.crt								! create a file
	-----BEGIN CERTIFICATE-----							! past in the remote certificate from above
	MIICtzCCAiACCQCOJDXcN8BI4TANBgkqhkiG9w0BAQUFADCBnzELMAkGA1UEBhMC
	[...snip...]
	S/To2pITuhif+f7Mec4qU/SDUXpj6Se/tJE9TjE2Mc5edTUmgX3amMpYUnQwBHti
	zQb9M8XXRU0RwBHZgqOYk/amVFeVCVFxw9jn
	-----END CERTIFICATE-----
	<ctrl-z>									! hit <ctrl-z> to exit file-creation with SAVE
<sr>	Exit
	$
<ur>	copy xxx_kawc09.crt vms_cert_dir						! optional: copy file to our cert directory
<sr>	$
<ur>	set def vms_cert_dir								! now move over there
<sr>	$
<ur>	dir client_ca.pem								! any chains like this here?
<sr>	%DIRECT-W-NOFILES, no files found						! nope
<ur>	copy xxx_kawc09.crt client_ca.pem						! copy cert into new PEM
		or									! or
	copy client_ca.pem, xxx_kawc09.crt client_ca.pem				! append cert onto existing PEM
<sr>	$
<ur>	openssl x509 -hash -noout -in client_ca.PEM					! compute hash of pem
<sr>	1132507a									! this is the computed result
<ur>	copy client_ca.PEM 1132507a.0							! create a hash file with '.0' extension
<sr>	$
<ur>	openssl verify "-CApath" vms_cert_dir -verbose -purpose any client_ca.PEM	! test the PEM-hash combo
<sr>	client_ca.pem: OK								! looks good so far
<ur>	set def sys$login:								! back to our home directory
<sr>	$
<ur>	openssl s_client -connect kawc09.on.bell.ca:443 -state	-			! connect to development platform (again)
		-cert vms_cert_dir/kawc96.crt			-			!
		-key vms_cert_dir/kawc96.key			-			!
		-"CAfile" vms_cert_dir/client_ca.PEM					! but reference trusted cert chain
<sr>	CONNECTED(00000005)
	SSL_connect:before/connect initialization
	SSL_connect:SSLv2/v3 write client hello A
	SSL_connect:SSLv3 read server hello A
	depth=0 /C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	verify return:1									<<<--- cool (fixed)
	SSL_connect:SSLv3 read server certificate A
	SSL_connect:SSLv3 read server key exchange A
	SSL_connect:SSLv3 read server done A
	SSL_connect:SSLv3 write client key exchange A
	SSL_connect:SSLv3 write change cipher spec A
	SSL_connect:SSLv3 write finished A
	SSL_connect:SSLv3 flush data
	SSL_connect:SSLv3 read finished A
	---
	Certificate chain
	0 s:/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	i:/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	---
	Server certificate
	-----BEGIN CERTIFICATE-----
	MIICtzCCAiACCQCOJDXcN8BI4TANBgkqhkiG9w0BAQUFADCBnzELMAkGA1UEBhMC
	[...snip...]
	S/To2pITuhif+f7Mec4qU/SDUXpj6Se/tJE9TjE2Mc5edTUmgX3amMpYUnQwBHti
	zQb9M8XXRU0RwBHZgqOYk/amVFeVCVFxw9jn
	-----END CERTIFICATE-----
	subject=/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	issuer=/C=ca/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
	---
	No client certificate CA names sent
	---
	SSL handshake has read 1270 bytes and written 361 bytes
	---
	New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-SHA
	Server public key is 1024 bit
	Secure Renegotiation IS supported
	Compression: NONE
	Expansion: NONE
	SSL-Session:
	Protocol : TLSv1
	Cipher : DHE-RSA-AES256-SHA
	Session-ID: 96B7F72BDCCB65C8040BD1DFE714989D87F966D000AB7ED9CDD9AEF5FD4EAE89
	Session-ID-ctx: 
	Master-Key: 7737874E462FAFD277E6541BD2608070BEBB15393D6897125F1DF8A10AC3AE24D5FD65BA0F909F9576A04856345BB6EE
	Key-Arg : None
	Start Time: 1343865022
	Timeout : 300 (sec)
	Verify return code: 0 (ok)					<<<---cool (fixed)
	---
<ur>	<ctrl-z>									! we are done
<sr>	Exit
	$

Overview of using Signed Certificates

Overview:

  • The main objective here is to create a CSR (Certificate Signing Request). This activity will generate two files: 
    1. whatever.key
      • holds the "private key" which you will never divulge to anyone
      • never encrypt this file. If you do then you will be prompted for a password whenever you restart Apache
    2. whatever.csr
      • holds certificate details about you and your sever including your "public key".
      •  you will display the raw file on you side before copying-then-pasting into a window at your certificate authority's web site
  • Once you have paid your money, and the Certificate Authority is convinced you are not attempting to generate a certificate for someone else's fully-qualified-domain, they will generate two files (some authorities will email files to you while others will send you an email instructing you on how to retrieve them from their site)
    1. whatever.crt (this is your public certificate; it was made by signing whatever.csr)
    2. vendor.crt (this is the vendor's public certificate which was used to sign whatever.crt)

OpenVMS steps using DCL scripts (the least error-prone method)

	$set default  ssl$com				(or set def ssl1$com )
	$@SSL$CERT_TOOL.COM				(or @ssl1$cert_tool.com )
		select "Create a Certificate Signing Request" (also called a CSR)
			be sure to name it something like: host_domain_ccyymmdd.csr
			where ccyymmdd represents the current date
		exit
	$set def SSL$ROOT:[000000.DEMOCA.CERTS]
	$dir  host_domain_ccyymmdd.*
		you should see two files; one with an extension of ".csr" and one with ".key"
	$type host_domain_ccyymmdd.csr
	-----
	1) drag your cursor across the file contents
	2) paste the result into the submission window at your certificate vendor's site
	3) the vendor will sign your CSR and mail it back to you as a CRT
	4) You should copy/paste the base-64 text into a file of the form:
		host_domain_ccyymmdd.crt
	5) The email will also contain a copy of the vendor's intermediate certificate
	6) You should copy/paste the base-64 text into a file of the form:
		host_domain_ccyymmdd_internediate.crt
	-----
	Modify Apache config file "[.conf]ssl.conf" like so:
		# our public certificate
		SSLCertificateFile	/vms_prod_cert_dir/BELLICS_COM_ccyymmdd.CRT
		# our private key
		SSLCertificateKeyFile	/vms_prod_cert_dir/BELLICS_COM_ccyymmdd.KEY
		# the CA's intermediate certificate
		SSLCACertificateFile	/vms_prod_cert_dir/BELLICS_COM_ccyymmdd_INTERMEDIATE.CRT
	restart Apache (monitor all error logs; if the server won't start then you've made a mistake)
	now retest with the OpenSSL CLI
	now retest with a all three popular browsers (IE, Firefox, Chrome)

Testing/Retesting

  • Your certificate vendor will provide you access to post installation tools which will verify the certificate installation as well as test your Apache-based OpenSSL engine.
  • It would be wise to test your site every few months to ensure you are not offering to use ciphers or protocols which are no longer considered secure
  • Here is one publically available tool for testing your site right now: https://www.ssllabs.com/ssltest/

All Platforms (when training wheels are not available or desired)

	note: this is a real-world example for server "kawc96.on.bell.ca"
	      except that I replaced my actual submission date with ccyymmdd
	commands:

	1) openssl genrsa   -out kawc96_ccyymmdd.key 2048
	2) openssl req -new -key kawc96_ccyymmdd.key -out kawc96_ccyymmdd.csr
	3) openssl req -noout -text -in                   kawc96_ccyymmdd.csr 
	4) cat (on Unix/Linux)                            kawc96_ccyymmdd.csr
		or 
	   type (on OpenVMS)                              kawc96_ccyymmdd.csr
	steps:
	1) copy/paste the contents into the submission window at your certificate vendor's site
	2) the vendor will sign your CSR then email it back to you in base-64 format
	3) copy/paste the base-64 text from the email into a file of the form:
	                                                  kawc96_ccyymmdd.crt
	4) visit the vendor's site to get a copy of their signing certificate.
	   I saved mine as: kawc96_ccyymmdd_vendor.crt
	5) modify the Apache config file "ssl.conf" (see steps above)
		kawc96_ccyymmdd.key        (private key which will never been shared with anyone)
		kawc96_ccyymmdd.crt        (public certificate which contains your public key)
		kawc96_ccyymmss_vendor.crt (vendor's public certificate used to sign your cert)
	6) restart the server (checking your log files)

A little more hacking (er, self education)

OpenSSL commands to display the certificates just for the fun of it

 1) openssl x509 -noout -text -in kawc96_ccyymmdd.crt
 3) openssl x509 -noout -text -in kawc96_ccyymmss_vendor.crt 

So you have found some time to get beyond connectivity tests and would like to dig a little deeper into this tool

p.s. the following examples manipulate files rather than data streams but you will get the general idea

OpenSSL s_client bug on OpenVMS (2012-02-xx)

  1. On 2012-02-14 I realized that command and openssl s_client on OpenVMS-8.4 Alpha does not work properly with HP-OpenSSL-1.4-453

    legend:
    <ur>	= user response
    <sr>	= system response
    ----------------------------------------------------
    <ur> openssl s_client -connect www.google:443<enter>
         <enter>
         <enter>
         <enter>
    <sr> write:errno=32    <<<--- Oops!!

    Note: I think error 32 = "broken pipe" (see: ERRNO.H or ERRNODEF.H) which means the channel just closed
    The problem here is that we did not see a prompt where we could request something from Google

  2. The bug does not exist on CPQ-OpenSSL-1.1B
     
  3. The bug is found in all HP versions starting with HP-OpenSSL-1.2 and running through HP-OpenSSL-1.4-467
     
  4. The bug affects Alpha and Itanium (there were no HP-sanctioned versions for VAX after  CPQ-OpenSSL-1.1B)
     
    • On OpenVMS: I created a little text file named "neil.txt" which only contains one line of data: "test data"
      then I ran openssl s_server "-WWW" -debug so my machine would act as a file webserver
      (use -accept to change to a different port if 443 is already in use by Apache on your system)
       
    • On Solaris: I typed openssl s_client -connect www.myserver:443 -debug and here is what I recorded
      <ur>	openssl s_client -connect www.myserver.com:443<enter>	!
      <sr>	...handshake verbage...					! bla...bla...bla...
      	---							! prompt
      <ur>	GET /neil.txt HTTP/1.0<enter>				! we want file neil.txt
      	<enter>							! signal end of HTTP header
      <sr>	HTTP HTTP/1.0 200 ok					!
      Content-type: text/plain ! !
      test data !
    • OpenVMS:  I now repeated the previous command. However, entering "GET /neil.txt HTTP/1.0<enter><enter>" will show outbound data packets every time you hit <enter> but no clear text is ever seen
    • Now inspect the s_server dialog you will find a line containing "FILE:neil.txt" which indicates the requested file being sent back.
       
    • At the client you will see inbound packets but nothing displayed in clear text
       
    • Conclusion:
       
      1. either the client-end connection isn't decrypting anything
      2. or there is no way to see what has been decrypted (since typing wasn't echoed, this last case seems more likely)
         
  5. On 2012-03-06 I realized this openssl s_client problem was only failing "server to client" and here is the proof:
     
  6. On 2012-03-11 I finally got around to developing a bug-fix for s_client.c (for HP-OpenSSL-1.3-281 and higher) which goes something like this:
     
    1. (tested) optional cosmetic change:
      • use an editor to locate the sixth line from the end of routine "void print_stuff(" which should read:
        BIO_printf(bio,"---\n");

        then change it to:
        BIO_printf(bio,"---\n\n");
      • This change will provide room under the three dashes for you to type your web server request (restores previous functionality)
         
    2. (tested) mandatory change for:
      • HP-OpenSSL-1.3-281
        1. use an editor to locate the string:
          i=write
        2. back up ~10 lines to locate the string:
          #if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_MSDOS)

          then change it to:
          #if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_MSDOS) || defined(OPENSSL_SYS_VMS)
          Explanation for this fix: In VMS section of "if (!ssl_pending)" we never call "if (write_tty) FD_SET(fileno(stdout),&writefds);" so it makes no sense to block on "FD_ISSET(fileno(stdout),&writefds)" ~ 150 lines below
      • HP-OpenSSL-1.4
        1. use an editor to locate the string:
          i=write
        2. back up ~10 lines to locate the string:
          #if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_MSDOS) || defined(OPENSSL_SYS_NETWARE)
          

          then change it to:
          #if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_MSDOS) || defined(OPENSSL_SYS_NETWARE) \
          	|| defined(OPENSSL_SYS_VMS)
      • HP-OpenSSL-1.4-453    -and-
        HP-OpenSSL-1.4-467
        • same fixes as HP-OpenSSL-1.4 but you will also see a compile problem with program B_SOCK.C which does not affect the VMS build
          (see the phrase above " class#ifdef OPENSSL_SYS_WINDOWS || (defined(OPENSSL_SYS_NETWARE) && !defined(NETWARE_BSDSOCK))makes no sense")
           
    3. (untested) mandatory change for OPENSSL-100G (from Swedish developer site http://polarhome.com/openssl/ )
      • use an editor to locate the string:
        i=raw_write_stdout

        then repeat the fixes above (but you will still crap out with error "bad select 38" which is related to select () testing stdin as if it were a network device). I won't be able to test this fix until I include term_sock.c functionality (and I just can't find the time right now)
        But then I did find the time. Click here to jump ahead.
         
    4. Suggestion: The current state of s_client.c can only be described as horrible. Due to the number of people who appear to have to modified it along with all the conditional compile statements, it would never pass a code review. Some kind soul should update it to a more modern "block indentation" like so:
      if (bla...)
      {	if (yada...)
      	{	just one line but bracketed anyway;
      	}
      }
      else
      {	switch(temp) {
      	case CASE1:
      		{	whatever;
      			break;
      		}
      	case CASE2:
      		{	whatever;
      			break;
      		}
      	default:
      		{	just one line but bracketed anyway;
      		}
      	}
      }

My Regression Testing

Operating
System
HP-OpenSSL
Version
Output from command
"OpenSSL s_client version"
s_client
works
properly?
Notes
OpenVMS-7.3 CPQ-OpenSSL-1.0A OpenSSL 0.9.6b [engine] 9 Jul 2001
[blank line]
Y telnet to: gate.polarhome.com
OpenVMS-7.3-1 CPQ-OpenSSL-1.1 OpenSSL 0.9.6g [engine] 9 Aug 2002
[blank line]
Y telnet to: deathrow.vistech.net
OpenVMS-7.3-2 CPQ-OpenSSL-1.1 OpenSSL 0.9.6g [engine] 9 Aug 2002
[blank line]
Y built this scratch system then downloaded
this kit:
 cpq-axpvms-ssl-v0101--1.pcsi-dcx_axpexe
from here:
 http://www.decuslib.com/decus/
OpenVMS-7.3-2 CPQ-OpenSSL-1.1B OpenSSL 0.9.6g [engine] 9 Aug 2002
[blank line]
Y built this scratch system then installed
this kit from a friend:
 cpq-axpvms-ssl-v0101-B-1.pcsi-dcx_axpexe
OpenVMS-7.3-2 HP-OpenSSL-1.2 OpenSSL 0.9.7d 17 Mar 2004
SSL for OpenVMS V1.2 Nov 3 2004.
N built this scratch system then installed
this kit from a friend:
 HP-AXPVMS-SSL-V0102--1.AXPEXE
OpenVMS-7.3-2 HP-OpenSSL-1.3-281 OpenSSL 0.9.7e 25 Oct 2004
SSL for OpenVMS V1.3 May 26 2006.
N built this scratch system then downloaded
this kit from HP:
 HP-AXPVMS-SSL-V0103-0281-1.PCSI_SFX_AXPEXE
OpenVMS-8.3 HP-OpenSSL-1.3-281 OpenSSL 0.9.7e 25 Oct 2004
SSL for OpenVMS V1.3 May 26 2006.
N visited: eisner.decus.org
OpenVMS-8.4 HP-OpenSSL-1.3-281 OpenSSL 0.9.7e 25 Oct 2004
SSL for OpenVMS V1.3 May 26 2006.
N I forced this regression
OpenVMS-8.4 HP-OpenSSL-1.4-453 OpenSSL 0.9.8o 01 Jun 2010
SSL for OpenVMS V1.4 May 10 2011.
N my production machine
OpenVMS-8.4 HP-OpenSSL-1.4-467 OpenSSL 0.9.8w 23 Apr 2012
SSL for OpenVMS V1.4 May 22 2012.
N my production machine (see following notes)
OpenVMS-8.4 HP-OpenSSL-1.4-471 OpenSSL 0.9.8y 5 Feb 2013
SSL for OpenVMS V1.4 Mar 7 2013.
Y my development machine

An official fix from HP is coming has come

Notes:
  1. I received a private patch today (2012-06-20) from HP OpenVMS Support which fixes the s_client bug in HP-OpenSSL-1.4-467. This patch is available on request so you need a VMS support contract to receive it. HP engineers do not like the shape of the existing code so will not offer a public fix for s_client until the next release of HP-OpenSSL for OpenVMS (probably in 2013).
     
  2. On 2012-06-23 I downloaded HP's source code for HP-OpenSSL-1.4-467 and verified that I could fix the problem myself. You could do this too provided you have access to a "C" compiler. When you are done, just copy test application openssl.exe from your working directory into production directory ssl$exe then test it.
     
  3. On 2013-05-06 I downloaded HP-OpenSSL-1.4-471 from HP's OpenVMS website and verified that s_client appears to work properly. Kudos to HP.

Building OpenSSL (for OpenVMS) from HP Sources

Here I am not talking about installing a PCSI kit from HP. I am talking about building (full recompile and link) so you will need a C-language compiler.

File Still
Available
from HP?
Available
Elsewhere?
VAX AXP I64 s_client
works
properly?
Notes
COMPAQ_SSL_SOURCES_V10A.EXE
COMPAQ_SSL_SOURCES_V10A.BCK
n     y   y 1) can only build AXP (Alpha) binaries
2) they appear to have been playing with VAX + I64 (using cross compilers)
COMPAQ_SSL_SOURCES_V11.EXE
COMPAQ_SSL_SOURCES_V11.BCK
n     y   y 1) can only build AXP (Alpha) binaries
2) they appear to have been playing with VAX + I64 (using cross compilers)
COMPAQ_SSL_SOURCES_V11A.EXE
COMPAQ_SSL_SOURCES_V11A.BCK
n y y y   y

To verify original announcement:
wayback-machine

COMPAQ_SSL_SOURCES_V11B.EXE
COMPAQ_SSL_SOURCES_V11B.BCK
n   y y   y

original announcement:
wayback-machine

HP_VMS_SSL_SOURCES_V12.EXE
HP_VMS_SSL_SOURCES_V12.BCK
n     y y n
(see note 5)
original announcement:
wayback-machine
HP_VMS_SSL_SOURCES_V13.AXPEXE
HP_VMS_SSL_SOURCES_V13.I64EXE
y
(see note 1)
    y y n
(see note 5)
original announcement:
wayback-machine
HP_VMS_SSL_SOURCES_V14.AXPEXE
HP_VMS_SSL_SOURCES_V14.I64EXE
y
(see note 1)
    y y n
(see note 5)
 
HP_VMS_SSL_SOURCES_V14-453.AXPEXE
HP_VMS_SSL_SOURCES_V14-453.I64EXE
y
(see note 1)
    y y n
(see note 5)
 
HP_VMS_SSL_SOURCES_V14-467.AXPEXE
HP_VMS_SSL_SOURCES_V14-467.I64EXE 
y
(see note 1)
    y y n
(see note 5)
 
HP_VMS_SSL_SOURCES_V14-471.AXPEXE
HP_VMS_SSL_SOURCES_V14-471.I64EXE
y     y y y  

Notes:
  1. Most "HP sanctioned" releases of OpenSSL for OpenVMS files can be found here: ftp://ftp.hp.com in folder "/pub/openvms/ssl/".
     
  2. HP is not offering any modern OpenSSL kits for VAX so you will need to build it yourself from public sources or download a complete package from Sweden ( http://polarhome.com/openssl/ )
     
  3. You might also find some older stuff here:
  4. Compaq/HP Build Notes:
    Do When Do What Target
    Do at least once read these notes http://h41379.www4.hpe.com/openvms/products/ssl/ssl_source.html#buildopenssl
      read text file $$$README.FOR_VMS
      never execute DCL script SUBMIT_BUILD.COM (can only be executed on HP's development system; requires CMS as well as some crypto stuff)
      consider modifying script VMS_BUILD_INFO.COM
    1. make sure the first line contains "$set noon"
    2. make sure BUILD_PLATFORM == "ALPHA" or "IA64"; sometimes this script is set to IA64 in the Alpha kit
    3. comment out the line defining CRYPTO$RES (it only exists on the HP development platform)
    B4 every full build execute DCL script @VMS_BUILD_INFO.COM (which sets DCL symbols required by MAKEVMS.COM)
      execute DCL script @MAKEVMS.COM/OUTPUT=MAKEVMS.LOG ALL NORSAREF NODEBUG DECC NONE
    (Note: NONE seems to work properly with both "TCPIP Services" as well as TCPware)
    B4 every app build execute DCL script @VMS_BUILD_INFO.COM (which sets DCL symbols required by MAKEVMS.COM)
      execute DCL script @MAKEVMS.COM/OUTPUT=MAKEVMS.LOG APPS NORSAREF NODEBUG DECC NONE
    (Note: NONE seems to work properly with both "TCPIP Services" as well as TCPware)
  5. Click this link to learn how to fix a problem with s_client.c prior to doing a build

Building OpenSSL (for OpenVMS) From Public Sources

Building OpenSSL on VMS from public sources
  1. Source #1 (vanilla): http://www.openssl.org/source/
  2. Source #2 (VMS friendly): http://polarhome.com/openssl/
    who offer:
    • smaller source-only kits
    • larger binary kits containing both 32-bit and 64-bit executables (VAX, Alpha, and Itanium) without source code
    comment: okay so every time I connect to this Swedish site I think about "The Girl With the Dragon Tattoo" by Stieg Larsson along with all the Swedish, Finnish and German hackers out there. If you saw the 2011 American version of the movie staring Daniel Craig then you will have no idea what I am talking about. I recommend you watch the 2009 Swedish version staring Noomi Rapace (the Blu-ray has English dubs).
OpenSSLbr>Version
(Vanilla)
Compiles
as-is
on VMS?
NNotes s_client
works
properly?
Notes Add'l
Notesbr>Below
OpenSSL 0.9.6g yes build script okay; install script needs work ? stopped by error "bad select 38" 2
OpenSSL
VVersion
(PolarHome)
Compiles
as-is
on VMS?
Notes s_client
works
properly?
Notes Add'l
Notesbr>Below
OpenSSL 1.0.1b
26 Apr 2012
yes build and install scripts are improved ? stopped by error "bad select 38" 1,2

Vanilla Build Notes:

  • most of the VMS build docs are old (some appear unchanged since 2000)
  • some docs and scripts have been modified but embedded dates have not been changed and there are no "in document" version numbers
  • the talented engineers at HPQ have made extensive changes to the 64-bit (Alpha/Itanium) versions which are only available from the HP website (these changes are instructive if nothing else). Perhaps HP management will not allow value-added changes to migrate back to the public source code but I don't see why some kind soul doesn't do this for the benefit of the Open Source community.
  • 0.9.6 (all versions)
    • bbuild script makevms.com will take up to 6 parameters (the first 3 are mandatory).
      • If you start the script with no parameters, the script will display help for each mandatory parameter then exit. Restart the script after each exit until it runs (more on this in a moment) /li>
      • P4 is used to set your "C" compiler. The script does a reasonable job of detecting which compiler is installed so this parameter is only important if you more than one compiler installed.
      • P5 is used to detect your TCP/IP stack and I'm not sure that auto-detect works properly. Why? Think about all the possible stacks which might be present:
        • TCPware (from Process Software; the only stack available for VMS for a decade starting in 1987)
        • MultiNet (purchased by Process Software from CISCO in 1997; MultiNet was initially created by TGV)
        • UCX (originally for ULTRIX; DEC ported this to VMS as a skunk works project)
        • TCPIP Services for OpenVMS (the official HP offering for OpenVMS)
      • BBuilding with RSA support is optional. If you wish to do this, OpenSSL docs tell you to retrieve RSADEF encryption files from www.rsa.com but you will never locate them because RSA removed them in 2000 when the patents expired. The files can still be found on ftp servers in Northern Europe (see the OpenSSL FAQ for sites). OpenVMS enthusiasts who want to keep museum pieces fully stocked might wish to download those files before they are lost forever (perhaps they could be posted to DECUS).
    • After installing the public source version of OpenSSL on OpenVMS, "s_client" will complain about a random generator problem like so:
      1092:error:24064064:random number generator:SSLEAY_RAND_BYTES:PRNG not seeded:SYS$SYSROOT:[SYSMGR.OPENSSL-096G.crypto.rand]md_rand.c;1
          :501:You need to read the OpenSSL FAQ, http://www.openssl.org/support/faq.html
      1092:error:05067003:Diffie-Hellman routines:DH_generate_key:BN lib:SYS$SYSROOT:[SYSMGR.OPENSSL-096G.crypto.dh]dh_key.c;1:147:
      1092:error:14098005:SSL routines:SSL3_SEND_CLIENT_KEY_EXCHANGE:bad asn1 object header:SYS$SYSROOT:[SYSMGR.OPENSSL-096G.ssl]s3_clnt.c
      ;1:1490:/pre>
      		
      • to get around this you must do the following because the $$openssl rand procedure doesn't seem to work properly on OpenVMS
         
      • create a random data file like so:
        $create neil.rnd		! creates a file named "neil.rnd"    
        12345678901234567890<control-z>	! enter at least 20-characters before hitting <control-z>/pre>
        			
      • nnow connect like so:
        $openssl s_client -connect 123.123.123.123:443 -rand neil.rnd
      • if you don't want to type the rand command all the time then just define a logical like so:
        $define/system RANDFILE = SYS$SYSDEVICE:[HACK]NEIL.RND

        as an alternative, you can use a process level logical or just declare a DCL symbol like so:
        RANDFILE :== SYS$SYSDEVICE:[HACK]NEIL.RND
  • 0.9.7 (all versions and higher)
    • software for 0.9.7 can't use the RSA software so don't even bother looking for it. But P2 is still reserved for it
    • ssince P2 is no longer supported but is still present, you can only start the script using a command similar to this:
          @makevms all "" nodebug decc multinet

PolarHome (Sweden) Build Notes

  • PolarHome Offers:
    1. smaller source-only kits/li>
    2. llarger binary kits containing both 32-bit and 64-bit executables (VAX, Alpha, and Itanium) without source code
  • OPENSSL-101b
    • I built this kit using this DCL command:
          @makevms.com/output=makevms.log all "" nodebug decc none
      Note that the meaning of P2 has changed from previous versions at this site but rather than using "" you may wish to use 32 or 64 (see docs)/li>
Additional Notes:
  1. OPENSSL-101b (quick test)
    openssl s_client -connect www.twitter.com:443 -no_tls1
    CONNECTED(00000003)
    depth=1 C = US, O = "VeriSign, Inc.", OU = VeriSign Trust Network, OU = Terms of use at https://www.verisign.com/rpa (c)06, CN = Ver
    iSign Class 3 Extended Validation SSL CA
    verify error:num=20:unable to get local issuer certificate
    verify return:0
    ---
    Certificate chain
     0 s:/1.3.6.1.4.1.311.60.2.1.3=US/1.3.6.1.4.1.311.60.2.1.2=Delaware/businessCategory=Private Organization/serialNumber=4337446/C=US/
    postalCode=94107/ST=California/L=San Francisco/street=795 Folsom St, Suite 600/O=Twitter, Inc./OU=Twitter Security/CN=twitter.com
       i:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)06/CN=VeriSign Class 3 Exte
    nded Validation SSL CA
     1 s:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)06/CN=VeriSign Class 3 Exte
    nded Validation SSL CA
       i:/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=(c) 2006 VeriSign, Inc. - For authorized use only/CN=VeriSign Class 3 Publi
    c Primary Certification Authority - G5
    ---
    Server certificate
    -----BEGIN CERTIFICATE-----
    MIIGfDCCBWSgAwIBAgIQHiLHN6ORXj+rZcS1pByuRjANBgkqhkiG9w0BAQUFADCB
    [...snip...]
    0tjHHMI1d6IJs0TAO26/SVI7YlQXEstKHk9iJzappwZ/0HZJsepX7jIxvlxyKKGb
    8MQGjSCwx8bY2PbYaLe0rkk2IjH0aMUlHW77DpNAK40=
    -----END CERTIFICATE-----
    subject=/1.3.6.1.4.1.311.60.2.1.3=US/1.3.6.1.4.1.311.60.2.1.2=Delaware/businessCategory=Private Organization/serialNumber=4337446/C=
    US/postalCode=94107/ST=California/L=San Francisco/street=795 Folsom St, Suite 600/O=Twitter, Inc./OU=Twitter Security/CN=twitter.com
    issuer=/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=Terms of use at https://www.verisign.com/rpa (c)06/CN=VeriSign Class 3 Ex
    tended Validation SSL CA
    ---
    No client certificate CA names sent
    ---
    SSL handshake has read 3360 bytes and written 488 bytes
    ---
    New, TLSv1/SSLv3, Cipher is RC4-SHA
    Server public key is 2048 bit
    Secure Renegotiation IS supported
    Compression: NONE
    Expansion: NONE
    SSL-Session:
        Protocol  : SSLv3
        Cipher    : RC4-SHA
        Session-ID: 98708C8995FF0F8AE3DE17DC8066CF220AB3D50C183E519089DB2E893EFEDCEA
        Session-ID-ctx: 
        Master-Key: 5542D6ADAC52B4FD82FD9E0FCADE67FBBB5D4BAB4EA1F5D564FE6F98F6CC6E8F3A0F350BF668726A377EC1169205BBAA
        Key-Arg   : None
        PSK identity: None
        PSK identity hint: None
        SRP username: None
        Start Time: 1340481505
        Timeout   : 300 (sec)
        Verify return code: 20 (unable to get local issuer certificate)
    ---bad select 38        <<<--- Oops! What does this mean?
    $
  2. Getting around "bad select 38"
     
    1. This publication: HP TCP/IP Services for OpenVMS Sockets API and System Services Programming
      http://h41379.www4.hpe.com/doc/82final/6529/6529pro_030.html
      in table Translation of Socket Error Codes to OpenVMS Status Codes
      indicates that socket error 38 (ENOTSOCK) is mapped to VMS code SS$_NOTNETDEV (Socket operation on nonsocket) so this problem involves treating stdin as a network device. (Allowed in the UNIX/Linux world but not allowed in the Windows/VMS world)
       
    2. Definitions for error 38 (ENOTSOCK) can be found here:
      1. SYS$COMMON:[SYSLIB]TCPIP$INETDEF.H
      2. SYS$COMMON:[SYSLIB]UCX$INETDEF.H
      3. SYS$COMMON:[TCPWARE.INCLUDE]UCX$INETDEF.H
         
    3. In some instances, UNIX-IO statement select() does not behave as expected on OpenVMS/VMS platforms. Poking around the documentation will reveal a few clues and here are some links to peruse:
    4. Source code to help explain the problem technically -and- enable you to get out of the "bad select 38" dilemma

Application Development

Getting Familiar with SSL Programming on OpenVMS

Caveats:

  • demo c-language programs are now found in two locations
    • ssl$examples (only supports OpenSSL-0.9 and lower)
      • HP has not updated the following example programs since 2006 so beware (the following directory listing was updated in 2016 from a new Itanium running OpenVMS-8.4)
      • these example programs need to be retested with HP SSL Version 1.4 (2012) which is not compatible with HP SSL Version 1.3 and earlier but I suspect a simple recompile and link is all that is required (BIO examples will probably work as-is; the TCP examples might require a few tweaks)
      • when testing the client programs by connecting to a web server:
        • change references of SSLv3_method() to TLSv1_method() because SSLv3 has been disabled on most web servers in 2014 due to the POODLE attack
        • consider generating certificates with keys sizes of 2048 bits (minimum)
        • some of the example programs reference certificates in your current directory (ssl$examples) whilst others reference certificates under ssl$root
        • hopefully none of your production certificates are under folder ssl$root but if they are, hopefully none have filenames like client.ext or server.ext otherwise you might not be able to use this mandatory script: ssl$examples:SSL$EXAMPLES_SETUP.COM
    • ssl1$examples (only supports OpenSSL-1.0 and higher)
      • some of the example programs reference certificates in your current directory (ssl1$examples) whilst others reference certificates under ssl$root
      • hopefully none of your production certificates are under folder ssl1$root but if they are, hopefully none have filenames like client.ext or server.ext otherwise you might not be able to use this mandatory script: ssl1$examples:SSL1$EXAMPLES_SETUP.COM
  • there are two ways to do self-signed certificates:
    • if only dealing with browsers and webservers then you can get away with just creating a self-signed certificate
      • most browsers come with a preloaded cache of CA certificates
      • when a self-signed certificate is encountered, the user is given the option of loading it into the cache
    • if dealing with OpenSSL or client software based upon OpenSSL it is better to:
      • create a self-signed CA (certificate authority)
      • create a CSR (certificate signing request)
      • use your own CA to sign your CSR
      • additional notes:
        • when you are testing client software to a browser, you will need to acquire the server's "self-signed certificate" or "intermediate CA certificate" then manually insert it into your client CA file before you begin testing
        • the script ssl$examples:SSL$EXAMPLES_SETUP.COM first creates server_CA.key and server_CA.crt then copies them to client_CA.key and client_CA.crt which is how this whole certificate thing is faked out in this example environment.

Example 'C' Programs from HP

$ set def ssl$examples
$ dir

Directory SYS$COMMON:[SYSHLP.EXAMPLES.SSL]

File                            Size  Date Stamp              Notes
------------------------------- ----  ----------- --------------------------------------------------------------
SSL$SIMPLE_CLI.C                 9KB  19-APR-2006 Simplest SSL and socket without BIO			(Client)
SSL$SIMPLE_SERV.C                8KB  19-APR-2006 Simplest SSL and socket without BIO			(Server)

SSL$BIO_CLI.C                    9KB  19-APR-2006 Simplest SSL and socket w/"Socket BIO"		(Client)
SSL$BIO_SERV.C                   9KB  19-APR-2006 Simplest SSL and socket w/"Socket BIO"		(Server)

SSL$CLI_VERIFY_CLIENT.C          9KB  19-APR-2006 "Socket BIO" + "client certificate verification"	(Client)
SSL$SERV_VERIFY_CLIENT.C         9KB  19-APR-2006 "Socket BIO" + "client certificate verification"	(Server)

SSL$CLI_SESS_REUSE.C            10KB  19-APR-2006 "Socket BIO" + "Session Resumption"			(Client)
SSL$SERV_SESS_REUSE.C            9KB  19-APR-2006 "Socket BIO" + "Session Resumption"			(Server)

SSL$CLI_SESS_REUSE_CLI_VER.C    12KB  19-APR-2006 "Socket BIO" + "Session Resumption" +
								 "Client Cert Verify"			(Client)
SSL$SERV_SESS_REUSE_CLI_VER.C   13KB  19-APR-2006 "Socket BIO" + "Session Resumption" +
								 "Client Cert Verify"			(Server)

SSL$CLI_SESS_RENEGO.C           11KB  19-APR-2006 "Socket BIO" + "Session Renegotiation"		(Client)
SSL$SERV_SESS_RENEGO.C          11KB  19-APR-2006 "Socket BIO" + "Session Renegotiation"		(Server)

SSL$CLI_SESS_RENEGO_CLI_VER.C   11KB  19-APR-2006 "Socket BIO" + "Session Renegotiation" +
								 "Client Cert Verify"			(Client)
SSL$SERV_SESS_RENEGO_CLI_VER.C  11KB  19-APR-2006 "Socket BIO" + "Session Renegotiation" +
								 "Client Cert Verify"			(Server)

SSL$TCP_CLIENT_QIO_SSL.C        17KB  14-JUN-2004 TCP/IP w/SSL using the Queued I/O			(Client)
SSL$TCP_SERVER_QIO_SSL.C        22KB  14-JUN-2004 TCP/IP w/SSL using the Queued I/O			(Server)

SSL$SHA1_MD5.C                   8KB  29-SEP-2004 how to use Secure Hash 1 and message digest 5

SSL$AES.C                       10KB  14-JUL-2004 how to use "Advanced Encryption Standard"
----------------------------------------------------------------------------------------------------------------
Just for fun, enter this DCL command:

        $dif  SSL$BIO_CLI.C  SSL$SIMPLE_CLI.C  /par/ignore=(white,case)

Not much difference between these two programs, eh?

Getting Familiar with SSL Programming on OpenVMS

Caveat: you need a "C" compiler to build the following executables

Legend: <ur> = user response
        <sr> = system response
--------------------------------------------------------
<sr>	$
<ur>	set def SSL$EXAMPLES				! we are now located somewhere under SYS$HELP
<sr>	$
<ur>	edit SSL$SIMPLE_SERV.C				! to inspect the build instructions then exit


Note: the following instructions are for 32-bit apps


<sr>	$
<ur>	cre VMS_DECC_OPTIONS.OPT
	SYS$LIBRARY:SSL$LIBCRYPTO_SHR.EXE/SHARE
	SYS$LIBRARY:SSL$LIBSSL_SHR.EXE/SHARE
	<ctrl-Z>
<sr>	$
<ur>	CC/POINTER_SIZE=32/PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES SSL$SIMPLE_SERV.C	! build simple server
<sr>	$
<ur>	link SSL$SIMPLE_SERV.obj, VMS_DECC_OPTIONS.OPT/OPT
<sr>	$
<ur>	CC/POINTER_SIZE=32/PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES SSL$SIMPLE_CLI.C	! build simple client
<sr>	$
<ur>	link SSL$SIMPLE_CLI.obj, VMS_DECC_OPTIONS.OPT/OPT
<sr>	$
<ur>	run SSL$SIMPLE_SERV.EXE
<sr>	186045:error:02001002:system library:fopen:no such file or directory:BSS_FILE:278:fopen('server.crt','r')
	186045:error:20074002:BIO routines:FILE_CTRL:system lib:BSS_FILE:280:
	186045:error:140AD002:SSL routines:SSL_CTX_use_certificate_file:system lib:SSL_RSA:515:


Note: The errors above indicate the certificates are missing from this directory.
      Read the contents of file "SSL$EXAMPLES:SSL$EXAMPLES_SETUP.TEMPLATE"


<sr>	$
<ur>	set def SSL$COM							! <<<--- location of HP's scripts
<sr>	$
<ur>	@SSL$CERT_TOOL.COM						! <<<--- start HP's certificate tool


File Name Description
server_CA.crt certificate and public key of your CA (certificate authority)
server_CA.key private key of your CA (certificate authority)
server.csr certificate signing request
  1. a file to be sent (out-of-band) to a CA for signing
  2. not required for a self signed certificate
server.crt certificate and public key of your server  (for in-channel distribution to your client)
  1. a signed certificate received from a CA (yours or someone else's)
  2. "or" a Self Signed certificate
  3. the "Common Name" field must contain the server's DNS
server.key private key of your server certificate
client.crt certificate and public key (client side)
  1. not required 95% of the time (client authentication is usually done via username/password)
  2. for some server-to-server communications like SOAP, you can use your server.crt
client.key private key of your client certificate
  1. not required 95% of the time (client authentication is usually done via username/password)
  2. for some server-to-server communications like SOAP, you can use your server.key
client_CA.crt a file containing one-or-more CA certificates
  1. also known as "a certificate chain file"
  2. these certificates are used to verify the legitimacy of signed server certificates
  3. this file is built by appending CA certificates (received out-of-band)
  4. many internet clients (e.g. browsers, email) are installed with 20,or more, preinstalled CA certificates.
    When building your own SSL clients, you will need to provide a list of any CA certificates you will encounter.

Steps:
  1. execute script @SSL$CERT_TOOL.COM choosing option 5 (Create a CA (Certification Authority) Certificate)
    1. When using SSL$CERT_TOOL.COM you must double-check your default prompts. You should always be working in directory:
      "ssl$root:[democa.certs]" and could mess up other products, like Apache, if you do not.
    2. all generated files will be named SERVER.* or SERVER_CA.* (if they are not, then you should rename them to these desired names)
    3. Sample Input:
       PEM Pass Phrase ? [] 
       Confirm PEM Pass Phrase ? [] 
       Encryption Bits ? [1024] 
       Default Days ? [3650] 
       CA certificate Key File ? [SSL$KEY:SERVER_CA.KEY] 
       CA certificate File ? [SSL$CRT:SERVER_CA.CRT] 
       Country Name ? [US] CA
       Organization Name ? [] Bell Canada
       Organization Unit Name ? [] Bell-ATS
       Common Name ? [CA Authority] Neil Rieck on node KAWC15       <<<--- official name of your CA Authority
       Require Unique Subject Names? [yes] no
       Display the CA certificate ? [N] 
  2. copy CA files from server* to client* as discussed in file: "SSL$EXAMPLES:SSL$EXAMPLES_SETUP.TEMPLATE"
    Sample Input:
    $ copy ssl$key:server_ca.key   ssl$key:client_ca.key
    $ copy ssl$certs:server_ca.crt ssl$certs:client_ca.crt
  3. execute script @SSL$CERT_TOOL.COM choosing option 3 (Create a Certificate Signing Request)
    Sample Input:
     Encrypt Private Key ? [N] 
     Encryption Bits ? [1024] 
     Certificate Key File ? [SSL$KEY:SERVER.KEY] 
     Certificate Request File ? [SSL$CSR:SERVER.CSR]
     Country Name ? [US] CA
     State or Province Name ? [] Ontario
     City Name ? [] Kitchener
     Organization Name ? [] Bell Canada
     Organization Unit Name ? [] Bell-ATS
     Common Name ? [bellics.com]                                                   <<<--- DNS name of our server
     Email Address ? [webmaster@bellics.com] neil@bellics.com
     Display the Certificate ? [N] 
  4. execute script @SSL$CERT_TOOL.COM choosing option 6 (Sign a Certificate Signing Request)
    Sample Input:
     CA Certificate File ? [SSL$CRT:SERVER_CA.CRT] 
     CA Certificate Key File ? [SSL$KEY:SERVER_CA.KEY] 
     Certificate Request File ? [SSL$CSR:SERVER.CSR] 
     Signed Certificate File ? [SSL$CRT:SIGNED.CRT] SSL$CSR:SERVER.crt            <<<--- a very important change
     Default Days ? [365] 3650                                      <<<--- make my life a little more convenient
     PEM Pass Phrase ? [] 
     Display the Certificate ? [N] 
    

    Caveat: 95% of the time you do not need the CLIENT files generated in the following 2 steps
     
  5. execute script @SSL$CERT_TOOL.COM choosing option 3 (choosing CLIENT files instead of SERVER)
  6. execute script @SSL$CERT_TOOL.COM choosing option 5 (choosing CLIENT files instead of SERVER)
  7. copy all files from ssl$root:[democa...]*.* to SYS$COMMON:[SYSHLP.EXAMPLES.SSL]        (not necessary for the QIO sample programs)
I/O from session #1 (Server)
<sr>	$
<ur>	run SSL$SIMPLE_SERV.EXE
I/O from session #2 (Client)
<sr>	$
<ur>	run SSL$SIMPLE_CLI.EXE
<sr>	Message to be sent to the SSL server:
<ur>	Hello There!				(end this message by hitting <ctrl-M> or <enter>)
<sr>	SSL connection using AES256-SHA
	Server certificate:
        	subject: /C=CA/ST=Ontario/L=Kitchener/O=Bell Canada
			/OU=Bell-ATS/CN=bellics.com/emailAddress=webmaster@bellics.com
        	issuer: /C=CA/O=Bell Canada/OU=Bell-ATS/CN=CA-SERVER
	Received 35 chars:'This message is from the SSL server'
I/O from session #1 (Server)
<sr>	Connection from 100007f, port bc71
	SSL connection using AES256-SHA
	Received 13 chars:'Hello There!		(there seems to be an <EOL> here)
	'
	$

Two Example Apps Require Modifications for Use With TCPware (in 2010)

These two apps:

  1. SSL$TCP_CLIENT_QIO_SSL.C
  2. SSL$TCP_SERVER_QIO_SSL.C

contain references for TCP/IP Services for OpenVMS so will not compile as-is under TCPware. You need to make the following modifications:

  1. replace this line:
        #include <tcpip$inetdef.h>
    with this one:
        #include "tcpware_include:ucx$inetdef.h"
  2. use an editor and do a global replace of this:
        TCPIP$C_SOCK_NAME
    with this:
        INET$C_SOCK_NAME
  3. use an editor and do a global replace of this:
        TCPIP$
    with this:
        UCX$

Caveat: these two example apps are the only ones which DO NOT use the certificates in the example directory (see declarations).

I/O from session #1 (Server)

<sr>	$
<ur>	run SSL$TCP_SERVER_QIO_SSL-TCPWARE.EXE	! the TCPware version of SSL$TCP_SERVER_QIO_SSL.exe)

I/O from session #2 (Client)

<sr>	$
<ur>	run SSL$TCP_CLIENT_QIO_SSL-TCPWARE.EXE	! the TCPware version of SSL$TCP_CLIENT_QIO_SSL.exe)
<sr>	Enter remote host:
<ur>	127.0.0.1
<sr>	Initiated connection to host: 127.0.0.1, port: 5555

	Info Callback state = 16, ret code = 1
		SSL_CB_HANDSHAKE_START

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		before/connect initialization

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 write client hello A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 read server hello A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 read server certificate A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 read server done A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 write client key exchange A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 write change cipher spec A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 write finished A

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 flush data

	Info Callback state = 4097, ret code = 1
		SSL_CB_CONNECT_LOOP
		SSLv3 read finished A

	Info Callback state = 32, ret code = 1
		SSL_CB_HANDSHAKE_DONE

	Info Callback state = 4098, ret code = 1
		SSL_CB_CONNECT_EXIT 
	SSL connection using AES256-SHA
	Server certificate:
		subject: /C=CA/ST=Ontario/L=Kitchener/O=Bell Canada
			 /OU=Bell-ATS/CN=bellics.com/emailAddress=webmaster@bellics.com
		issuer: /C=CA/O=Bell Canada/OU=Bell-ATS/CN=CA-SERVER
	Message to be sent to the SSL server: 
		--- From SSL QIO Client, Hey, Hello Server ---  
	Received 39 chars:'This message is from the SSL QIO server'

	Info Callback state = 16392, ret code = 256
		SSL_CB_WRITE_ALERT
		Alert = warning:close notify
	$ 

I/O from session #1 (Server)

<sr>	$
<ur>	run SSL$TCP_SERVER_QIO_SSL-TCPWARE.EXE	! this is the TCPware version of SSL$TCP_SERVER_QIO_SSL.exe
<sr>	. . . Waiting for a client connection on port: 5555
	. . . Accepted connection from host: 127.0.0.1, port: 32049
	SSL connection using AES256-SHA
	Received 48 chars from client:' --- From SSL QIO Client, Hey, Hello Server --- '
	$

Using the CLIENT/SERVER demos across different platforms

Up until this point, the client and server demos were running on the same platform (connecting via the loopback address of 127.0.0.1). To get the client demos to run from a different platform you must copy the server's CA Certificate into the client's chain file. In the demo programs this file is always named client_ca.crt

Note: you need the server CA certificate (which was sent out-of-channel) preinstalled on the client machine in order to prove that the signed certificate (which was sent in-channel) has been signed by a trusted CA. The purpose for all of this is to minimizing spoofing by a possible man-in-the-middle.

If you intend to connect to multiple servers, and the servers have been signed by different CAs, then you must merge all the CA certificates in the certificate chain file (client_ca.crt)

Debugging (without using the OpenSSL CLI)

Warning: You will drive yourself crazy attempting to make these client demos work with an unknown (not under your control) server. The prescribed way to diagnose then repair client problems is with the OpenSSL CLI (command line interpreter). For example, run the server example on platform 1 but then try connecting via openssl s_client on platform 2

I/O from session #1 (Server on platform 1)

<sr>	$							! my prompt
<ur>	run SSL$SIMPLE_SERV.EXE					! this defaults to port 5555

I/O from session #2 (Client on platform 2)

Note: SSL clients do not always specify certificates or keys

<sr>	$							! my VMS prompt
<ur>	openssl							!
<sr>	OpenSSL>						! my OPENSSL prompt 
<ur>	s_client -connect 142.180.39.15:5555 -ssl3 -debug
<sr>	CONNECTED(00000005)
	write to 00404FF0 [0040F838] (100 bytes => 100 (0x64))
	0000 - 16 03 00 00 5f 01 00 00-5b 03 00 4a 2a 64 cb 88   ...._...[..J*d..
	0010 - 41 dd 6b 75 23 99 4c af-40 04 0d 75 39 c9 33 46   A.ku#.L.@..u9.3F
	0020 - 6c 8a 2e 5c e3 b1 45 a6-a5 7c 07 00 00 34 00 39   l..\..E..|...4.9
	0030 - 00 38 00 35 00 16 00 13-00 0a 00 33 00 32 00 2f   .8.5.......3.2./
	0040 - 00 66 00 05 00 04 00 63-00 62 00 61 00 15 00 12   .f.....c.b.a....
	0050 - 00 09 00 65 00 64 00 60-00 14 00 11 00 08 00 06   ...e.d.`........
	0060 - 00 03 01                                          ...
	0064 - <SPACES/NULS>
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 16 03 00 00 4a                                    ....J
	read from 00404FF0 [0040A83D] (74 bytes => 74 (0x4A))
	0000 - 02 00 00 46 03 00 4a 2a-64 cb c7 34 17 80 14 c5   ...F..J*d..4....
	0010 - ad ca c7 39 79 bd be 28-d9 89 f0 f4 12 a6 22 fd   ...9y..(......".
	0020 - a7 ff 1c ed 45 96 20 d2-96 42 3b d3 90 dc cb 54   ....E. ..B;....T
	0030 - 48 03 a8 9d 78 29 7c 80-75 62 3e 20 08 ff be b5   H...x)|.ub> ....
	0040 - 8a ab 86 6f 83 5e f8 00-35                        ...o.^..5
	004a - <SPACES/NULS>
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 16 03 00 02 c5                                    .....
	read from 00404FF0 [0040A83D] (709 bytes => 709 (0x2C5))
	0000 - 0b 00 02 c1 00 02 be 00-02 bb 30 82 02 b7 30 82   ..........0...0.
	0010 - 02 20 02 09 00 a3 ff 03-94 ac f7 26 10 30 0d 06   . .........&.0..
	0020 - 09 2a 86 48 86 f7 0d 01-01 04 05 00 30 81 9f 31   .*.H........0..1
	0030 - 0b 30 09 06 03 55 04 06-13 02 63 61 31 10 30 0e   .0...U....ca1.0.
	0040 - 06 03 55 04 08 13 07 6f-6e 74 61 72 69 6f 31 12   ..U....Ontario1.
	0050 - 30 10 06 03 55 04 07 13-09 6b 69 74 63 68 65 6e   0...U....kitchen
	0060 - 65 72 31 14 30 12 06 03-55 04 0a 13 0b 62 65 6c   er1.0...U....bel
	0070 - 6c 20 63 61 6e 61 64 61-31 11 30 0f 06 03 55 04   l canada1.0...U.
	0080 - 0b 13 08 62 65 6c 6c 2d-61 74 73 31 1a 30 18 06   ...Bell-ATS1.0..
	0090 - 03 55 04 03 13 11 6b 61-77 63 31 35 2e 6f 6e 2e   .U....kawc15.on.
	00a0 - 62 65 6c 6c 2e 63 61 31-25 30 23 06 09 2a 86 48   bell.ca1%0#..*.H
	00b0 - 86 f7 0d 01 09 01 16 16-6e 65 69 6c 40 6b 61 77   ........neil@kaw
	00c0 - 63 31 35 2e 6f 6e 2e 62-65 6c 6c 2e 63 61 30 1e   c15.on.bell.ca0.
	00d0 - 17 0d 30 39 30 36 30 35-31 38 35 39 31 32 5a 17   ..090605185912Z.
	00e0 - 0d 31 30 30 36 30 35 31-38 35 39 31 32 5a 30 81   .100605185912Z0.
	00f0 - 9f 31 0b 30 09 06 03 55-04 06 13 02 63 61 31 10   .1.0...U....ca1.
	0100 - 30 0e 06 03 55 04 08 13-07 6f 6e 74 61 72 69 6f   0...U....Ontario
	0110 - 31 12 30 10 06 03 55 04-07 13 09 6b 69 74 63 68   1.0...U....kitch
	0120 - 65 6e 65 72 31 14 30 12-06 03 55 04 0a 13 0b 62   ener1.0...U....b
	0130 - 65 6c 6c 20 63 61 6e 61-64 61 31 11 30 0f 06 03   ell canada1.0...
	0140 - 55 04 0b 13 08 62 65 6c-6c 2d 61 74 73 31 1a 30   U....Bell-ATS1.0
	0150 - 18 06 03 55 04 03 13 11-6b 61 77 63 31 35 2e 6f   ...U....kawc15.o
	0160 - 6e 2e 62 65 6c 6c 2e 63-61 31 25 30 23 06 09 2a   n.bell.ca1%0#..*
	0170 - 86 48 86 f7 0d 01 09 01-16 16 6e 65 69 6c 40 6b   .H........neil@k
	0180 - 61 77 63 31 35 2e 6f 6e-2e 62 65 6c 6c 2e 63 61   awc15.on.bell.ca
	0190 - 30 81 9f 30 0d 06 09 2a-86 48 86 f7 0d 01 01 01   0..0...*.H......
	01a0 - 05 00 03 81 8d 00 30 81-89 02 81 81 00 e2 98 76   ......0........v
	01b0 - 67 f7 39 15 a5 b4 f9 69-eb fa 3a 39 c3 d2 8a 70   g.9....i..:9...p
	01c0 - e4 f1 72 cb 4c 44 20 d6-78 aa 3b 9c 9b 28 1d 56   ..r.LD .x.;..(.V
	01d0 - 77 7f b3 58 aa b2 fc 65-31 71 15 cf 3f f4 84 bd   w..X...e1q..?...
	01e0 - 9c b0 95 86 3c b5 d8 d5-7f d4 94 e4 0e ad cf 0d   ....<...........
	01f0 - e9 86 39 ee d4 b5 a6 7d-28 f7 92 40 79 22 d9 ce   ..9....}(..@y"..
	0200 - 9a 75 10 dc fe 61 43 2a-b4 91 9c ec 7c 4d af c5   .u...aC*....|M..
	0210 - 6f 34 d5 a3 b8 c3 09 d5-2f a7 4c e7 45 2e b2 08   o4....../.L.E...
	0220 - f5 6e 32 5e ae 0d 92 58-20 4a 96 75 a1 02 03 01   .n2^...X J.u....
	0230 - 00 01 30 0d 06 09 2a 86-48 86 f7 0d 01 01 04 05   ..0...*.H.......
	0240 - 00 03 81 81 00 72 db b7-6e f7 32 28 6f 80 97 62   .....r..n.2(o..b
	0250 - 8b bf 7a cf 73 00 07 5c-ba 54 46 59 12 45 2f ab   ..z.s..\.TFY.E/.
	0260 - 5d 49 7a 9b 42 8b 7c e8-e2 34 05 96 b8 4b 51 17   ]Iz.B.|..4...KQ.
	0270 - fa bf 4f 56 76 8e e0 56-b2 f1 13 a3 4f 1f 6d eb   ..OVv..V....O.m.
	0280 - 8d df 37 9a 4c 6e 43 84-34 9f 21 63 4e 36 cb 68   ..7.LnC.4.!cN6.h
	0290 - ef 48 92 65 99 0d f1 de-a4 38 8b 21 28 0b 3e 3c   .H.e.....8.!(.><
	02a0 - 23 7e f7 d8 4c 89 3a 3a-b1 e4 98 61 dc 60 25 24   #~..L.::...a.`%$
	02b0 - 6f 19 3a 0d 09 79 85 f3-53 11 07 d0 a3 d9 6b 3e   o.:..y..S.....k>
	02c0 - e7 2c 55 57 f6                                    .,UW.
	depth=0 /C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	verify error:num=18:self signed certificate                      <<<---Note that this server certificate is self-signed
	verify return:1
	depth=0 /C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	verify return:1
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 16 03 00 00 04                                    .....
	read from 00404FF0 [0040A83D] (4 bytes => 4 (0x4))
	0000 - 0e                                                .
	0004 - <SPACES/NULS>
	write to 00404FF0 [00302E70] (137 bytes => 137 (0x89))
	0000 - 16 03 00 00 84 10 00 00-80 39 fa c4 8f bb d0 1b   .........9......
	0010 - 5a b9 2b 0f a4 03 5b 09-b9 b6 88 f7 6d f7 2f ec   Z.+...[.....m./.
	0020 - a4 ab ee 89 ac 9a 3d d9-9c 92 b6 90 9b ed 8f 76   ......=........v
	0030 - 88 85 86 f2 24 bd 58 38-1c d2 e7 f7 4c cb c2 37   ....$.X8....L..7
	0040 - b7 b3 b1 58 78 30 0a d6-02 e3 5f e8 bc e2 a4 94   ...Xx0...._.....
	0050 - 2f f6 3d b0 b3 15 08 8e-f4 d2 20 fc 42 a6 ae 17   /.=....... .B...
	0060 - 46 3b ac 24 c8 ae 13 3f-cb af b3 b8 be 91 46 4f   F;.$...?......FO
	0070 - 9e 79 37 0d fa b6 b2 5c-e4 5d ed a7 d2 93 4d bd   .y7....\.]....M.
	0080 - a3 df bb 4e fe cb f6 26-69                        ...N...&i
	write to 00404FF0 [00302E70] (6 bytes => 6 (0x6))
	0000 - 14 03 00 00 01 01                                 ......
	write to 00404FF0 [00302E70] (69 bytes => 69 (0x45))
	0000 - 16 03 00 00 40 2e 20 38-5b 89 c8 1e 5b e3 d8 82   ....@. 8[...[...
	0010 - c1 aa 3b b8 d8 a2 a4 5e-49 14 59 3c fb 83 63 53   ..;....^I.Y<..cS
	0020 - eb c3 99 b3 b7 2f 80 53-1d 9f cf 81 80 44 f3 e9   ...../.S.....D..
	0030 - d2 ce a1 ce 3e c1 25 24-56 cb 22 45 dc 59 dd 0c   ....>.%$V."E.Y..
	0040 - dc b7 a2 26 f7                                    ...&.
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 14 03 00 00 01                                    .....
	read from 00404FF0 [0040A83D] (1 bytes => 1 (0x1))
	0000 - 01                                                .
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 16 03 00 00 40                                    ....@
	read from 00404FF0 [0040A83D] (64 bytes => 64 (0x40))
	0000 - 00 bc 02 d4 79 e6 ae 7e-26 16 fd 6b 41 b3 0c c0   ....y..~&..kA...
	0010 - a5 6a 11 b6 c7 7a 4e 9c-e3 b4 5c 3b 50 e1 2e 9b   .j...zN...\;P...
	0020 - ef 5f aa 22 42 96 cb 33-f6 7a 72 18 ae d2 e7 1c   ._."B..3.zr.....
	0030 - 2a 99 e9 bf be 86 81 fd-f8 8b ed d4 c5 d7 8d 6a   *..............j
	---
	Certificate chain
	 0 s:/C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	   i:/C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	---
	Server certificate
	-----BEGIN CERTIFICATE-----
	MIICtzCCAiACCQCj/wOUrPcmEDANBgkqhkiG9w0BAQQFADCBnzELMAkGA1UEBhMC
	[...snip...]
	E6NPH23rjd83mkxuQ4Q0nyFjTjbLaO9IkmWZDfHepDiLISgLPjwjfvfYTIk6OrHk
	mGHcYCUkbxk6DQl5hfNTEQfQo9lrPucsVVf2
	-----END CERTIFICATE-----
	subject=/C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	issuer=/C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc15.on.bell.ca/emailAddress=neil@kawc15.on.bell.ca
	---
	No client certificate CA names sent
	---
	SSL handshake has read 877 bytes and written 312 bytes
	---
	New, TLSv1/SSLv3, Cipher is AES256-SHA
	Server public key is 1024 bit
	SSL-Session:
	    Protocol  : SSLv3
	    Cipher    : AES256-SHA
	    Session-ID: D296423BD390DCCB544803A89D78297C8075623E2008FFBEB58AAB866F835EF8
	    Session-ID-ctx: 
	    Master-Key: 38C8558FDF4A37EBF3202C5C464EBE60767A31B47B04B60C80A62FDE9D7819F2FDD8CF31E89B5CC26AC50611EFA6DDB5
	    Key-Arg   : None
	    Start Time: 1244292299
	    Timeout   : 7200 (sec)
	    Verify return code: 18 (self signed certificate)
<ur>	hello<enter>						! I typed this on my keyboard
<sr>	write to 00404FF0 [0040F838] (74 bytes => 74 (0x4A))
	0000 - 17 03 00 00 20 bc b3 9c-e7 04 1f 02 57 b9 5f b2   .... .......W._.
	0010 - e5 15 da b5 f2 00 c5 3e-3f 9b 23 ef 10 e6 94 7c   .......>?.#....|
	0020 - 8d 5a 94 2b b0 17 03 00-00 20 3f 1c aa 08 68 fa   .Z.+..... ?...h.
	0030 - 2b 99 6f 14 e1 17 c6 c9-14 71 c8 a8 0c d1 bd ab   +.o......q......
	0040 - 79 e5 1a 0b 71 f9 78 df-dd 2f                     y...q.x../
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 17 03                                             ..
	0005 - <SPACES/NULS>
	read from 00404FF0 [0040A83D] (32 bytes => 32 (0x20))
	0000 - b5 32 b9 5b 47 78 e9 52-9a b0 e5 c8 34 65 0d 56   .2.[Gx.R....4e.V
	0010 - 06 7a f7 67 c4 9d 28 51-52 bc 44 d4 e0 ea f0 79   .z.g..(QR.D....y
	read from 00404FF0 [0040A838] (5 bytes => 5 (0x5))
	0000 - 17 03 00 00 40                                    ....@
	read from 00404FF0 [0040A83D] (64 bytes => 64 (0x40))
	0000 - 59 d6 34 d8 94 e6 38 e2-8a ea 23 f8 81 43 6c eb   Y.4...8...#..Cl.
	0010 - ee 97 df f1 2a 98 95 6f-28 4e a1 f8 03 90 3c 26   ....*..o(N....<&
	0020 - 67 55 ec 14 6c 82 4e 46-6e 16 8a ea e7 a9 ca 47   gU..l.NFn......G
	0030 - 7a c6 ce 37 73 b0 da 9a-02 13 5a fb b5 60 74 59   z..7s.....Z..`tY
	write to 00404FF0 [0040F838] (74 bytes => 74 (0x4A))
	0000 - 17 03 00 00 20 0d be ad-d9 e9 e2 df 5b 5e 76 13   .... .......[^v.
	0010 - 75 81 c9 fa c7 a3 84 80-eb 7f e5 5c 59 5f 0a 7c   u..........\Y_.|
	0020 - ad 29 f6 70 32 17 03 00-00 20 a3 11 4a 53 65 b7   .).p2.... ..JSe.
	0030 - 33 cd d9 40 d3 e1 3e 6f-f2 1b 91 e8 7e 3f a9 1f   3..@..>o....~?..
	0040 - 3c b4 13 69 d1 5e 8d 65-e3 4e                     <..i.^.e.N
	write to 00404FF0 [0040F838] (74 bytes => -1 (0xFFFFFFFF))
	write:errno=32
	OpenSSL>

I/O from session #1 (Server on platform 1)

<sr>	$
<ur>	run SSL$SIMPLE_SERV.EXE
<sr>	Connection from 1027b48e, port 9ea3
	SSL connection using AES256-SHA
	Received 6 chars:'hello
	'
	$ 

Hints To Correct Your Problem

  • copy your server's CA (certificate authority) certificate to the appropriate directory of your client machine (you may need to append it to an existing file called a "certificate chain file")
    • now restart the openssl -connect command with the -CAfile parameter (or -CApath if you have set up things properly). You will need to quote any mixed-case parameters.
    • Note: most internet clients like browsers and email readers have access to more than one hundred preloaded CA certificates. Since you are rolling your own client app then you will need to do this yourself (on windows, go to START button >>> SETTINGS item >> CONTROL PANEL item >> INTERNET PROPERTIES item >>> CONTENT tab >>> CERTIFICATES tab, then export a few trusted root certificates).
    • in many ways, copying the certificate of the CA from the server to the client through an out-of-channel path is similar to copying the PUB file to the client machine when setting up an SSH connection
  • switch to a self-signed certificate and disable server certificate authentication (not recommended)
    • this will not protect you against a man-in-the-middle attack but maybe you don't care because you are running on a private intranet

Creating those pesky compound PEM Files

Facts:

  1. PEM is an acronym for Privacy-enhanced Electronic Mail but it is used in many more places today than email
  2. OpenSSL can generate Certificate and Key files which then can be saved in either binary format or PEM format
  3. There is a third use for PEM files which I am going to describe now

Many SSL implementations (like my gSOAP client software) employ a compound PEM file which is poorly documented, or perhaps and industry secret, or perhaps just lost to the ages. So what follows is an example of a few hacks one afternoon

  File Name Notes Distribute?
Input Files kawc09.crt a certificate file and public key for host kawc09.on.bell.ca Y
  kawc09.key a private key file for host kawc09.on.bell.ca N
Output Files kawc09.pem a PEM file for host kawc09.on.bell.ca (concatenation of kawc09.key and kawc09.crt) N
  30A5DF47.0 a copy of file kawc09.crt whose name is contains the computed hash of file kawc09.pem N


===============================================================================================
 file : AAA_PEM_NOTES.TXT
 edit : NSR 2012-02-14
 topic: 1. general stuff about certificates on our system
	2. creating a PEM (required by SSL calls made by our SOAP-based client software)
	3. Note: the WASD implementation of HTTPd requires PEM files (reference)
 notes:	1. all "our" production certificate files are located here as HPE suggests:
			sys$sysdevice:[certificates]
	2. a logical name has been defined to reference this directory:
			$define/system  vms_cert_dir  sys$sysdevice:[certificates]
	3. apache files like "apache$common[.conf]ssl.conf" need to reference this logical name
	4. before experimenting with the certificate tools in directory SSL$COM you might
	   consider copying production certificates to SSL$CERTS which points to here:
			ssl$root:[000000.democa.certs]
	5. OpenVMS caveat: when using the openssl CLI on OpenVMS you will need to double-quote
	   mixed-case parameters to preserve case 
 legend:
	<ur> = user response
	<sr> = system response
===============================================================================================
<sr> $
<ur> set def SSL$CERTS								! change default directory
<sr> $
<ur> copy/concat kawc09.key,kawc09.crt kawc09.pem				! create a server PEM file
<sr> $
--------------------------------------------------------------------------------
	note: this next command will only work IF we first created kawc09.csr
	then sent it to another organization to have it signed. The signer will
	send back kawc09.crt and chain.crt  
--------------------------------------------------------------------------------
<ur> openssl  verify  "-CAfile" chain.crt -verbose -purpose any kawc09.pem	! test the pem
<sr> kawc09.pem: OK
     $
--------------------------------------------------------------------------------
	self-signed certificates require a hash file
--------------------------------------------------------------------------------
<ur> openssl x509 -hash -noout -in  kawc09.pem					! compute the hash (output to stdout)
<sr> 30a5df47
     $
<ur> copy kawc09.crt 30a5df47.0							! use hash to create the file: hash.0 
<sr> $
<ur> define dvlp_cert_dir SSL$ROOT:[000000.DEMOCA.CERTS]			! define a logical name for use below
<sr> $
<ur> openssl  verify  "-CApath" dvlp_cert_dir -verbose -purpose any kawc09.pem	! test certs with path
<sr> kawc09.pem: OK
     $
--------------------------------------------------------------------------------
	is the hash file required? (yes)
--------------------------------------------------------------------------------
<ur> ren 30A5DF47.0 30A5DF47.yada						! rename hash file for next test
<sr> $
<ur> openssl  verify  "-CApath" vms_cert_dir -verbose -purpose any kawc09.pem	! test certs with path
<sr> kawc09.pem: /C=CA/ST=Ontario/L=Kitchener/O=Bell Canada/OU=Bell-ATS/CN=kawc09.on.bell.ca/emailAddress=neil@kawc09.on.bell.ca
     error 18 at 0 depth lookup:self signed certificate
     OK
     $
<ur> ren 30A5DF47.yada 30A5DF47.0						! restore hash file name
<sr> $
<ur> openssl  verify  "-CApath" vms_cert_dir -verbose -purpose any KAWC09.PEM	! test certs with path (again)
<sr> kawc09.pem: OK
     $
==========================================================================================================================
	<<< proof that Apache has its own version of SSL >>>

	notes:	1. danger danger danger
		2. only try this on a backup lab system with no one logged on >>>
		3. if your running system relies upon SSL for various security functions, then removing SSL may render
			your OpenVMS 8.x system unusable
==========================================================================================================================
	uninstall SSL on OpenVMS-8.4 (node kawc98)
		$prod remov prod ssl
			note: you will get a warning saying not to do this because of linkages to OpenVMS (but not Apache)
				ignore the warning and remove SSL anyway
	reboot
		@sys$update:autogen reboot
	test Apache and notice that https://kawc98.on.bell.ca still works (Apache has its own baked-in OpenSSL engine)
	install SSL on OpenVMS-8.4
		$PRODUCT instal/options=NOVALIDATE_KIT SSL
			note: you now need OPTIONS because SSL is required to validate kits (oops)
	reboot
		@sys$update:autogen reboot
==========================================================================================================================

*** End of Section: Application Development ***

"HP SSL" vs "HP SSL1" (the name game part-2)

Ancient History

In 2010, HP (now HPE) published a product named HP SSL-1.4 for OpenVMS which was architecturally different from HP SSL-1.3 for OpenVMS. So much so that it came with this warning: any programs compiled and linked against SSL-1.3 needed to be recompiled and relinked. This is fine if "you have access to the source code" but in the case of applications built around third party software, you would need to contact the vendor. I seem to remember related warnings about some third party products like IBM WebSphere MQ and XCOM.

For example, this blast-from-the-past Solution Document: RO67803 from Computer Associates (a.k.a. CA) is dated 2014 and instructs XCOM users on OpenVMS to replace HP SSL-1.4 with HP SSL-1.3 which prompts me to wonder if they Computer Associates lost the XCOM source code. This recommendation is a big mistake for many reasons.

  1. First off, new security libraries are always better than old ones.
  2. Secondly HPE had already recommended this scheme ( https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c02449766 ) where affected users could define a process-level logical name which would point the affected application at the old library in an alternate location
  3. Newer versions of OpenVMS utilities (like BACKUP and ENCRYPT to only name two) now require 1.4 so going back to 1.3 would certainly break those apps (bad news if you need to restore an encrypted backup saveset)

Recent Progress (2016)

  • If you are running OpenVMS-8.4 then the software installed in your system is most likely HP SSL-1.4 (based upon OpenSSL-0.9.x) but have you installed the latest patch kit?
    • This is mostly client-side software; it has nothing to do with certain system-side software apps like CSWS (a.k.a. Apache) but might affect newer versions of WASD or MariaDB
    • However, it is used for doing other things like:
      • supporting SSL in third party applications
      • supporting SSL in your own client-side applications
      • encrypting local files (think: savesets)
      • validating patch kits from HPE and VSI
    • OpenSSL is mandatory with OpenVMS-8.4 and higher
    • OpenSSL is optional with OpenVMS-7.x and lower (but any platform trapped in time like this is probably not using OpenSSL)
    • check this document to verify your patch level: http://h41379.www4.hpe.com/openvms/products/ssl/ssl.html
  • In 2016, HPE published a product named HPE SSL1 for OpenVMS which is based upon OpenSSL-1.0 and higher (which means that older stuff is based upon OpenSSL-0.9 and lower)
    • caveat: the product is advertised as HPE SSL1 for OpenVMS is visible as HP SSL1 in the product command (see yellow box below)
  • Unlike the debacle HP created in 2010, HP implemented SSL1 so it can coexist with SSL
    • HP SSL (traditional)
      • logical names of the form SSL$whatever will be used to access the older binaries, older cert tools, as well as the older OpenSSL CLI
      • the run-time library files are prefixed with SSL$ like so: sys$library:SSL$LIBSSL_SHR32.EXE
      • example c-language programs are found here: ssl$examples
    • HP SSL1 (new)
      • logical names of the form SSL1$whatever will be used to access the newer binaries, newer cert tools, as well as the newer OpenSSL CLI
      • the run-time library files are prefixed with SSL1$ like so: sys$library:SSL1$LIBSSL_SHR32.EXE
      • example c-language programs are found here: ssl1$examples
  • Installation Requirements:
    • On Itanium you need to be running OpenVMS-8.4 patch kit 1200 (or higher)
    • Then you need to install the patch for MANAGE-200 which was released in 2015 but is not automatically installed with patch kit 1200
  • Checking SSL on your OpenVMS system (this is the view after installing the newer patch kit)
    <sr>	$
    <ur>	prod sho pro *ssl*
    <sr>
    	------------------------------------ ----------- ---------
    	PRODUCT                              KIT TYPE    STATE
    	------------------------------------ ----------- ---------
    	HP I64VMS SSL V1.4-502               Full LP     Installed
    	HP I64VMS SSL1 V1.0-2L               Full LP     Installed
    	------------------------------------ ----------- ---------
    	2 items found
    	
    	$

    and now you can see why HP's alternate naming convention has really confused SSL on OpenVMS. How would anyone know that the first product only supports SSL-0.9 and lower?

comments:

  • According to this official document, OpenSSL-1.0.0 and everything below it are no longer being supported by the developers of OpenSSL. So if you are using SSL/TLS to do anything on the internet then it is (maybe) imperative that your update your system and applications ASAP
  • Let me complement HP for deciding to support both OpenSSL packages on the same system. Why? I recently (2018.01.xx) updated a Linux system from CentOS-7.2 to CentOS-7.4 which updated OpenSSL to a new version that did not support sslv2 or sslv3. That system was required to connect to an old version of SQL Server 2005 (running on Windows Server 2003) via msodbcsql (ms-odbc-sql) which only supports sslv2. Click here to read more.

Recent Third-Party Progress (2017)

  • The 2014 release of MariaDB-5.5-25 from Mark Berryman was linked against an open source SSL library known as "YASSL" (yet another SSL) which is now known to have some security issues.
  • The 2017 release of MariaDB-5.5-58, also from Mark Berryman, now links against run-time libraries found in location "sys$library". Updating your SSL libraries with updates published by HPE or VSI will ensure that MariaDB-5.5-58 is using the most up-to-date SSL protocols

y2k20 - a potential dilemma in 2020

 Modern browsers in 2020 will expect to "connect HTTPS" only using TLSv1.2 and TLSv1.3 (this assumes that support for everything from SSLv3 to TLSv1.1 will be removed)

click here to learn more

Local Links

External Links

Free OpenSSL books

OpenSSL for OpenVMS (published by HP/HPE)

OpenSSL for OpenVMS (other)

SSL (general) 

OpenSSL Tutorials

OpenSSL for Windows

  • because many times you can learn more by connecting to an UNIX/Linux/OpenVMS server from your PC
    • If you only have one server platform then you have no other choice
    • In a pinch, you can put two PCs back-to-back (type "openssl s_server" on one, type "openssl c_client" on the other)
    • In a real pinch you can run server and client on the same machine but it's not really the same
  • http://www.slproweb.com/products/Win32OpenSSL.html  - very high quality work from Shining Light Productions; please donate a few bucks if you can
  • http://gnuwin32.sourceforge.net/packages/openssl.htm

Compaq C Run-Time Library Reference Manual for OpenVMS Systems


 Back to Home
 Neil Rieck
 Waterloo, Ontario, Canada.