view release on metacpan or  search on metacpan

lib/EMDIS/ECS.pm  view on Meta::CPAN

    my $encr_out_keyid = shift;
    my $encr_out_passphrase = shift;

    # initialize
    return "EMDIS::ECS::openpgp_encrypt(): ECS has not been configured."
        unless ecs_is_configured();
    my $cfg = $ECS_CFG;

    # compose command
    my $keyid = (defined $encr_out_keyid and 0 < length $encr_out_keyid) ?
        $encr_out_keyid : $cfg->GPG_KEYID;
    my $cmd = $cfg->OPENPGP_CMD_ENCRYPT;
    $cmd =~ s/__INPUT__/$input_filename/g;
    $cmd =~ s/__OUTPUT__/$output_filename/g;
    $cmd =~ s/__RECIPIENT__/$recipient/g;
    $cmd =~ s/__SELF__/$keyid/g;
    print "<DEBUG> openpgp_encrypt() command: $cmd\n"
        if $cfg->ECS_DEBUG > 0;

    # set GNUPGHOME environment variable
    $ENV{GNUPGHOME} = $cfg->GPG_HOMEDIR;

    # attempt to execute command
    my $result = timelimit_cmd($cfg->T_MSG_PROC, $cmd,
        (defined $encr_out_passphrase and 0 < length $encr_out_passphrase) ?
            $encr_out_passphrase :
            (defined $cfg->GPG_PASSPHRASE and 0 < length $cfg->GPG_PASSPHRASE ?
                $cfg->GPG_PASSPHRASE : undef));
    $result = "EMDIS::ECS::openpgp_encrypt(): $result" if $result;
    return $result;
}

# ----------------------------------------------------------------------
# Use PGP2 (PGP) to decrypt a file.
# Returns empty string if successful or error message if error encountered.
sub pgp2_decrypt
{
    my $input_filename = shift;
    my $output_filename = shift;
    my $required_signature = shift;
    my $encr_out_passphrase = shift;

    # initialize
    return "EMDIS::ECS::pgp2_decrypt(): ECS has not been configured."
        unless ecs_is_configured();
    my $cfg = $ECS_CFG;

    # compose command
    my $cmd = $cfg->PGP2_CMD_DECRYPT;
    $cmd =~ s/__INPUT__/$input_filename/g;
    $cmd =~ s/__OUTPUT__/$output_filename/g;
    print "<DEBUG> pgp2_decrypt() command: $cmd\n"
        if $cfg->ECS_DEBUG > 0;

    # set PGPPATH and PGPPASS environment variables
    $ENV{PGPPATH} = $cfg->PGP_HOMEDIR;
    my $passphrase = (defined $encr_out_passphrase and 0 < length $encr_out_passphrase) ?
        $encr_out_passphrase : $cfg->PGP_PASSPHRASE;
    $ENV{PGPPASS} = $passphrase;

    # attempt to execute command - pipe passphrase to cmd, to support usage of gpg1 in place of pgp2
    my $result = timelimit_cmd($cfg->T_MSG_PROC, $cmd, $passphrase);
    $result = '' if($result =~ /^Status 0x0100/);  # ignore exit value = 1
    $result = "EMDIS::ECS::pgp2_decrypt(): $result" if $result;

    # check signature, if indicated
    if(defined($required_signature) and not $result) {
        if($cmd_output !~ /Good signature from[^\n]+$required_signature/is) {
            $result = "EMDIS::ECS::pgp2_decrypt(): required signature not " .
                "present: $required_signature";
        }
    }

    return $result;
}

