216
The functions that read DER representations also require a
BIO
or
FILE
object as their first argument, depending on which function is used. The second argument is a pointer to an object of
the type that is being read, which is treated just the same as the first argument to the base functions. That is, when
NULL
or a pointer to
NULL
is specified, a new object of the appropriate type is created; otherwise, the specified object is populated. The return value from these functions is
NULL
if an error occurs; otherwise, the return is the object that was populated. Example 8-4
demonstrates.
Example 8-4. Reading and writing DER-encoded objects using the BIO and file functions
BIO bio = BIO_newBIO_s_memory; RSA rsa = RSA_generate_key1024, RSA_F4, NULL, NULL;
i2d_RSAPrivateKey_biobio, rsa; FILE fp = fopenrsakey.der, rb;
RSA rsa = NULL; d2i_RSAPrivateKey_fpfp, rsa;
8.6.2 Writing and Reading PEM-Encoded Objects
The same objects that can be read and written in DER format can also be read and written in PEM format. The interface to the PEM format is somewhat different from the DER interface. To begin
with, it supports writing to and reading from a BIO or a file; it does not support memory buffers like the DER interface does. As it turns out, this isnt much of a limitation since you can just use a
memory BIO. All of the function declarations can be found in the header file opensslpem.h.
The functions for writing public keys and parameters all share the same basic signature. The functions for writing to a BIO require a
BIO
object as the first argument and the object type as the second argument. The functions for writing to a file require a
FILE
object as the first argument and the object type as the second argument. Each of the functions, regardless of whether theyre
writing to a
BIO
object or a
FILE
object, return zero if an error occurs and nonzero if the operation was successful.
The functions for writing private keys are a bit more complex because the PEM format allows them to be encrypted before theyre encoded and written out. Each function requires a
BIO
or
FILE
object to write to, the object to be written, a password callback function, and symmetric cipher information.
int PEM_write_OBJNAMEFILE fp, OBJTYPE obj, const EVP_CIPHER enc, unsigned char kstr, int klen, pem_password_cb
callback, void cb_arg;
fp The file to write to.
obj The object that contains the data to be written. The type of this object can be
DSA
,
EVP_PKEY
, or
RSA
. enc
217
The optional cipher to use to encrypt the key data. This can be any symmetric cipher object supported by OpenSSL. Refer to
Chapter 6 for a comprehensive list of the
available options. If this is specified as
NULL
, the key data is written unencrypted, and the remaining arguments are ignored.
kstr An optional buffer that contains the password or passphrase to use for encryption. If this
is specified as non-
NULL
, the password callback function is ignored, and the contents of this buffer are used.
klen Specifies the number of bytes contained in the
kstr
buffer. callback
A callback function to obtain the password or passphrase for encrypting the key data. Its signature is described below.
cb_arg Application-specific data that is passed to the callback function. If the callback function
and the
kstr
buffer are specified as
NULL
, this is interpreted as a
NULL
-terminated, C- style string that is used as the password or passphrase to encrypt the key data. If it is also
specified as
NULL
, the default password callback function is used. The default password callback function prompts the user to enter the password or passphrase.
The functions that are used to write to a BIO object have the same signature, except that the
FILE
object is replaced with a
BIO
object. The return values from functions that write private keys are the same as the values from functions that write public keys and parameters: zero if an error
occurs, nonzero otherwise. The password callback function, if one is used, has the following signature:
typedef int pem_password_cbchar buf, int len, int rwflag, void cb_arg;
buf A buffer that the password or passphrase will be written into.
len The size of the password buffer.
rwflag Indicates whether the password or passphrase will be used to encrypt or decrypt the PEM
data. When writing PEM data, this argument will be nonzero. When reading PEM data, this argument will be zero.
cb_arg Application-specific. It is passed from the function that caused the password callback
function to be called.
218
The functions for reading public keys, private keys, and parameters all share a similar signature. Each requires a
BIO
or a
FILE
object to read from, an object to populate with the data that was read, and a password callback function.
OBJTYPE PEM_read_OBJNAMEFILE fp, OBJTYPE obj, pem_password_cb callback,
void cb_arg;
fp The file to read from.
obj The object to populate with the data that is read. If it is specified as
NULL
, a new object of the appropriate type is created and populated. If it is specified as a pointer to
NULL
, a new object of the appropriate type is also created and populated. In addition, it receives a
pointer to the newly created object. callback
A callback function to obtain the password or passphrase if one is required. A password or passphrase is required only if the PEM data being read is encrypted. Normally, only
private keys are encrypted. The callback function may be specified as
NULL
. cb_arg
Application-specific data that is passed to the callback function. If the callback is specified as
NULL
, this argument is interpreted as a
NULL
-terminated, C-style string containing the password or passphrase to use. If both the callback and this argument are
specified as
NULL
, the default password callback function is used. The functions that are used to read from a BIO have the same signature, except that the
FILE
object is replaced with a
BIO
object. The return value from the reading functions is always a pointer to the object that was populated with the data that was read. If an error occurs reading the
PEM data,
NULL
is returned. See Table 8-2
.
Table 8-2. Functions for reading and writing PEM encodings of public key objects Type of
object OpenSSL
object type
Function to write the PEM representation
Function to read the PEM representation
Diffie- Hellman
parameters
DH PEM_write_DHparams
PEM_write_bio_DHparams PEM_read_DHparams
PEM_read_bio_DHparams
DSA parameters
DSA PEM_write_DSAparams
PEM_write_bio_DSAparams PEM_read_DSAparams
PEM_read_bio_DSAparams
DSA public key
DSA PEM_write_DSA_PUBKEY
PEM_write_bio_DSA_PUBKEY PEM_read_DSA_PUBKEY
PEM_read_bio_DSA_PUBKEY
DSA private key
DSA PEM_write_DSAPrivateKey
PEM_write_bio_DSAPrivateKey PEM_read_DSAPrivateKey
PEM_read_bio_DSAPrivateKey
219
RSA public key
RSA PEM_write_RSA_PUBKEY
PEM_write_bio_RSA_PUBKEY PEM_read_RSA_PUBKEY
PEM_read_bio_RSA_PUBKEY
RSA private key
RSA PEM_write_RSAPrivateKey
PEM_write_bio_RSAPrivateKey PEM_read_RSAPrivateKey
PEM_read_bio_RSAPrivateKey EVP_PKEY
public key
EVP_PKEY PEM_write_PUBKEY
PEM_write_bio_PUBKEY PEM_read_PUBKEY
PEM_read_bio_PUBKEY EVP_PKEY
private key
EVP_PKEY PEM_write_PrivateKey
PEM_write_bio_PrivateKey PEM_read_PrivateKey
PEM_read_bio_PrivateKey
TE AM
FL Y
Team-Fly
®
220
Chapter 9. OpenSSL in Other Languages
So far, weve discussed OpenSSL in the context of the C programming language, but you dont have to use C to use OpenSSL Language bindings are available for many different languages,
including Java, Perl, PHP, Python, and others. Unfortunately, none of the non-C language bindings that weve come across are as complete as the C API; nonetheless, it is important to
discuss at least a few of the more popular and best-supported language bindings that are available.
The first section of this chapter is a discussion of Net::SSLeay, the most popular and complete module that is widely available for Perl. Be careful not to confuse Net::SSLeay with
Crypt::SSLeay. The latter package is intended only to add support for HTTPS to the LWP package a popular WWW interface library for Perl and does not provide the additional interfaces to
OpenSSL that Net::SSLeay does. The second section of this chapter is a discussion of M2Crypto, the most popular and complete suite of modules that is widely available for Python. The third
section of this chapter is a brief discussion of the experimental OpenSSL extensions available in PHP 4.0.4 and newer versions.
For the purposes of these discussions, we assume that you have a familiarity with the language that is being discussed and its accompanying tools. It is not our intent to guide you through the
installation of the modules or the common usage of the language. The specific purpose of this chapter is to demonstrate how to use the modules and get you started with OpenSSL in your own
programs.
9.1 Net::SSLeay for Perl
Net::SSLeay is the most complete OpenSSL module available for Perl. It is written and maintained by Sampo Kellomäki
samposymlabs.com and can be found on the Web at
http:www.symlabs.comNet_SSLeay . As is the case with most Perl modules, it is also available
from CPAN. Unfortunately, its installation is not as straightforward as one might hope, so take care in reading the accompanying installation instructions for guidance.
As its name suggests, the module has its roots in the old SSLeay library originally developed by Eric Young, which provides the foundation upon which OpenSSL has been built. SSLeay evolved
into OpenSSL several years ago, and Net::SSLeay hasnt supported old versions of SSLeay since early 1999. At the time of this writing, the latest version of Net::SSLeay is Version 1.13 and
requires OpenSSL 0.9.6c or later.
The module comes with a fair number of scripts that serve as examples to demonstrate how to use the modules basic functionality. It provides Perl bindings for many of the low-level OpenSSL
library functions. Many convenience functions that are intended for use at a low level are also included. The module also contains several high-level functions that you can use to perform
common tasks involving OpenSSL, such as obtaining a file securely from the Web or securely posting data to a CGI script.
A limited amount of documentation is also included with the module. A quick-reference file that contains a list of the functions that are exported is included, along with a simple one-line
description of each. The main Perl module file, SSLeay.pm, also contains some documentation in perldoc format of the functions the module adds to the OpenSSL bindings. Aside from the quick-
reference file, no additional documentation is provided for the OpenSSL bindings. In fact, the author refers you to the OpenSSL documentation and source code for more information.