Net::SSLeay Error Handling Net::SSLeay Utility Functions

222

9.1.2 Net::SSLeay Error Handling

In addition to providing Perl bindings for many of OpenSSLs error handling functions, three utility functions are provded by Net::SSLeay to handle error conditions: print_errsmsg This function returns a string containing a list of all of the OpenSSL errors that occurred since the OpenSSL function ERR_get_error was last called. A newline character separates each error in the returned string, and each error is prefaced with the message string that you specify as an argument. Additionally, if the trace variable is any nonzero value, the errors will be printed to stderr via Perls warn function. die_if_ssl_errormsg This function will cause your program to terminate immediately by calling die with the message that you pass as an argument if an OpenSSL error has occurred. The function simply calls print_errs to determine if any errors have occurred. If print_errs returns any errors, the program is terminated. die_nowmsg This function will cause your program to terminate immediately by calling die with the message that you pass as an argument. Before calling die , print_errs is called so that any errors will be printed to stderr if the trace global variable is set to any nonzero value.

9.1.3 Net::SSLeay Utility Functions

Net::SSLeay provides many high-level utility functions that simplify the use of OpenSSL. Theyre mostly wrappers around the low-level OpenSSL functions for which the module also provides bindings. Several of the functions also provide a wrapper around the HTTPS protocol. make_headersheaders This function converts an associative array into a string formatted for sending directly to an HTTP server. The arrays keys should be the header identifier, and the values should be the value to be associated with each header identifier. Essentially, this function combines each keyvalue pair with a colon and joins all of the pairs with carriage returns and linefeeds. The return value from this function is the resulting string. make_formdata This function converts an associative array into a string formatted for sending form data to a CGI script. The arrays keys should be the field name, and the values should be the value to be associated with each field name. The values are encoded according to the rules governing special and reserved characters in URLs. Essentially, this function combines each keyvalue pair with an equal sign and joins all of the pairs with an ampersand. The return value from this function is the resulting string. get_httpssite, port, path, headers, content, mime_type, crt_path, key_pathhead_httpssite, port, path, headers, content, mime_type, crt_path, key_pathpost_httpssite, port, path, headers, content, mime_type, crt_path, 223 key_pathput_httpssite, port, path, headers, content, mime_type, crt_path, key_path These four functions are similar, so well describe them together. They take the same arguments and perform the HTTP request that is signified by their names. Not all of the arguments are appropriate for all of the functions, and in many cases empty values can be specified without any adverse effects. All of the functions establish a secure connection using SSL with the HTTPS protocol. You should not pass a URL to the functions, but instead pass the separate components that make up a URL as arguments, individually. These functions will build the URL for you, establish the connection, perform the requested operation with the data youve provided, and return the data from the server to your program. Its important to realize that these functions perform no real certificate verification, so the only protection theyre providing is against passive eavesdropping attacks. The first argument, site , should contain the hostname or IP address of the host you wish to contact. The second argument, port , should be the port to connect to. For the HTTPS protocol, the default port is 443. The third argument, path , should be the path to the page as well as any variables you wish to pass as part of the URL. Essentially, this is the remainder of the URL. The fourth argument, headers , should contain any additional headers that you wish to send with your request. You can use the function make_headers to build a string of header information from an associative array. By default, Net::SSLeay will include the standard Host and Accept headers, so you do not need to include them yourself. The fifth argument, content , is useful only for the put_https and post_https functions. Use it to specify the data to send to the server. In the case of the post_https , you can use the function make_form to build a string of data from an associative array to send to the server. The sixth argument, mime_type , is used to specify the MIME type of the data contained in the content argument. If you do not specify a MIME type, applicationx-www-form-urlencoded is used by default. The final two arguments, crt_path and key_path , are optionally used to specify the path and filename to the client certificate and RSA private key to be used in establishing the connection. Remember that if you request a private key to be used in the transaction, the passphrase for the key will be requested from the console by OpenSSL if it is encrypted. The certificate and key files must be in PEM format, which also means that they may both be contained in the same file. All four functions will return an array containing the results of the transaction. If an error occurs, the returned array will have only two elements. The first element will be undef , and the second element will be a string representation of the error that occurred. If the transaction is successful, the array will have three elements. The elements will be in this order: the data that makes up the page, the response code from the server, and the headers returned from the server. The headers will be returned in the form of an associative array. sslcathost, port, content, crt_path, key_path This function establishes an SSL-secured connection to another host, sends it some data, waits for a response, and returns the remote hosts response to your program. The first two arguments, host and port , specify the hostname or IP address and the port number to connect to. The third argument, content , specifies the data that you wish to send to the remote host. 224 The fourth and fifth arguments, crt_path and key_path , optionally specify the path and filename to the client certificate and RSA private key to be used in establishing the SSL connection. Remember that if you specify a key to be used, the passphrase for the key will be prompted for on the console if the key is encrypted. The return value from this function will be the data returned by the remote host or undef if an error occurred. If you call the function to request an array as a return, the first element of the array will be the data that was received from the remote host, and the second element will be a string containing error information if an error occurred. randomizeseed_file, seed_string, egd_path This is a convenience function used to seed OpenSSLs PRNG. The first argument is the name of a file to be used as a seed file. The second argument is a string to be used as a seed. The third argument is the name of a Unix domain socket that is bound to a server that speaks the EGD protocol for gathering entropy. If the argument is undefined, the environment variable EGD_PATH will be consulted for the name of the socket to use. Additionally, if youve specified a random device with the random_device variable and it exists, the information will be passed on to OpenSSL via RAND_load_file . This function has no return value. set_cert_and_keyctx, cert_file, key_file This is a convenience function for specifying the certificate and key to use for an SSL context. All three arguments are required. Note that if the RSA key specified by key_file is encrypted, OpenSSL will prompt you on the console for the passphrase. This function returns 0 if an error has occurred; otherwise, the return is nonzero. ssl_read_allssl, howmuch This function reads howmuch bytes from SSL connection specified by ssl . The function will not return until the specified number of bytes has been read or EOF is encountered, whichever happens first. The return from this function will be the data that was received. If you call the function requesting an array return, the first element of the array will be the data received, and the second element will be the string representation of any errors that occurred. ssl_read_CRLFssl, max This function reads data from the SSL connection specified by ssl until a carriage return and linefeed are received or the number of bytes equals max if it is specified. The carriage return and linefeed characters will be included in the received data if theyre read before the maximum byte limit is reached. The return from this function will be the data that was received. ssl_read_untilssl, delimiter, max This function reads data from the SSL connection specified by ssl until the specified delimiter is received or the number of bytes equals max if it is specified. If no delimiter is specified, or a linefeed character will be used, depending on whether is defined or not. If the delimiter is encountered, it will be included in the data that is returned. The return from this function will be the data that was received. ssl_write_allssl, data 225 This function writes the data specified by data to the SSL connection specified by ssl . The function will not return until all of the data has been written. The data to be written may be passed as a reference. The return from this function will be the number of bytes that were written. If you call the function requesting an array return, the first element of the array will be the number of bytes written, and the second element will be the string representation of any errors that occurred. ssl_write_CRLFssl, data This function is a simple wrapper around ssl_write_all that makes an additional call to ssl_write_all to write both a carriage return and a linefeed after your data. The return from this function is the total number of bytes written. Remember that this byte count will include the carriage return and linefeed characters.

9.1.4 Net::SSLeay Low-Level Bindings