Chapter 1: About This Manual

AKM Perl modules

Alliance Key Manager implements a wire protocol for the AKM Encryption Service and the AKM Key Service. The AKM Encryption Service allows for remote encryption and decryption of data on the AKM server. The AKM Key Service allows for encryption key retrieval from the AKM server.

Any client application that is capable of creating a TLS connection to the AKM server and which has the proper X509 certificate and private key, can perform remote encryption and decryption on the AKM server or can retrieve an encryption key. The Perl language provides TLS communications, and AKM includes Perl modules for key retrieval and remote encryption that can be installed in your Perl projects.

Who is this for?

This guide is designed to help Perl developers install and use the AKM Perl remote encryption and key retrieval modules.

Other resources

The following documents provide additional information on the installation and use of Alliance Key Manager:

Notices

This product and documentation is covered by U.S. and International copyright law. This product may incorporate software licensed under one or more open source license agreements. Government users please note that this product is provided under restricted government use license controls. Please refer to the AKM End User License Agreement for more information.

Change log

The following table provides information on the changes to this documentation:

Version Date Description
2.1.13.001 3/21/2014 Manual style updates.
3.0.3.001 12/30/2014 Update for ready to use implementations of AKM. Addition of change log to document.
3.0.3.002 5/18/2015 Merge info from HOWTO Perl Key Retrieval and HOWTO Perl Remote Encryption. Rename to AKM Guide for Perl Developers.
4.0.0.001 5/24/2016 Update Certificates chapter for AKM 4.0 release.

Chapter 2: API Documentation

The AKM Encryption Service API Reference provides a full description of the remote encryption interface, while the AKM Key Service API Reference describes the key retrieval interface. Please refer to these manuals for more information about encryption and key retrieval fields and options.

The Perl module incorporates standard perldoc documentation on the use of the module. A more detailed description of the module options is available in the API documentation if needed.

Chapter 3: Certificates

In order to make a TLS connection to the Alliance Key Manager server there must be two PEM files in a local directory. There must be a PEM file with the client certificate, and a second PEM file with the client private key. The client certificate must be signed by a certificate authority known to the key manager. You should protect these files with native Linux security. The paths to these two files are passed as options to the AKM Perl module.

All required authentication certificates and private keys are generated automatically during server initialization. See your platform specific deployment guide for more information on locating authentication certificates.

Chapter 4: Installing the Perl Module on Linux

The commands needed to install the AKM Perl module in your environment will vary from one platform to the next. You should consult online documentation for information on the best way to install Perl modules on your platform. The CPANM facility is probably the easiest way to install the Perl modules and is used in the following example.

Pre-requisites

