Programmer's Reference


Overview

The SciSslSocketInterface provides a Smalltalk application with a set of classes and methods to construct tasks that use the Secure Socket Layer and/or Transport Layer Security protocols to provide secure communications over TCP/IP.

Support for these protocols is based on the OpenSSL API, an open source implementation of SSL/TLS based on the SSLeay library developed by Eric A. Young and Tim J. Hudson. The use of OpenSSL is provided under a dual license, the OpenSSL License and the SSLeay License. Although the binaries for the OpenSSL library are provided with VisualAge Smalltalk, it is recommended that the user download and compile OpenSSL.

Source and documentation can be found at http://www.openssl.org. Installation instructions for most platforms are provided. Another excellent source of information are the various mailing lists that exist for OpenSSL users and developers to share information. There are instructions at the above url for joining the list, or you can search archives for answers to your questions. One such archive, for the openssl-users mailing list, can be found at http://marc.theaimsgroup.com/?l=openssl-users.

The API for OpenSSL is very large; therefore, VisualAge Smalltalk supports a subset of the functions in the library. You can easily add additional OpenSSL functions calls. The steps to do so are:

  1. Check the documentation or source code for the function for which you wish to add support. Visit http://www.openssl.org/docs or, if you've compiled the OpenSSL library yourself, check the man pages.
  2. Open an browser on the SciOpenSSLInterface subapplication.
  3. Display the SciSslOpenSSLInterface class >> _PRAGMA_SciSslFunctions method in the lower pane.
  4. Find the alphabetical placement for the name of the function you want to wrap.
  5. Add a line like the one below substituting the name of the function, the appropriate library, the correct number and types of arguments to the function, and the proper return type.

    As an example, let's look at the the declaration for SSL_CTX_set_cipher_

    (name: SSL_CTX_set_cipher_list isConstant: true valueExpression: 
    'PlatformFunction fromArray: #(''C'' ''SSL_CTX_set_cipher_list'' nil ''SSL_LIB'' #(#pointer #pointer) #int32)')
     
    

    This declaration specifies a C language library call located in the SSL_LIB library (see the note below concerning the libraries) that takes two pointers as arguments and returns a 32-bit signed integer.

  6. In the SciSslBlockingDispatcher class, located in the SciSslOpenSSLInterface subapplication, look at the instance methods. The SciSslBlockingDispatcher performs the actual function calls; therefore, you will need to add a method for your function. To continue the SSL_CTX_set_cipher_list example above, you would create the following method
    SciSslBlockingDispatcher>>callSSL_CTX_set_cipher_listWith: ctx with: aStringPtr
     
    ^self callWithSslErrorCheck: SciSslFunctions::SSL_CTX_set_cipher_list
      withArguments: (Array with: ctx with: aStringPtr)
      errorBlock: [ :value | value <= 
    

    This specifies that you want error checking to be turned on, and provides the name of the function within the SciSslFunctions Pool Dictionary. See the OpenSSL documentation to learn the return values associated with an error for the function In this case, the API returns a -1 when an error has occurred. Be sure to check the result of you call* method for an instance of SciSslError

.

Note:
There are two main libraries in which the OpenSSL API resides. SSL_LIB includes all the OpenSSL API calls. CRYPTO_LIB contains all the cryptographic API calls. These library names are mapped to the appropriate shared libraries located in <vast root directory>\bin and are platform-specific.
Note:
On supported UNIX platforms (AIX, Solaris, HP-UX) you will need to create a source of random bits for the PRNG in OpenSSL; otherwise you will get the PRNG not seeded error. To overcome this obstacle, you can install a program called EGD - Entropy Gathering Daemon. The Random Number Generator in OpenSSL relies on the existence of a pool of random bits from which to seed the RNG. This is not an issue on most Linux systems because of the use of /dev/random which runs in the background and grabs bits from various places on a running system. EGD is a Perl program that simulates this behavior. More information about this issue can be found at http://www.openssl.org/support/faq.html. You need to have Perl 5 to install EGD.

As another option, you can provide a file containing random bits for the PRNG to use. The difficulty with this approach is that entropy gathering daemons such as EGD or /dev/urandom in Linux provide better seeding material than other approaches. The deciding factor as to which path to take should be level of security you require.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]