For POPFile 1.1.2 (released 21 August 2011) the SSL support for the Windows version was upgraded to use a completely new SSL support package which is more up-to-date and smaller than the support packages used by earlier releases of POPFile. The Windows installer now includes all of the neceassry files and installs them by default. This means the installer will no longer download (and possibly patch) the files during the installation. As a result the installer code has been simplified and made easier to maintain.

POPFile has been able to make SSL connections to mail servers since the 0.22.0 release in September 2004. If the “SSL support” option is selected the installer will download the necessary files from the University of Winnipeg repository (this is the main source of these SSL Support files; they are not available from the main ActivePerl 5.8 repository because ActiveState do not currently have the necessary government permit).

POPFile 1.1.0 and later releases also download one SSL file from the ppm.tcool.org repository because the file found in the University of Winnipeg repository does not support the timeout feature POPFile uses to cope with slow servers.

Downloading the SSL support files during the installation helps reduce the size of the installer and ensures that the installation uses the most up-to-date SSL support files. This scheme has worked very well because these SSL files are not updated frequently (see table below).

However there have been occasions where the files on the University of Winnipeg server have become incompatible with a particular release of POPFile. Usually this problem can be resolved by simply applying a patch to downgrade one of these files (SSL.pm from the IO::Socket::SSL module) to an older version which is compatible with the minimal Perl used by that release of POPFile.

The files on the University of Winnipeg server do not get updated very often (see table below) so the installer used to include a hard-coded patch but starting with the 0.22.5 release a more flexible approach was adopted. Instead of relying upon a patch embedded in the installer, the installer now downloads any necessary patches from the POPFile web-server.

This makes it much easier to respond to those rare occasions when the files on the University of Winnipeg server get updated and become incompatible with the current release of POPFile because it avoids the need to rebuild the installer and the POPFile SSL Setup wizard. However the current patches, if any, are still incorporated into each build of the installer so they can be used if the POPFile web site is not available when the installer is run.

Normally SSL support is downloaded at the same time that POPFile is installed, but SSL support can be added or updated after installation by using the “Add/Remove Programs” entry for POPFile 1.0.0 or later (or by re-running the installer or by running the POPFile SSL Setup wizard).

For POPFile 0.22.0, 022.1, 0.22.2, 0.22.3, 0.22.4 and 0.22.5 a special utility, the POPFile SSL Setup wizard, has been created to allow SSL Support to be added to these older versions of POPFile. This wizard is able to add or update SSL Support for POPFile 0.22.0 or any later release.

Although the installers for 0.22.3, and 0.22.4 offer to add SSL Support these old installers are unable to apply the necessary patches to make the current files from the University of Winnipeg repository compatible with these old POPFile releases. This means POPFile will crash when it tries to use the SSL files downloaded by these old installers.

The 0.22.5 installer is currently (11 March 2008) able to add SSL Support but it does not use the new POPFile web-server address so it will be unable to download the SSL patches if any become necessary for this old release. Version 0.3.1 (or later) of the POPFile SSL Setup wizard uses the new POPFile web-server so it can be used to update old 0.22.5 installations if any SSL patches need to be applied.

The minimal Perl used in POPFile 0.22.0, 0.22.1 and 0.22.2 is no longer compatible with the files from the University of Winnipeg so the POPFile SSL Setup wizard includes a set of compatible SSL files which will be installed instead.

The current SSL Support status for POPFile 0.22.0 and all later releases is summarised in this table.

When SSL support is added to POPFile a log file is created listing the files which get added to POPFile and any SSL patches which were applied to make the files work properly with that particular installation.

Three log files are used at present:

• install.log is used when SSL Support is added by the POPFile installer

• modify.log is used when SSL Support is added by using POPFile's “Add/Remove Programs” entry (for POPFile 1.0.0 or later releases)

• addssl.log is used when SSL Support is added by the POPFile SSL Setup wizard

These log files are stored in the main POPFile program folder. The location of this folder is normally held in the POPFILE_ROOT environment variable and in the registry. Since it it not easy for users to check these values, the location of this folder can be displayed using the following shortcut created by the installer: Start – Programs – POPFile – Support – PFI Diagnostic utility (simple)

The /var/www/installer/ssl-patch directory contains, at the time of writing (3 October 2009), the following files which are used when adding or upgrading SSL support:

0.22.x.pcf
0.22.5.pcf
1.0.0.pcf
1.0.1.pcf
1.1.0.pcf
1.1.1.pcf
SSL_pm.pat
MD5SUMS

The *.pcf files are Patch Control Files which specify the SSL patches, if any, required for POPFile. The 0.22.x.pcf file is a special file used for 0.22.4 and earlier releases. The 0.22.5 and later releases each have their own Patch Control File (PCF).

