Chapter 1: Introduction

Alliance Key Manager implements a wire protocol for encryption key retrieval. This means that any client application that is capable of creating an TLS connection to the key server, and which has the proper X509 certificates, can retrieve encryption keys from the key server. The PHP language does provide this type of support and PHP developers can easily retrieve 128-bit, 192-bit, and 256-bit encryption keys for use with the AES (Rijndael) encryption algorithm.

Change log

Version Date Description
2.0.4.001 1/10/2010 Reformat and revise for AKM version 2.0.0
2.0.4.002 10/23/2013 New manual format.
2.0.4.003 10/28/2019 Added comments for failover

Chapter 2: Key Retrieval API Documentation

The AKM Key Service API Reference provides a full description of the key retrieval interface. Please refer to this manual for more information about key retrieval fields and options. The sample code below provides a quick view of a sample key retrieval application. Note that in the PHP sample code below the key instance name is set to blanks to indicate the default instance of the key (see the “%24s” directive). If you are decrypting you will probably want to specify the actual key instance name to use.

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. The client PEM file contains the client X509 certificate and private key (cat the two PEM files together), and the Certificate Authority file contains the CA certificate from the key server. You should protect these files with native Linux/Unix security.

Chapter 4: Sample PHP Code

The following code example shows a simple method of retrieving an encryption key from the AKM server. You should modify this code for use in your environment.

Note: Commented sections have been added to this code where failover logic could be implemented.

<?php

// This just gets more error info displayed when needed
function myErrorHandler($errno, $errstr)
{
    echo "<br />\nerror [$errno] $errstr";
    return false;
}

// This sets up the TLS options, including server cert verification against the CA cert
// and presenting a client certificate to the server
$opts = array(
    'ssl' => array(
        'cafile' => '/home/jim/portland-root-ca-cert.pem',
        'capture_peer_cert' => true,
        'local_cert' => '/home/jim/client_cert_and_key.pem',
        'verify_peer' => true
    )
);

// This creates the TLS context for the connection to the key server
$ctx = stream_context_create($opts);

// This connects to the AKM server
// Change this host name to the name of your host, or the IP address of your host.
$host = 'ec2-184-73-72-217.compute-1.amazonaws.com:6000';

// This creates the connection to the key server
$fp = stream_socket_client('tls://'.$host, $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);

**// If the connection fails you can implement connection to a failover server here**

// This just dumps the contents of the server cert
$opts = stream_context_get_options($ctx);
$server_cert = $opts['ssl']['peer_certificate'];
var_dump(openssl_x509_parse($server_cert));

// This requests the current instance of key 'Key01-128' and displays the key value in hex
// Quick-and-dirty code...
if ($fp) {
    // Change ‘B16’ to ‘BIN’ for a binary key, or ‘B64’ for Bases64 encoded key
    // Change ‘Key01-128’ to your key name
    $request = sprintf("000712001%-40s%24sB16", 'Key01-128', '');
    fputs($fp, $request);
    $len = fread($fp, 5);
    if ($len) {
        $rsp = fread($fp, $len + 1);
        if ($rsp) {
             $value = substr($rsp, 95);
             echo "<p><b> $value </b>";
        }
    }
    fclose($fp);
} else {
    echo "<p>errno: $errno, errstr: $errstr";
}
?>