# ----------------------------------------------------------------------
# Use PGP to encrypt a file.
# Returns empty string if successful or error message if error encountered.
sub pgp2_encrypt
{
    my $input_filename = shift;
    my $output_filename = shift;
    my $recipient = shift;
    my $encr_out_keyid = shift;
    my $encr_out_passphrase = shift;

    # initialize
    return "EMDIS::ECS::pgp2_encrypt(): ECS has not been configured."
        unless ecs_is_configured();
    my $cfg = $ECS_CFG;

    # compose command
    my $keyid = (defined $encr_out_keyid and 0 < length $encr_out_keyid) ?
        $encr_out_keyid : $cfg->PGP_KEYID;
    my $cmd = $cfg->PGP2_CMD_ENCRYPT;
    $cmd =~ s/__INPUT__/$input_filename/g;
    $cmd =~ s/__OUTPUT__/$output_filename/g;
    $cmd =~ s/__RECIPIENT__/$recipient/g;
    $cmd =~ s/__SELF__/$keyid/g;
    print "<DEBUG> pgp2_encrypt() command: $cmd\n"
        if $cfg->ECS_DEBUG > 0;

    # set PGPPATH and PGPPASS environment variables
    $ENV{PGPPATH} = $cfg->PGP_HOMEDIR;
    my $passphrase = (defined $encr_out_passphrase and 0 < length $encr_out_passphrase) ?
        $encr_out_passphrase : $cfg->PGP_PASSPHRASE;
    $ENV{PGPPASS} = $passphrase;
    
    # attempt to execute command - pipe passphrase to cmd, to support usage of gpg1 in place of pgp2
    my $result = timelimit_cmd($cfg->T_MSG_PROC, $cmd, $passphrase);
    $result = "EMDIS::ECS::pgp2_encrypt(): $result" if $result;
    return $result;
}

# ----------------------------------------------------------------------
# Check whether another copy of the program is already running.
# If so, this one dies.
sub check_pid
{
    die "EMDIS::ECS::check_pid(): ECS has not been configured."
        unless ecs_is_configured();

    if(open PIDFILE, $pidfile) {
        my $pid = <PIDFILE>;
        $pid =~ s/\s+//g;
        die "Error: $0 is already running (pid $pid).\n"
            if kill(0, $pid);
        close PIDFILE;
    }

    save_pid();
}

# ----------------------------------------------------------------------
# Update PID file.
sub save_pid
{
    die "EMDIS::ECS::save_pid(): ECS has not been configured."
        unless ecs_is_configured();

    open PIDFILE, ">$pidfile";
    print PIDFILE "$$\n";
    close PIDFILE;
    chmod $FILEMODE, $pidfile;
    $pid_saved = 1;
}

# ----------------------------------------------------------------------
# Select the Win32 or Unix version of timelimit_cmd
sub timelimit_cmd
{
    $^O =~ /MSWin32/ ? timelimit_cmd_win32(@_) : timelimit_cmd_unix(@_);
}