The SSL_pm.pat file is a binary file containing the VPATCH patch data used by the installer to downgrade the SSL.pm file in newer versions of the IO::Socket::SSL module to the old v0.97 version which is compatible with POPFile 0.22.4 and 0.22.3.

The MD5SUMS file contains the MD5 sums for the other files in the directory. It is used by the installer (or the POPFile SSL Setup wizard) to check the integrity of the files it downloads. This file can be generated and checked quite easily at the web server's command-line:

$ rm MD5SUMS
$ md5sum * > MD5SUMS
$ md5sum -c MD5SUMS

The PCF files and the MD5SUMS file are text files and can use either LF or CRLF for the end-of-line sequence. (The installer and POPFile SSL Setup wizard can cope with either format.)

From the 0.22.5 release onwards each release has a Patch Control File (PCF) which specifies any SSL patches which are to be applied when SSL Support is installed or upgraded. These PCF files have names which are formed by appending “.pcf” to the release number, e.g. 0.22.5.pcf, 1.0.0.pcf, etc.

These PCF files are simple INI files and always start like this:

; POPFILE PATCH CONTROL FILE
 
[PCF]
Format=1

Format specifies the format of the PCF file. At present only one format is used so this value is always set to “1”

There is always a [Settings] section in the PCF file:

[Settings]
POPFileVersion=
PatchIssue=
NumberOfPatches=
Comment=

POPFileVersion specifies the version of POPFile to which these patches apply. Each release has a separate PCF file.

PatchIssue specifies the issue number for this particular PCF file.

NumberOfPatches specifies the number of SSL patches which are to be applied to this release of POPFile. If no patches are required then this value is set to 0.

Comment holds a string to identify the particular PCF file. Currently only a single string (less than 1,023 characters) is supported.

The information in the [Settings] section is used to generate entries in the appropriate log file.

If any patches are required then NumberOfPatches will specify the number and for each patch there will be a separate section defining the patch and how to apply it. Each patch section defines the patch for a specific file; if more than one file needs to be patched then the PCF file must contain a patch section for each file to be patched.

Details of the first patch will be in section [Patch-1], the next patch will be specified in section [Patch-2] and so on. Here is the format used for a patch section:

[Patch-n]
Category=
PatchData=
TargetFolder=
TargetFile=
LogMsg-1=
LogMsg-2=
LogMsg-3=
LogMsg-4=

For each patch section the following data is required:

[Patch-n] specifies the number of this patch section. n should be replaced by the patch section number, starting from 1.

Category indicates the importance of the patch. In the current implementation two categories are supported: ESSENTIAL and OPTIONAL. At present the ESSENTIAL category is used to trigger a Message Box in the “POPFile SSL Setup” wizard.

PatchData specifies the name of the binary patch file to be applied (stored in same directory as the PCF file). This file is generated by the VPATCH utility shipped with the NSIS compiler (see “How the SSL.pm patch was created” below)

TargetFolder specifies the installation directory containing the file to be patched. This directory path is relative to the main POPFile program folder (i.e. this path is appended to the contents of the POPFILE_ROOT environment variable). TargetFolder paths containing the sequence “..” will be rejected to ensure the installer (or the POPFile SSL Setup wizard) only patches files in or under the POPFILE_ROOT folder.

