Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 11 - C API Reference Guide, Part II
Time and Date Functions

Several API calls give you access to Apache's routines for formatting and parsing HTTP-compliant date strings. Also see the descriptions for ap_update_mtime() and ap_set_last_modified() in Chapter 10, C API Reference Guide, Part I, under "Sending Files to the Client."

The declarations for these functions are scattered among several header files, including httpd.h, util_date.h, and http_request.h. In the following list we indicate where the function can be found:

char *ap_ht_time (pool *p, time_t t, const char *fmt, int gmt)

(Declared in the header file httpd.h.) Given a resource pool, a time_t timestamp, a character format, and a flag indicating whether or not to use GMT (Greenwich Mean Time, also known as Universal Standard Time), this function returns a character string containing the date. The character format uses the same code as the standard C library strftime() function, with the addition of two common extensions. The code %Z is substituted with the string GMT, and the code %z is substituted with +0000. See the manual page for strftime() for other codes you can use.

This example returns a string in the format Tue, 15Sep 1998 14:36:31 GMT, which happens to be the HTTP date format recommended by RFCs 822 and 1123.

char *str = ap_ht_time(p, time(NULL), "%a %d %b %Y %T %Z", 0);

time_t ap_parseHTTPdate (const char *date)

(Declared in the header file util_date.c.) Given a char* containing a date in HTTP format, this routine parses the date and returns a time_t Unix timestamp. This routine is flexible enough to correctly handle minor variations in the date format, such as omitting the time zone and day of the week. Any text that follows the time string is ignored.

Here's an example of converting the incoming If-modified-since header into a timestamp. We then compare this timestamp to the requested file's last modification date and return HTTP_NOT_MODIFIED if the file is not newer than the browser's cached copy.

char *if_modified_since = ap_table_get(r->headers_in, "If-modified-since");
if (if_modified_since) {
  time_t secs = ap_parseHTTPdate(if_modified_since);
  if (secs <= r->mtime) {
     return HTTP_NOT_MODIFIED;
  }
}

See also ap_meets_conditions().

struct tm *ap_get_gmtoff (int *tz)

(Declared in the header file httpd.h.) The ap_get_gmtoff() function calculates the current local time and returns it as a tm* function result. The offset from GMT, in minutes, is returned in the tz argument.

Here's an example borrowed from mod_rewrite, which it uses to write logging timestamps in the format [14/Sep/1998:11:01:23 -0500].

static char *current_logtime(request_rec *r)
{
  int timz;
  struct tm *t;
  char tstr[80];
  char sign;
  t = ap_get_gmtoff(&timz);
  sign = (timz < 0 ? '-' : '+');
  if (timz < 0) {
      timz = -timz;
  }
  strftime(tstr, 80, "[%d/%b/%Y:%H:%M:%S ", t);
  ap_snprintf(tstr + strlen(tstr), 80-strlen(tstr), "%c%.2d%.2d]",
              sign, timz/60, timz%60);
  return ap_pstrdup(r->pool, tstr);
}

char *ap_get_time (void)

(Declared in the header file httpd.h.) This function returns a date/time string in the format returned by the standard ctime() library call. Although this format is not compliant with the recommended HTTP header format, it is somewhat more concise and, for historical reasons, is used by the logging API for error log timestamps. Do not use it for the Expires header field or other HTTP headers that use dates. Use ap_gm_timestr_822() instead.

char *ctime_string = ap_get_time();

char *ap_gm_timestr_822 (pool *p, time_t sec)

(Declared in the header file httpd.h.) The unfortunately named function ap_gm_timestr_ 822() returns a date/time string that is formatted according to the RFC 822 SMTP specification. You can use this to create the outgoing Expires or Date fields. The sec argument contains the timestamp you wish to format.

In this example, we arrange for the outgoing document to expire 1 hour (3600 seconds) from the current time:

now = time(NULL);
ap_table_set(r->headers_out, "Expires", ap_gm_timestr_822(r->pool, now+3600))

time_t ap_tm2sec (const struct tm *t)

(Declared in the header file util_date.h.) The ap_tm2sec() function converts a GMT tm structure into a timestamp, the number of seconds since the start of the epoch. It is much faster than the standard equivalent mktime() function, and unlike mktime(), ap_ tm2sec() will always return a valid time_t() value, which may be 0 should an error occur.

time_t secs = ap_t2sec(&tm);

Message Digest Algorithm Functions

Apache includes a version of the MD5 Message Digest algorithm distributed as freeware by RSA Data Security Inc. These routines provide the functionality of the Perl MD5 module used in Chapters 5 through 7. In fact, both the Apache and Perl MD5 implementations are derived from the same source code.

Although MD5 was originally incorporated into Apache to support Digest Authentication, you can use it for whatever purpose you desire. As we've seen in earlier chapters, MD5 turns out to be handy anywhere you need to quickly check the authenticity of a file or message.

