NSS Sample Code 1: Key Generation and Transport Between Servers.
This is an example program that demonstrates how to do key generation and transport between cooperating servers. This program shows the following:
- RSA key pair generation
- Naming RSA key pairs
- Looking up a previously generated key pair by name
- Creating AES and MAC keys (or encryption and MAC keys in general)
- Wrapping symmetric keys using your own RSA key pair so that they can be stored on disk or in a database.
- As an alternative to TOKEN symmetric keys
- As a way to store large numbers of symmetric keys
- Wrapping symmetric keys using an RSA key from another server
- Unwrapping keys using your own RSA key pair
The main part of the program shows a typical sequence of events for two servers that are trying to extablish a shared key pair.
We will add message protection (encryption and MACing) examples to this program in the future.
Sample Code
#include <iostream.h>
#include "pk11pub.h"
#include "keyhi.h"
#include "nss.h"
// Key management for keys share among multiple hosts
//
// This example shows how to use NSS functions to create and
// distribute keys that need to be shared among multiple servers
// or hosts.
//
// The management scheme assumes that one host is PRIMARY. It
// generates the secret keys that will be used by all participating
// hosts. The other hosts (SECONDARY) request keys from the
// primary host. As an alternative, new keys may be sent to the
// current set of SECONDARY hosts when they are generated by the
// PRIMARY. In this case, the PRIMARY maintains a list of the
// secondary hosts.
//
// The sequence of events is:
// 1. The primary host generates a new symmetric key. This key
// may be used for an encryption mechanism (DES or AES) or for
// integrity (MD5_HMAC or SHA1_HMAC). This key needs to be
// permanent, since it may be used during several runs of the
// server. (Currently NSS doesn't store persistant keys. Steps
// 1a through 1x show how to do this).
// 1a. The primary host generates an RSA keypair that will be used
// store keys locally.
// 1b. The primary host wraps the newly generated key using the
// RSA key and stores the wrapped key data in a local file.
// 1c. The primary host unwraps the key using the RSA key each time
// access to the key is required, such as at server startup.
// 2. The secondary host generates an RSA keypair that will be used
// to transport keys between the primary host and itself. This
// key needs to exist long enough to be used to process the
// response to a key transport request that is made to the primary
// server. The example here shows how to create a permanent (token)
// RSA key for this purpose. (This key will also be used for
// storage of the keys, since NSS does not support permanent symmetric
// keys at the current time.)
// 3. The secondary host sends its RSA public key to the primary host as
// part of a request for a particular key, or to be added to a list
// of secondary hosts.
// 4. The administrator of the primary host verifies that the RSA key
// that was received belongs to a valid secondary host. The adminstrator
// may do this by checking that the key was received in a signed email
// message, or by checking a digest value with the adminstrator of the
// secondary host. [Need support for digest check values]
// 5. The primary host exports (wraps) the symmetric key using the
// secondary host's RSA key. The wrapped value is sent back to
// the secondary host.
// 6. The administrator of the secondary host verifies that the wrapped
// key data came from the primary host. The same methods outlined
// in step 4 may be used here.
// 7. The secondary host unwraps the the key using its own RSA private key.
// NOTE: currently NSS does not support permanent symmetric keys.
// The secondary host may store the wrapped value that was received
// from the primary in a file, and unwrap it each time the key is required
// (such as at server startup).
// NSS actually has some support for permanent symmetric keys. However this
// example will need to be modified somewhat in order to demonstrate it.
// Utility function to print hex data
static void
printBuffer(unsigned char *digest, unsigned int len)
{
int i;
cout << "length: " << len << endl;
for(i = 0;i < len;i++) printf("%02x ", digest[i]);
cout << endl;
}
// XXX Data protection
// - takes an input buffer, applies the encryption
// and MAC, and generates a buffer with the result.
// - the application sends or uses the result (possibly
// after base64 encoding it.
//
// Server - an instance of a server that is part of a
// cluster of servers that are sharing a common set
// of encryption and MACing keys.
//
class Server
{
public:
// Initializes the server instance. In particular, this
// creates the key pair that is used for wrapping keys
int Init();
// Generates keys for encryption (AES) and MACing. The
// wrapped keys are stored in data files.
int GenerateKeys();
// Gets the server's public key (wrapping key) to
// send to another server. This becomes the input to
// the ExportKeys method on the remote server.
int ExportPublicKey(SECItem **pubKeyData);
// Export the encryption and key using the key
// provided. The key should come from another server
// in the cluster. (The admin should verify this.)
//
// In this example, the server must be started to perform
// this function (see Start())
int ExportKeys(SECItem *pubKey, SECItem **wrappedEncKey,
SECItem **wrappedMacKey);
// Import the keys received from another server in the
// cluster. The admin should make sure the keys actually
// came from the correct source.
int ImportKeys(SECItem *wrappedEncKey, SECItem *wrappedMacKey);
// Start the server, loading the encryption and MACing keys
// from files
int Start();
// Shut down the server. (For completeness)
int Shutdown();
// Compare keys in two server instances. Use this in the
// example to make sure the keys are transferred correctly.
// This will not work in real life!
//
// The servers must be started
int CompareKeys(Server *peer);
// Create a server - the name distiguish the keys in the
// shared database in this example
Server(const char *serverName);
~Server();
private:
int getPrivateKey(SECKEYPrivateKey **prvKey);
int getPublicKey(SECKEYPublicKey **pubKey);
int wrapKey(PK11SymKey *key, SECKEYPublicKey *pubKey, SECItem **data);
// export raw key (unwrapped) DO NOT USE
int rawExportKey(PK11SymKey *key, SECItem **data);
char *mServerName;
// These items represent data that might be stored
// in files or in a configuration file
SECItem *mWrappedEncKey;
SECItem *mWrappedMacKey;
// These are the runtime keys as loaded from the files
PK11SymKey *mEncKey;
PK11SymKey *mMacKey;
};
Server::Server(const char *serverName)
: mServerName(0), mWrappedEncKey(0), mWrappedMacKey(0),
mEncKey(0), mMacKey(0)
{
// Copy the server name
mServerName = PL_strdup(serverName);
}
Server::~Server()
{
if (mServerName) PL_strfree(mServerName);
if (mWrappedEncKey) SECITEM_FreeItem(mWrappedEncKey, PR_TRUE);
if (mWrappedMacKey) SECITEM_FreeItem(mWrappedMacKey, PR_TRUE);
if (mEncKey) PK11_FreeSymKey(mEncKey);
if (mMacKey) PK11_FreeSymKey(mMacKey);
}
int
Server::Init()
{
int rv = 0;
SECKEYPrivateKey *prvKey = 0;
SECKEYPublicKey *pubKey = 0;
PK11SlotInfo *slot = 0;
PK11RSAGenParams rsaParams;
SECStatus s;
// See if there is already a private key with this name.
// If there is one, no further action is required.
rv = getPrivateKey(&prvKey);
if (rv == 0 && prvKey) goto done;
rv = 0;
// These could be parameters to the Init function
rsaParams.keySizeInBits = 1024;
rsaParams.pe = 65537;
slot = PK11_GetInternalKeySlot();
if (!slot) { rv = 1; goto done; }
prvKey = PK11_GenerateKeyPair(slot, CKM_RSA_PKCS_KEY_PAIR_GEN, &rsaParams,
&pubKey, PR_TRUE, PR_TRUE, 0);
if (!prvKey) { rv = 1; goto done; }
// Set the nickname on the private key so that it
// can be found later.
s = PK11_SetPrivateKeyNickname(prvKey, mServerName);
if (s != SECSuccess) { rv = 1; goto done; }
done:
if (slot) PK11_FreeSlot(slot);
if (pubKey) SECKEY_DestroyPublicKey(pubKey);
if (prvKey) SECKEY_DestroyPrivateKey(prvKey);
return rv;
}
int
Server::GenerateKeys()
{
int rv = 0;
SECKEYPublicKey *pubKey = 0;
PK11SlotInfo *slot = 0;
// Choose a slot to use
slot = PK11_GetInternalKeySlot();
if (!slot) { rv = 1; goto done; }
// Get our own public key to use for wrapping
rv = getPublicKey(&pubKey);
if (rv) goto done;
// Do the Encryption (AES) key
if (!mWrappedEncKey)
{
PK11SymKey *key = 0;
// The key size is 128 bits (16 bytes)
key = PK11_KeyGen(slot, CKM_AES_KEY_GEN, 0, 128/8, 0);
if (!key) { rv = 1; goto aes_done; }
rv = wrapKey(key, pubKey, &mWrappedEncKey);
aes_done:
if (key) PK11_FreeSymKey(key);
if (rv) goto done;
}
// Do the Mac key
if (!mWrappedMacKey)
{
PK11SymKey *key = 0;
// The key size is 160 bits (20 bytes)
key = PK11_KeyGen(slot, CKM_GENERIC_SECRET_KEY_GEN, 0, 160/8, 0);
if (!key) { rv = 1; goto mac_done; }
rv = wrapKey(key, pubKey, &mWrappedMacKey);
mac_done:
if (key) PK11_FreeSymKey(key);
}
done:
if (slot) PK11_FreeSlot(slot);
return rv;
}
int
Server::ExportPublicKey(SECItem **pubKeyData)
{
int rv = 0;
SECKEYPublicKey *pubKey = 0;
rv = getPublicKey(&pubKey);
if (rv) goto done;
*pubKeyData = SECKEY_EncodeDERSubjectPublicKeyInfo(pubKey);
if (!*pubKeyData) { rv = 1; goto done; }
done:
if (pubKey) SECKEY_DestroyPublicKey(pubKey);
return rv;
}
int
Server::ExportKeys(SECItem *pubKeyData, SECItem **wrappedEncKey,
SECItem **wrappedMacKey)
{
int rv;
CERTSubjectPublicKeyInfo *keyInfo = 0;
SECKEYPublicKey *pubKey = 0;
SECItem *data = 0;
// Make sure the keys are available (server running)
if (!mEncKey || !mMacKey) { rv = 1; goto done; }
// Import the public key of the other server
keyInfo = SECKEY_DecodeDERSubjectPublicKeyInfo(pubKeyData);
if (!keyInfo) { rv = 1; goto done; }
pubKey = SECKEY_ExtractPublicKey(keyInfo);
if (!pubKey) { rv = 1; goto done; }
// Export the encryption key
rv = wrapKey(mEncKey, pubKey, &data);
if (rv) goto done;
// Export the MAC key
rv = wrapKey(mMacKey, pubKey, wrappedMacKey);
if (rv) goto done;
// Commit the rest of the operation
*wrappedEncKey = data;
data = 0;
done:
if (data) SECITEM_FreeItem(data, PR_TRUE);
if (pubKey) SECKEY_DestroyPublicKey(pubKey);
if (keyInfo) SECKEY_DestroySubjectPublicKeyInfo(keyInfo);
return rv;
}
int
Server::ImportKeys(SECItem *wrappedEncKey, SECItem *wrappedMacKey)
{
int rv = 0;
if (mWrappedEncKey || mWrappedMacKey) { rv = 1; goto done; }
mWrappedEncKey = SECITEM_DupItem(wrappedEncKey);
if (!mWrappedEncKey) { rv = 1; goto done; }
mWrappedMacKey = SECITEM_DupItem(wrappedMacKey);
if (!mWrappedMacKey) { rv = 1; goto done; }
done:
return rv;
}
int
Server::Start()
{
int rv;
SECKEYPrivateKey *prvKey = 0;
rv = getPrivateKey(&prvKey);
if (rv) goto done;
if (!mEncKey)
{
// Unwrap the encryption key from the "file"
// This function uses a mechanism rather than a key type
// Does this need to be "WithFlags"??
mEncKey = PK11_PubUnwrapSymKey(prvKey, mWrappedEncKey,
CKM_AES_CBC_PAD, CKA_ENCRYPT, 0);
if (!mEncKey) { rv = 1; goto done; }
}
if (!mMacKey)
{
// Unwrap the MAC key from the "file"
// This function uses a mechanism rather than a key type
// Does this need to be "WithFlags"??
mMacKey = PK11_PubUnwrapSymKey(prvKey, mWrappedMacKey,
CKM_MD5_HMAC, CKA_SIGN, 0);
if (!mMacKey) { rv = 1; goto done; }
}
done:
if (prvKey) SECKEY_DestroyPrivateKey(prvKey);
return rv;
}
int
Server::Shutdown()
{
if (mEncKey) PK11_FreeSymKey(mEncKey);
if (mMacKey) PK11_FreeSymKey(mMacKey);
mEncKey = 0;
mMacKey = 0;
return 0;
}
int
Server::CompareKeys(Server *peer)
{
int rv;
SECItem *macKey1 = 0;
SECItem *macKey2 = 0;
SECItem *encKey1 = 0;
SECItem *encKey2 = 0;
// Export each of the keys in raw form
rv = rawExportKey(mMacKey, &macKey1);
if (rv) goto done;
rv = rawExportKey(peer->mMacKey, &macKey2);
if (rv) goto done;
rv = rawExportKey(mEncKey, &encKey1);
if (rv) goto done;
rv = rawExportKey(peer->mEncKey, &encKey2);
if (rv) goto done;
if (!SECITEM_ItemsAreEqual(macKey1, macKey2)) { rv = 1; goto done; }
if (!SECITEM_ItemsAreEqual(encKey1, encKey2)) { rv = 1; goto done; }
done:
if (macKey1) SECITEM_ZfreeItem(macKey1, PR_TRUE);
if (macKey2) SECITEM_ZfreeItem(macKey2, PR_TRUE);
if (encKey1) SECITEM_ZfreeItem(encKey1, PR_TRUE);
if (encKey2) SECITEM_ZfreeItem(encKey2, PR_TRUE);
return rv;
}
// Private helper, retrieves the private key for the server
// from the database. Free the key using SECKEY_DestroyPrivateKey
int
Server::getPrivateKey(SECKEYPrivateKey **prvKey)
{
int rv = 0;
PK11SlotInfo *slot = 0;
SECKEYPrivateKeyList *list = 0;
SECKEYPrivateKeyListNode *n;
char *nickname;
slot = PK11_GetInternalKeySlot();
if (!slot) goto done;
// ListPrivKeysInSlot looks like it should check the
// nickname and only return keys that match. However,
// that doesn't seem to work at the moment.
// BUG: XXXXX
list = PK11_ListPrivKeysInSlot(slot, mServerName, 0);
cout << "getPrivateKey: list = " << list << endl;
if (!list) { rv = 1; goto done; }
for(n = PRIVKEY_LIST_HEAD(list);
!PRIVKEY_LIST_END(n, list);
n = PRIVKEY_LIST_NEXT(n))
{
nickname = PK11_GetPrivateKeyNickname(n->key);
if (PL_strcmp(nickname, mServerName) == 0) break;
}
if (PRIVKEY_LIST_END(n, list)) { rv = 1; goto done; }
*prvKey = SECKEY_CopyPrivateKey(n->key);
done:
if (list) SECKEY_DestroyPrivateKeyList(list);
return rv;
}
int
Server::getPublicKey(SECKEYPublicKey **pubKey)
{
int rv;
SECKEYPrivateKey *prvKey = 0;
rv = getPrivateKey(&prvKey);
if (rv) goto done;
*pubKey = SECKEY_ConvertToPublicKey(prvKey);
if (!*pubKey) { rv = 1; goto done; }
done:
if (prvKey) SECKEY_DestroyPrivateKey(prvKey);
return rv;
}
int
Server::wrapKey(PK11SymKey *key, SECKEYPublicKey *pubKey, SECItem **ret)
{
int rv = 0;
SECItem *data;
SECStatus s;
data = (SECItem *)PORT_ZAlloc(sizeof(SECItem));
if (!data) { rv = 1; goto done; }
// Allocate space for output of wrap
data->len = SECKEY_PublicKeyStrength(pubKey);
data->data = new unsigned char[data->len];
if (!data->data) { rv = 1; goto done; }
s = PK11_PubWrapSymKey(CKM_RSA_PKCS, pubKey, key, data);
if (s != SECSuccess) { rv = 1; goto done; }
*ret = data;
data = 0;
done:
if (data) SECITEM_FreeItem(data, PR_TRUE);
return rv;
}
// Example of how to do a raw export (no wrapping of a key)
// This should not be used. Use the RSA-based wrapping
// methods instead.
int
Server::rawExportKey(PK11SymKey *key, SECItem **res)
{
int rv = 0;
SECItem *data;
SECStatus s;
s = PK11_ExtractKeyValue(key);
if (s != SECSuccess) { rv = 1; goto done; }
data = PK11_GetKeyData(key);
*res = SECITEM_DupItem(data);
if (!*res) { rv = 1; goto done; }
done:
return rv;
}
// Initialize the NSS library. Normally this
// would be done as part of each server's startup.
// However, this example uses the same databases
// to store keys for server in the "cluster" so
// it is done once.
int
InitNSS()
{
int rv = 0;
SECStatus s;
s = NSS_InitReadWrite(".");
if (s != SECSuccess) rv = 1; // Error
// For this example, we don't use database passwords
PK11_InitPin(PK11_GetInternalKeySlot(), "", "");
return rv;
}
int
main(int argc, char *argv[])
{
int rv;
Server *server1 = 0;
Server *server2 = 0;
// Initialize NSS
rv = InitNSS();
if (rv) { cout << "InitNSS failed" << endl; goto done; }
// Create the first "server"
server1 = new Server("Server1");
if (!server1 || server1->Init())
{
cout << "Server1 could not be created" << endl;
rv = 1;
goto done;
}
// Generate encryption and mac keys. These keys will
// be used by all the servers in the cluster.
rv = server1->GenerateKeys();
if (rv) { cout << "GenerateKeys failed" << endl; goto done; }
// Now that everything is ready, start server1. This loads
// the encryption and MAC keys from the "files"
rv = server1->Start();
if (rv) { cout << "Cannot start server 1" << endl; goto done; }
// Create a second server in the cluster. We will need
// to transfer the keys from the first server to this
// one
server2 = new Server("Server2");
if (!server2 || server2->Init())
{
cout << "Server2 could not be created" << endl;
rv = 1; // Error
goto done;
}
// Transfer the keys from server1
{
SECItem *wrappedEncKey = 0;
SECItem *wrappedMacKey = 0;
SECItem *pubKeyData = 0;
// Get the public key for server 2 so that it can
// be sent to server 1
rv = server2->ExportPublicKey(&pubKeyData);
if (rv) { cout << "ExportPublicKey failed" << endl; goto trans_done; }
// Send the public key to server 1 and get back the
// wrapped key values
rv = server1->ExportKeys(pubKeyData, &wrappedEncKey, &wrappedMacKey);
if (rv) { cout << "ExportKeys failed" << endl; goto trans_done; }
// Print - for information
cout << "Wrapped Encryption Key" << endl;
printBuffer(wrappedEncKey->data, wrappedEncKey->len);
cout << "Wrapped MAC Key" << endl;
printBuffer(wrappedMacKey->data, wrappedMacKey->len);
// Import the keys into server 2 - this just puts the wrapped
// values into the "files"
rv = server2->ImportKeys(wrappedEncKey, wrappedMacKey);
if (rv) { cout << "ImportKeys failed" << endl; goto trans_done; }
trans_done:
if (wrappedEncKey) SECITEM_FreeItem(wrappedEncKey, PR_TRUE);
if (wrappedMacKey) SECITEM_FreeItem(wrappedMacKey, PR_TRUE);
if (pubKeyData) SECITEM_FreeItem(pubKeyData, PR_TRUE);
}
if (rv) goto done;
// Start server 2 - this unwraps the encryption and MAC keys
// so that they can be used
rv = server2->Start();
if (rv) { cout << "Cannot start server 2" << endl; goto done; }
// List keys in the token - informational
{
PK11SlotInfo *slot = 0;
SECKEYPrivateKeyList *list = 0;
SECKEYPrivateKeyListNode *n;
slot = PK11_GetInternalKeySlot();
if (!slot) goto list_done;
cout << "List Private Keys" << endl;
list = PK11_ListPrivKeysInSlot(slot, 0, 0);
if (!list) goto list_done;
for(n = PRIVKEY_LIST_HEAD(list);
!PRIVKEY_LIST_END(n, list);
n = PRIVKEY_LIST_NEXT(n))
{
char *name;
name = PK11_GetPrivateKeyNickname(n->key);
cout << "Key: " << name << endl;
}
list_done:
if (slot) PK11_FreeSlot(slot);
if (list) SECKEY_DestroyPrivateKeyList(list);
cout << "Done" << endl;
}
// Let's see if the keys are the same
rv = server1->CompareKeys(server2);
if (rv) { cout << "Key Comparison failed" << endl; }
server1->Shutdown();
server2->Shutdown();
done:
if (server1) delete server1;
if (server2) delete server2;
NSS_Shutdown();
return rv;
}