Writing and Reading PEM-Encoded Objects

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.