TargetFile specifies the name of the file to be patched. The existing file will be backed up and up to three such backups will be retained (i.e. these backups will be <filename>.bk1 (the newest backup), <filename>.bk2 and <filename>.bk3 (the oldest)

LogMsg-1 the English text used in the log file (and any message box) to identify the purpose of this patch

LogMsg-2 the English text used in the log file (and any message box) to report the result of the attempt to patch the target file

LogMsg-3 the English text used in the log file (and any message box) to report a successful patch attempt

LogMsg-4 the English text used in the log file (and any message box) to report a failure to patch the target file

The information in the patch section is used to generate entries in the appropriate log file:

• install.log for the installer (setup.exe)
• modify.log for POPFile's “Add/Remove Programs” entry (for 1.0.0 and later releases of POPFile)
• addssl.log for the POPFile SSL Setup wizard (addssl.exe)

; POPFILE PATCH CONTROL FILE
 
[PCF]
Format=1
 
[Settings]
POPFileVersion=1.0.0
PatchIssue=0
NumberOfPatches=0
Comment=The current SSL Support files are compatible (21 Oct 2007 @ 10:00 GMT)

; POPFILE PATCH CONTROL FILE
 
[PCF]
Format=1
 
[Settings]
POPFileVersion=0.22.5
PatchIssue=1
NumberOfPatches=0
Comment=The current SSL Support files are compatible (13 Jun 2007 @ 19:08 GMT)

NOTE: Used by the POPFile SSL Setup wizard to add SSL Support to 0.22.3 or 0.22.4

; POPFILE PATCH CONTROL FILE
 
[PCF]
Format=1
 
[Settings]
POPFileVersion=0.22.x
PatchIssue=2
NumberOfPatches=1
Comment=Updated to cope with current SSL files (14 February 2008 @ 15:20 GMT)
 
[Patch-1]
Category=ESSENTIAL
PatchData=SSL_pm.pat
TargetFolder=lib\IO\Socket
TargetFile=SSL.pm
LogMsg-1=Downgrading SSL.pm to v0.97
LogMsg-2=SSL.pm patch status:
LogMsg-3=SSL.pm file has been downgraded to v0.97
LogMsg-4=ERROR: SSL.pm file has *not* been downgraded to v0.97

NOTE: This is a fictitious example (POPFile 0.22.6 was never released)

; POPFILE PATCH CONTROL FILE
 
[PCF]
Format=1
 
[Settings]
POPFileVersion=0.22.6
PatchIssue=7
NumberOfPatches=2
Comment=Dummy example with two patch sections, created 28 January 2007 @ 00:37 GMT
 
[Patch-1]
Category=ESSENTIAL
PatchData=SSL_pm.pat
TargetFolder=lib\IO\Socket
TargetFile=SSL.pm
LogMsg-1=Downgrading SSL.pm to v0.97
LogMsg-2=SSL.pm patch status:
LogMsg-3=SSL.pm file has been downgraded to v0.97
LogMsg-4=ERROR: SSL.pm file has *not* been downgraded to v0.97
 
[Patch-2]
Category=OPTIONAL
PatchData=dummy.pat
TargetFolder=UI
TargetFile=HTML.pm
LogMsg-1=Applying a dummy patch to UI\HTML.pm
LogMsg-2=UI\HTML.pm patch status:
LogMsg-3=UI\HTML.pm file has been upgraded to v1.23.456
LogMsg-4=ERROR: UI\HTML.pm file has *not* been upgraded to v1.23.456

The patch used to downgrade SSL.pm v0.99, SSL.pm v0.999, SSL.pm v1.01, SSL.pm v1.08 or SSL.pm v1.13 to SSL.pm v0.97 was created using the VPATCH package which is supplied with NSIS. The following MS-DOS commands were used to create the patch file:

del SSL_pm.pat
GenPat.exe SSL_0.99.pm  SSL_0.97.pm SSL_pm.pat
GenPat.exe SSL_0.999.pm SSL_0.97.pm SSL_pm.pat
GenPat.exe SSL_1.01.pm  SSL_0.97.pm SSL_pm.pat
GenPat.exe SSL_1.08.pm  SSL_0.97.pm SSL_pm.pat
GenPat.exe SSL_1.13.pm  SSL_0.97.pm SSL_pm.pat

where

• SSL_0.97.pm was the SSL.pm file from v0.97 of the IO::Socket:SSL module
• SSL_0.99.pm was the SSL.pm file from v0.99 of the IO::Socket:SSL module
• SSL_0.999.pm was the SSL.pm file from v0.999 of the IO::Socket:SSL module
• SSL_1.01.pm was the SSL.pm file from v1.01 of the IO::Socket:SSL module
• SSL_1.08.pm was the SSL.pm file from v1.08 of the IO::Socket:SSL module
• SSL_1.13.pm was the SSL.pm file from v1.13 of the IO::Socket:SSL module

These commands generate a SSL_pm.pat file which can be used to downgrade v0.99, v0.999, v1.01, v1.08 or v1.13 of SSL.pm to v0.97 which is compatible with POPFile 0.22.3 and 0.22.4.

• IMPORTANT NOTE
  • The various SSL.pm files used to generate this patch must use the correct end-of-line sequences. When the untgz plugin extracts SSL.pm the output file uses LF therefore the files used to generate this patch must also use LF instead of the normal CRLF sequence used on Windows systems. If files with CRLF are used to make the patch then the SSL.pm file will not be patched (a “no suitable patches found” error will be reported by the vpatch plugin).

• “SSL Support Files Status” information correct as of 18 September 2008

• On 22 June 2005 the University of Winnipeg's SSL files were updated to work with ActivePerl 5.8.7 Build 813 (the then current version of ActivePerl). These changes made the SSL files incompatible with the Windows versions of POPFile 0.22.0, 0.22.1 and 0.22.2 since these releases use older versions of perl58.dll which lack some of the features required by the new SSL Support files. This binary incompatibility prompted the release of POPFile 0.22.3.

• “SSL Support Status for POPFile releases” information correct as of 3 October 2009

• Starting with the 1.1.0 release POPFile now uses a timeout when connecting to the SSL server. This requires the use of IO::Socket:SSL v1.10 or later. Since the University of Winnipeg repository currently has only v1.08 available, another repository (http://ppm.tcool.org/) is used for the IO::Socket::SSL package (v1.13 as of 30 November 2008 and 3 October 2009).