The module uses the OpenSSL Toolkit (http://www.openssl.org/) to work with certificates. You need to install OpenSSL development libraries. On Debian based distributions (Debian, Ubuntu etc.) the package is libssl-dev.

Installing the AKM Perl module on Ubuntu

The module is packaged as a standard Perl module distribution (in this case using Module::Install) and thus can be installed using cpanm. The module runs on Ubuntu versions 10.04 and later.

Install any updates to the Ubuntu OS:

sudo apt-get update

Install the Aptitude application:

sudo apt-get install aptitude

Install the OpenSSL toolkit:

sudo aptitude install libssl-dev

Install cpanm:

curl -L http://cpanmin.us | perl - --sudo --self-upgrade

Install curl:

sudo aptitude install curl

Install the Perl documentation module:

sudo apt-get install perl-doc

You are now ready to install the AKM encryption module AKM::Encrypt or the key retrieval module AKM::SymmetricKey (note that the versions you find on the AKM Supplemental may be different):

cpanm --sudo --prompt <path to AKM-Encrypt-vx.y.z.tar.gz>

Chapter 5: Installing the Perl Module on Windows

The commands needed to install the Alliance Key Manager Perl module in your environment will vary from one platform to the next. You should consult online documentation for information on the best way to install Perl modules on your platform. This example uses ActivePerl for Windows and was tested on version 5.16.2.

Pre-requisites

You can install the ActivePerl package from this website:

Installing the AKM Perl module on Windows

The module is packaged as ActivePerl package (in this case using Module::Install) and can be installed using ppm.

Install AKM::Encrypt if you are using the Perl remote encryption module:

ppm install <path to AKM-Encrypt-vx.y.z.ppd>

Install AKM::SymmetricKey if you are using the Perl key retrieval module:

ppm install <path to AKM-SymmetricKey-vx.y.z.ppd>

Module development on Windows

Use the following steps for development on the Microsoft Windows platform. This example uses the remote encryption module.

Change the version number in lib/AKM/Encrypt.pm.

Install dmake and gcc compiler and Module::Install module.

cpan (let cpan install dmake and gcc)

install Module::Install
exit

Remove old intermediate files:

dmake distclean

Create new Makefile:

perl Makefile.PL

Create distribution package:

dmake dist

Create ppm descriptor:

dmake ppd

Update archive name in ppd descriptor.

Replace this line:

<CODEBASE HREF="" />

With:

<CODEBASE HREF="AKM-Encrypt-vx.y.z.tar.gz" />

Rename ppd to reflect module version:

Rename AKM-Encrypt.ppd to AKM-Encrypt-vx.y.z.ppd

The result is AKM-Encrypt-vx.y.z.tar.gz and AKM-Encrypt-vx.y.z.ppd prepared to be installed as described in the “Installing the AKM Perl encryption module on Windows” section above.

Chapter 6: Perl Documentation

After installing module documentation can be displayed using perldoc. If using the Perl remote encryption module:

perldoc AKM::Encrypt

If using the Perl key retrieval module:

perldoc AKM::SymmetricKey

See Appendix A for an example of the documentation delivered with the AKM perl encryption module.

Chapter 7: Sample Code for Remote Encryption

There is an example of module usage in examples/encrypt_derypt.pl. Run the program without arguments to get help. The following is a listing of the sample program:

#!/usr/bin/perl

use strict;
use warnings;

use AKM::Encrypt qw(encrypt decrypt);

if (@ARGV < 7) {
    print "Not enough arguments given.\n";
    print "$0 <server> <port> <client_cert_file> <client_private_key_file> <key_name> <data> <iv>\n";
    exit 1;
}

my ($server, $port, $cert_file, $key_file, $name, $data, $iv) = @ARGV;

my %response_hash = encrypt(
    server     => $server,
    port       => $port,
    cert_file  => $cert_file,
    key_file   => $key_file,
    key_name   => $name,
    data       => $data,
    iv         => $iv,
);

die "Server call failed, error code: " . $response_hash{'return_code'} if $response_hash{'return_code'} > 0;

my $encrypted_data = $response_hash{'data'};

%response_hash = decrypt(
    server     => $server,
    port       => $port,
    cert_file  => $cert_file,


    key_file   => $key_file,
    key_name   => $name,
    data       => $encrypted_data,
    iv         => $iv,
);

die "Server call failed, error code: " . $response_hash{'return_code'} if $response_hash{'return_code'} > 0;

my $decrypted_data = $response_hash{'data'};

print "Data to encrypt: $data\n";
print "Encrypted data : $encrypted_data\n";
print "Decrypted data : $decrypted_data\n";

exit 0;

Chapter 8: Sample Code for Key Retrieval

There is an example of module usage in examples/retrieve_keys.pl. Run the program without arguments to get help. The following is a listing of the sample program:

#!/usr/bin/perl

use strict;
use warnings;

use AKM::SymmetricKey qw(retrieve_key);

if (@ARGV < 6) {
    print "Not enough arguments given.\n";
    print "$0 <server> <port> <client_cert_file> <client_private_key_file> <key_name> <key_format>\n";
    exit 1;
}

my ($server, $port, $cert_file, $key_file, $name, $format) = @ARGV;

my %response_hash = retrieve_key(
    server     => $server,
    port       => $port,
    cert_file  => $cert_file,
    key_file   => $key_file,
    key_name   => $name,
    key_format => $format
);

die "Server call failed, error code: " . $response_hash{'return_code'} if $response_hash{'return_code'} > 0;

my $key = $response_hash{'key'};
if ($format eq 'BIN') {
    my $key_size = int($response_hash{'size'});
    $key = unpack("H$key_size", $key)
}

print 'Retrieved key ' . $response_hash{'name'} . ": $key\n";

exit 0;

 

Appendix A: Perldoc Documentation

The following is an example of the perldoc documentation. Please use the perldoc command to view the current version of the module documentation.

NAME

    AKM::Encrypt - Encrypt or decrypt data using Townsend Security Alliance
    Key Manager server

VERSION

    Version 1.0.1

SYNOPSIS

    This Perl module is used to encrypt or decrypt data using Townsend
    Security Alliance Key Manager server.

    use AKM::Encrypt qw(encrypt decrypt);

    my $data_to_encrypt = 'Hello World23456'; # Length must be multiple of
    16 characters

    my %response_hash = encrypt( server => 'my.server.com', port => 6003,
    cert_file => 'certs/AKMClientSignedCert.pem', key_file =>
    'certs/AKMClientPrivKey.pem', data => $data_to_encrypt, iv => "x" x 16,
    key_name => 'My_key', );

    die "Server call failed, error code: " . $response_hash{'return_code'}
    if $response_hash{'return_code'} > 0;

    my $encrypted_data = $response_hash{'data'};

    %response_hash = decrypt( server => 'my.server.com', port => 6003,
    cert_file => 'certs/AKMClientSignedCert.pem', key_file =>
    'certs/AKMClientPrivKey.pem', data => $encrypted_data # Length must be
    multiple of 16 characters iv => "x" x 16, key_name => 'My_key', );

    die "Server call failed, error code: " . $response_hash{'return_code'}
    if $response_hash{'return_code'} > 0;

    my $decrypted_data = $response_hash{'data'};

    # At this point $decrypte_data eq $data_to_encrypt

EXPORT

    encrypt decrypt

SUBROUTINES/METHODS

  encrypt

    Sends data to Alliance Key Manager server for encryption.

    Method accepts hash of options as input parameter (not a hash
    reference).

   
Supported input options
    *   server

        Hostname/IP of Alliance Key Manager server

    *   port

        Port number to which AKM listens 

    *   cert_file

        Path to file with client certificate in PEM format.

    *   key_file

        Path to file with client private key in PEM format.

    *   key_file_password

        Password to file with client private key in PEM format. If private
        key file is encrypted and no password is given, interactive password
        prompt is shown.

    *   data

        Data to be encrypted. Length of data must be multiple of 16
        characters.

    *   key_name

        Name of the key stored in AKM to be used for encryption.

    *   key_instance

        An all blank value references the current instance. This is the
        version of the key to be used for encryption.

    *   iv

        Initialization vector to be used with CBC, must be 16 bytes long.

   Method output

    Method returns hash containing key attributes and the key.

    *   return_code

        Value 0000 indicates success. Value 0001-9999 represents an error
        condition.

    *   instance

        The same instance as in the request. If the request was blank this
        is the current instance.

    *   data

        Encrypted data.

  decrypt

    Sends encrypted data to Alliance Key Manager server for decryption.


    Method accepts hash of options as input parameter (not a hash
    reference).

   Supported input options
    *   server

        Hostname/IP of Alliance Key Manager server

    *   port

        Port number on which AKM listens to

    *   cert_file

        Path to file with client certificate in PEM format.

    *   key_file

        Path to file with client private key in PEM format.

    *   key_file_password

        Password to file with client private key in PEM format. If private
        key file is encrypted and no password is given, interactive password
        prompt is shown.

    *   data

        Data to be decrypted. Length of data must be multiple of 16
        characters.

    *   key_name

        Name of the key stored in AKM to be used for encryption.

    *   key_instance

        An all blank value references the current instance. This is the
        version of the key to be used for encryption.

    *   iv

        Initialization vector to be used with CBC, must be 16 bytes long.

   Method output

    Method returns hash containing key attributes and the key.

    *   return_code

        Value 0000 indicates success. Value 0001-9999 represents an error
        condition.

    *   instance

        The same instance as in the request. If the request was blank this
        is the current instance.

    *   data

        Decrypted data.

AUTHOR

    Townsend Security, "<info at townsendsecurity.com>"

BUGS

    Please report any bugs or feature requests to "bug-akm-encrypt at
    rt.cpan.org".

SUPPORT

    You can find documentation for this module with the perldoc command.

        perldoc AKM::Encrypt

COPYRIGHT & LICENSE

    Copyright (c) 2013 Townsend Security, Inc. Permission is granted to use
    this Perl module in your applications when accessing a properly licensed
    version of Alliance Key Manager.