You will find all the data types and routines described in this section in header file ap_md5.h.

void ap_MD5Init (AP_MD5_CTX *context)

To compute an MD5 checksum, you will initialize the algorithm with ap_MD5Init(), add one or more rounds of data to it with ap_MD5Update(), and retrieve the checksum with ap_MD5Final(). A "context" record, the AP_MD5_CTX struct, keeps track of the state of the algorithm throughout this process.

ap_MD5Init() takes a new, uninitialized context variable and initializes it so that the algorithm is ready to use. You do not have to worry about what's in the context struct. You can create it on the stack or allocate it from a resource pool:

AP_MD5_CTX context;
ap_MD5Init(&context);

void ap_MD5Update (AP_MD5_CTX *context, const unsigned char *input, unsigned int inputLen)

Once the context is initialized, call ap_MD5Update() as many times as you need to add data to the digest function. In addition to the context record, you provide a character buffer in input and the length of the buffer in inputLen.

ap_MD5Update(&context, string, strlen(string));

void ap_MD5Final (unsigned char digest[16], AP_MD5_CTX *context)

When you are done adding data to the checksum, call ap_MD5Final(). This signals the algorithm to flush its buffers and calculate the final digest. The digest data (in binary form) will be returned in the 16 bytes of digest.

Here's one way to compute the checksum of the requested file. After retrieving the digest in binary form, we transform it into a human-readable hexadecimal string and return it:

AP_MD5_CTX context;
unsigned char buffer[1024];
unsigned char hash[16];
unsigned int len;
char *ptr, result[33];
int i;
FILE *fh = ap_pfopen(r->pool, r->filename, "r");
if (!fh) {
   return NULL;
}
ap_MD5Init(&context);
while ((len = fread(buffer, sizeof(unsigned char), 1024, fh)) > 0) {
   ap_MD5Update(&context, buffer, len);
}
ap_MD5Final(hash, &context);
for (i=0, ptr=result; i<16; i++, ptr+=2 ) {
   ap_snprintf(ptr, sizeof(result), "%02x", hash[i]);
}
*ptr = '\0';
return ap_pstrdup(r->pool, result);

The following functions are handy Apache extensions to the RSA routines. They are found in util_md5.h.

char *ap_md5 (pool *p, unsigned char *string)

ap_md5() is equivalent to the hexhash() method of the Perl MD5 module. It takes a resource pool p plus an arbitrary character string, string, and returns the hexadecimal representation of its MD5 digest. For example, should you wish to implement a message authentication check (MAC) as we did in the hangman example of Chapter 5, this will do the trick (assuming that WORD, LEFT, and so on are character strings):

char *fields = ap_pstrcat(p, SECRET, WORD, LEFT, GUESSED, GAMENO, WON, TOTAL,
   NULL);
char *mac = ap_md5(p, ap_pstrcat(p, SECRET, ap_md5(p,fields), NULL));

char *ap_md5_binary (pool *p, const unsigned char *buf, int len)

The ap_md5_binary() function does exactly the same work as ap_md5() but accepts a len parameter for data whose length cannot be determined using strlen(). In fact, ap_md5_ binary() does all the real work when ap_md5() is called.

char *ap_md5digest (pool *p, FILE *infile)

Given a resource pool pointer and a FILE* infile, this function computes the MD5 digest from the contents of the file and then base64-encodes it. The resulting character string is human-readable but is not the same as the hexadecimal representation more commonly used for MD5 digests. ap_md5digest() was designed for use with MIME MACs, which use base64 encoding.

char *digested_file = ap_md5digest(r->pool, infile);

char *ap_md5contextTo64 (pool *p, AP_MD5_CTX * context)

Given an MD5 context, this routine calls ap_MD5Final() and returns the digest as a base64-encoded string. Example:

char *encoded_context = ap_md5contextTo64(r->pool, &context);

User and Group ID Information Routines

These are a handful of routines that act as frontends to the standard Unix getpwnam() and getgrnam() functions. In addition to their role as easy-to-use wrappers, they provide portability with operating systems that don't provide these calls, such as Win32 systems.

These routines are declared in httpd.h:

uid_t ap_uname2id (const char *uname)

Used internally to process the User configuration directive, this function will use getpwnam() to look up the given user login name and return the user's UID. If the name is prefixed with the # symbol, as in #501, the string is converted into integer format and simply returned. Under Win32 systems, this function always returns 1.

uid_t id = ap_uname2id(uname);

gid_t ap_gname2id (const char *gname)

This function behaves identically to ap_uname2id(), except that it operates on group names and group IDs, using the Unix getgrnam() for its lookups. Under Win32 systems, this function will always return 1.

gid_t id = ap_gname2id(gname);