# Returns empty string if successful or error message if error encountered.
sub timelimit_cmd_win32
{
    my $timelimit = shift;
    my $cmd = shift;
    my $input_data = shift;
    my $cfg = $ECS_CFG;
    my @msgs = ();
    my $result = "";
    my ($ProcessObj, $rc, $appname, $cmdline);

    # reset module-level variable containing command output
    $cmd_output = '';

lib/EMDIS/ECS.pm  view on Meta::CPAN

1990s.

In addition to the EMDIS::ECS Perl module, the EMDIS-ECS tar archive
includes a docker subdirectory containing several Dockerfile setups
to aid in testing the software and deploying it under Rocky Linux or
Ubuntu, and a web-status subdirectory containing resources for an ECS
Status web page.

This ECS.pm module contains miscellaneous ECS related subroutines.
However, most of the documentation found here pertains to the Perl ECS
implementation in general, not those specific subroutines.


=head2 Introduction

This Perl implementation of the EMDIS Communication System (ECS),
herein referred to as "Perl-ECS", is generally compatible with
the ECS specification published by the ZKRD, though it differs from
the specification in some of its implementation details.
A PDF document containing the original ECS specification is available
from the ZKRD web site (see http://www.zkrd.de/).


=head2 Getting Started

Before Perl-ECS can be used, a number of pre-requisites must
be satisfied.

=over 4

=item Install Perl-ECS

Install Perl, preferably version 5.6.1 or higher.  Then install the
EMDIS::ECS package.

=item Email Account

Acquire an email account to be used by the ECS system.  Perl-ECS
uses SMTP to send outbound mail, so a SMTP server will need to be
available for this purpose.

To read incoming email, Perl-ECS can use IMAP protocol, POP3 protocol,
or a DIRECTORY method.  If IMAP or POP3 protocol is used, that service
will also need to be available.

Some cloud-based email providers such as GMail and Office 365 require
the use of an OAuth 2.0 access token for authentication with their
SMTP, IMAP, and POP3 services.  Version 0.45 of Perl-ECS added OAuth
configuration settings to enable authentication with those services.

=item Encryption Software

Install and configure PGP and/or GnuPG encryption software.  Refer to
http://www.pgp.com/, http://www.pgpi.org/, http://www.gnupg.org/,
and http://www.philzimmermann.com/ for more information on the topic
of PGP and related software.

=item GnuPG Version 2.2 - Additional Notes

The default OpenPGP configuration used by Perl-ECS is intended for use
with GnuPG (gpg) versions 1.4 and 2.0.  However, gpg version 2.2 is a
standard component of newer Linux systems such as Ubuntu 18.

For systems using gpg version 2.2, configuration adjustments are needed
in order to enable Perl-ECS to transmit the passphrase to gpg via stdin
(pinentry-mode loopback).

1. Create or edit $GNUPGHOME/gpg-agent.conf, adding the line:

 allow-loopback-pinentry

2. Execute the command:

 gpg-connect-agent /bye

3. In the ecs.cfg configuration file, revise the OPENPGP_CMD_ENCRYPT and
OPENPGP_CMD_DECRYPT settings to add the following.  (If needed, first
uncomment those settings.):

 --pinentry-mode loopback

4. If upgrading from an earlier gpg version, use ecstool --tweak to modify
all (addr_r) key IDs in the node table, because the IDs change when the
keyring is converted to gpg 2.2.

=item AMQP Messaging

As an experimental new feature, version 0.41 added support for use of
AMQP messaging as an alternative to email.

To use AMQP messaging, the ENABLE_AMQP setting must be set to YES or TRUE.
AMQP communications utilize a mboxes/amqp_staging directory, which will
need to be created manually, e.g.:

 mkdir mboxes/amqp_staging

Additionally, the node table now accepts new AMQP-related settings.
These can be added via the "ecstool --tweak" command, e.g.:

 ecstool --tweak BB amqp_addr_meta emdis.bb.meta
 ecstool --tweak BB amqp_addr_msg emdis.bb.msg

AMQP settings configured at the individual node level override equivalent
global settings when communicating with that node.   The presence of
amqp_addr_meta and amqp_addr_msg in the node configuration, respectively,
enable use of AMQP for transmission of META and regular EMDIS messages to
that node (assuming ENABLE_AMQP is also set in ecs.cfg).

The node table also recognizes an amqp_only yes/no option.  If enabled,
the amqp_only option disables use of email when transmitting
meta-messages, documents, or regular messages messages to that node.

=item Document Exchange

As an experimental new feature, version 0.41 added support for document
exchange.

The ecs_scan_mail program, when processing files in the
mboxes/to_dir/to_XX subdirectories, now looks for filenames with the
suffix .doc or .doc.xml and sends those files as documents.

Similarly, the "ecstool --send" command now sends files with a .doc or
.doc.xml suffix as documents, e.g. "ecstool --send EE test01.doc"

The ecs_scan_mail program copies documents received to the
mboxes/from_dir/from_XX subdirectories, to a filename with a .doc suffix.

Document exchange uses a Subject header of the form EMDIS:AA:123:DOC
to indicate the presence of a document and its sequence number.
DOC_MSG_ACK and DOC_RE_SEND are meta messages used for document exchange.

=back

=head2 Configuration

Once the above prerequisites are in place, it's time to configure your
ECS system.  Create a directory to hold the ECS data files and then run
the ecs_setup program to help create a basic configuration file.  The
ECS configuration file can also be created and edited using a regular
text editor.


=head2 NODE_TBL