Log2t::Time(3)

NAME
Log2t::Time - A library that provides method to work with different timestamps.

DESCRIPTION
This is a small library to assist with time manipulation. It contains multiple methods that can be used in log2timeline modules when dealing with converting timestamps that are stored in various formats into Epoch, and also to convert Epoch timestamps to textual representations.

This library should always be used when converting timestamps either to or from an epoch value since the sub routines defined here can be used by all modules (code reuse, and if a quicker method is developed it will make maintenance considerably easier).

All methods should be documented here in the code so that it will be easy for anyone to use them in the code.

METHODS

  "Win2Unix"
A subroutine copied from ptfinder.pl developed by Andreas Schuster and Csaba Barta. This sub routine converts windows filetime into a unix format

n.b FILETIME is represented in UTC

Windows epoch is 1601-01-01 00:00:00, resolution 100ns

UNIX epoch is 1970-01-01 00:00:00, resolution 1s

Copyright (c) 2009 by Andreas Schuster and Csaba Barta.

Args:

Lo: An integer (32 bits) representing the lower 32 bits of the timestamp.

Hi: An integer (32 bits) representing the higher 32 bits of the timestamp.

Returns:

An integer representing the number of seconds since Epoch time.

  "getNanoWinFileTime"
A small subroutine that returns the nanoseconds of a Windows FILETIME

Args:

l: An integer, 32 bits, representing the lower 32 bits of the timestamp.

h: An integer, 32 bits, representing the higher 32 bits of the timestamp.

Returns:

An integer that represents the nanoseconds of a FILETIME timestamp.

  "Dos2Unix"
Taken from the dos2unixtime function from the tsk3/fs/fatfs_meta.c file from The Sleuthkit. The logic and code taken there, and adapted to be a Perl code (the other is a C code)

** Brian Carrier [carrier <at> sleuthkit [dot] org]

** Copyright (c) 2006-2008 Brian Carrier, Basis Technology. All Rights reserved

** Copyright (c) 2003-2005 Brian Carrier. All rights reserved

**

** TASK

** Copyright (c) 2002 Brian Carrier, @stake Inc. All rights reserved

**

**

** This software is distributed under the Common Public License 1.0

**

** Unicode added with support from I.D.E.A.L. Technology Corp (Aug '05)

Convert DOS DATE and TIME format to Unix Epoch.

DOS DATE is a two byte packet data where

0-4 DAY (1-31)

5-8 MONTH (1-12)

9-15 YEAR (from 1980)

DOS TIME is a two byte packet

0-4 sec (divided by two)

5-10 min

11-15 hour

Links pointing towards further information:

http://msdn.microsoft.com/en-us/library/aa371853%28VS.85%29.aspx

http://www.vsft.com/hal/dostime.htm

Args:

date: Packed 16 bit (2 byte) value that represents the date.

time: Packed 16 bit (2 byte) value that represents the time of day.

  "iso2epoch"
This routine transforms a date formated according to ISO 8601 to an epoch time (see definition on Wikipedia):

http://en.wikipedia.org/wiki/ISO_8601

Args:

iso: A string containing the timestamp, in ISO_8601 notation.

tz: The timezone of the file.

Returns:

An integer representing the number of seconds since Epoch.

  "epoch2cftl"
A sub routine that converts an Epoch timestamp into a timestamp that CFTL (Computer Forensics Time Lab accepts in it's XML schema).

Args:

epoch: An integer in the epoch format.

tz: The timezone of the timestamp.

Returns:

A string representing the timestamp in a format that CFTL accepts.

  "epoch2text"
A sub routine that converts an Epoch timestamp into a textual human readable format.

The sub routine returns the text in three different formats depending on the value of the variable use_local.

The formats are:

+ [0] One value: Day Month DD YYYY HH:MM:SS (GMT)

+ [1] One value: Day Month DD YYYY HH:MM:SS (ZONE)

+ [3] Two values: MM/DD/YYYY and HH:MM:SS

Args:

epoch: An integer in the Epoch format

use_local: An integer that determines the format of the output, values can be found above in the description.

tz: The timezone of the timestamp.

Returns:

A string representing the timestamp, depending on the value of use_local.

  "month2int"
A small sub routine that takes as an input a string that is an abbreviated textual representation of a month and returns an integer, that is the month value of that particular month, eg. Jan becomes 1, Nov becomes 11, etc.

Args:

Month: A string, abbreviated text of a month (eg Jan, Feb, Mar, ...)

Returns:

An integer, from 1-12

  "exceldate2epoch"
A method that takes a timestamp that is defined in the native Excel format and transforms that into an Epoch timestamp.

The Excel format is:

DDDD.TTTT

Where DDDD is the number of days elapsed since 01/01/1901 and TTTT is the number of seconds since the start of the day.

Further reading:

http://office.microsoft.com/en-us/access-help/on-time-and-how-much-has-elapsed-HA001110218.aspx

http://support.microsoft.com/kb/214019

Since Epoch is measured in seconds since 01/01/1970 there is only 69 year difference between the two representations, so we can just simply calculate the difference and return that.

Args:

d: A string that represents the timestamp in the Excel format.

tz: The timezone of the file in question.

Returns:

An integer, representing the timestamp in Epoch format.

  "is_leap_year"
A small method used to determine if a given year is a leap year or not.

Method derived from this document:

http://support.microsoft.com/kb/214019

Essentially the method is split up in the following steps:

1: Is the year evenly divisible by 4? step 2: step 5

2: Is the year evenly divisible by 100? step 3: step 4

3: Is the year evenly divisible by 400? step 4: step 5

4: Leap year, return 1

5: Not a leap year, return 0

Args:

year: a four digit integer (year)

Returns:

1 if this is a leap year, 0 otherwise.