org.ka2ddo.yaac.auth

Class YAACKeyManager

java.lang.Object

org.ka2ddo.yaac.auth.YAACKeyManager

All Implemented Interfaces:

javax.net.ssl.KeyManager, javax.net.ssl.X509KeyManager

public class YAACKeyManager
extends java.lang.Object
implements javax.net.ssl.X509KeyManager

This class stores encryption keys used for signing and verifying messages. There are two meanings of signing:

1. public key signing with the sender's private key and verifying with their public key.
2. secret key Hashed Message Authentication Code for signing and verifying.

This class is the repository for keys used for this signing and verifying, backed by a Java keystore. It supports:

1. private keys with associated public key certificate chains,
2. public key certificates of other users,
3. secret keys of the local user or other users.

The keys stored in the keystore are associated with lists of sending station ID's and broadcast (bulletin) addressees.

It also provides the APRS message signing and verifying logic, and provides a means to associate other station's callsigns with keys and certificates. This class also provides services to create, export, import, and delete keys and certificates.

This is based on research reported by Bryan Hoyer KG6GEU in a presentation to the NW Digital Radio group on 2013-Mar-31

Author:

Andrew Pavlin, KA2DDO

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	YAACKeyManager.KeyType Enumeration identifying different types of encryption keys that can be stored in the KeyManager.

Method Summary

Modifier and Type	Method and Description
java.lang.String	chooseClientAlias(java.lang.String[] keyTypes, java.security.Principal[] principals, java.net.Socket socket) Choose an alias to authenticate the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
java.lang.String	chooseServerAlias(java.lang.String algChoice, java.security.Principal[] principals, java.net.Socket socket) Choose an alias to authenticate the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
void	createSecretKey(java.lang.String alias) Create a new secret (symmetric) key.
void	deleteKey(java.lang.String alias) Delete a key from the local keystore.
boolean	doesKeystoreExistYet() Test if the keystore has been created yet,
java.lang.String[]	findMatchingKeys(java.lang.String callsign, YAACKeyManager.KeyType keyType) Search the keystore for keys that match the destination addressee of the specified message.
java.lang.String[]	getAliases() Get all key aliases stored in the keystore.
java.lang.String[]	getAssociations(java.lang.String alias) Get all the associated callsigns allowed to use the key specified by the alias.
java.security.cert.X509Certificate[]	getCertificateChain(java.lang.String alias) Returns the certificate chain associated with the given alias.
java.lang.String[]	getClientAliases(java.lang.String algChoice, java.security.Principal[] principals) Get the matching aliases for authenticating the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
static YAACKeyManager	getInstance() Get the KeyManager singleton.
java.security.Key	getKey(java.lang.String alias) Get the key associated with the specified alias.
YAACKeyManager.KeyType	getKeyType(java.lang.String alias) Get the type of key associated with the specified alias.
java.security.PrivateKey	getPrivateKey(java.lang.String alias) Get the PrivateKey associated with the specified alias.
java.lang.String[]	getServerAliases(java.lang.String algChoice, java.security.Principal[] principals) Get the matching aliases for authenticating the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
void	insertPrivateKey(java.lang.String alias, java.security.PrivateKey key, java.security.cert.Certificate[] certs) Insert a private key with its associated public key certificate chain.
void	insertPublicCertificateChain(java.lang.String alias, java.security.cert.CertPath chain) Store the public key certificates for some other station into the keystore.
void	insertSecretKey(java.lang.String alias, byte[] encoded) Store a byte-encoded secret (symmetric) key in the keystore.
boolean	isPasswordSet() Test if the backing keystore's password has been set.
static void	main(java.lang.String[] args) unit test.
void	setAssociations(java.lang.String alias, java.lang.String[] associations) Get all the associated callsigns allowed to use the key specified by the alias.
void	setPassword(char[] password) Set the password to be used to decode keys in the backing keystore.
void	sign(AprsSignableMessage mm, java.lang.String alias) Sign a timestamped APRS message with the specified key.
SignableMessage.SignatureState	verify(AprsSignableMessage mm) Verify the signature (if any) in an APRS message against the keys in the local keystore.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static YAACKeyManager getInstance()

Get the KeyManager singleton.

Returns:

instance of KeyManager

isPasswordSet

public boolean isPasswordSet()

Test if the backing keystore's password has been set.

Returns:

boolean true if password has been successfully set

setPassword

public void setPassword(char[] password)
                 throws java.lang.NullPointerException,
                        java.io.IOException,
                        java.security.GeneralSecurityException

Set the password to be used to decode keys in the backing keystore.

Parameters:

password - char array of the password

Throws:

java.lang.NullPointerException - if password was null

java.io.IOException - if keystore file could not be read for any reason

java.security.GeneralSecurityException - if keystore file could not be decoded for any reason

doesKeystoreExistYet

public boolean doesKeystoreExistYet()

Test if the keystore has been created yet,

Returns:

boolean true if keystore backing file exists (i.e., the keystore has been created)

getKey

public java.security.Key getKey(java.lang.String alias)
                         throws java.lang.NullPointerException

Get the key associated with the specified alias.

Parameters:

alias - String alias name for a key

Returns:

the Key associated with the alias

Throws:

java.lang.NullPointerException - if the keystore's password was not successfully set yet

getAliases

public java.lang.String[] getAliases()
                              throws java.lang.NullPointerException

Get all key aliases stored in the keystore.

Returns:

array of String aliases

Throws:

java.lang.NullPointerException - if the keystore's password was not successfully set yet

getKeyType

public YAACKeyManager.KeyType getKeyType(java.lang.String alias)
                                  throws java.lang.NullPointerException

Get the type of key associated with the specified alias.

Parameters:

alias - String name associated with the desired key

Returns:

KeyType specifying the kind of key associated with the alias, or null if no key with the specified alias

Throws:

java.lang.NullPointerException - if the keystore's password was not successfully set yet

getAssociations

public java.lang.String[] getAssociations(java.lang.String alias)

Get all the associated callsigns allowed to use the key specified by the alias.

Parameters:

alias - String name of the key to query

Returns:

array of callsigns and broadcast aliases associated with the named key (possibly zero length if no associations)

setAssociations

public void setAssociations(java.lang.String alias,
                            java.lang.String[] associations)

Get all the associated callsigns allowed to use the key specified by the alias.

Parameters:

alias - String name of the key to modify

associations - array of callsign Strings to associate with named key

createSecretKey

public void createSecretKey(java.lang.String alias)
                     throws java.lang.NullPointerException,
                            java.security.KeyStoreException

Create a new secret (symmetric) key.

Parameters:

alias - String name to label the key

Throws:

java.lang.NullPointerException - if keystore password hasn't been correctly set yet

java.security.KeyStoreException - if key can't be stored in backing keystore file

insertSecretKey

public void insertSecretKey(java.lang.String alias,
                            byte[] encoded)
                     throws java.lang.NullPointerException,
                            java.security.KeyStoreException

Store a byte-encoded secret (symmetric) key in the keystore. Used to import a key generated by someone else.

Parameters:

alias - String name to associate with key

encoded - byte array of the encoded key

Throws:

java.lang.NullPointerException - if keystore password hasn't been correctly set yet

java.security.KeyStoreException - if key can't be stored in backing keystore file

insertPublicCertificateChain

public void insertPublicCertificateChain(java.lang.String alias,
                                         java.security.cert.CertPath chain)

Store the public key certificates for some other station into the keystore.

Parameters:

alias - String name to associate with this public key

chain - array of Certificates containing the public key and identifying the issuers up to the certificate authority

insertPrivateKey

public void insertPrivateKey(java.lang.String alias,
                             java.security.PrivateKey key,
                             java.security.cert.Certificate[] certs)
                      throws java.security.KeyStoreException

Insert a private key with its associated public key certificate chain.

Parameters:

alias - String name to associate with this key pair

key - PrivateKey

certs - array of Certificates listing the public key associated with the private key and the issuers up to the certificate authority

Throws:

java.security.KeyStoreException - if the key pair could not be stored

deleteKey

public void deleteKey(java.lang.String alias)
               throws java.security.KeyStoreException,
                      java.io.IOException

Delete a key from the local keystore.

Parameters:

alias - String name of the key

Throws:

java.security.KeyStoreException - if the keystore can't be modified

java.io.IOException - if the altered keystore can't be checkpointed to the backing disk file

findMatchingKeys

public java.lang.String[] findMatchingKeys(java.lang.String callsign,
                                           YAACKeyManager.KeyType keyType)

Search the keystore for keys that match the destination addressee of the specified message.

Parameters:

callsign - String callsign to be matched against the known keys

keyType - KeyType of keys to be searched for, or null to search for all types

Returns:

array of String names of keys that are associated with the specified callsign string (may be zero-length if no matches)

sign

public void sign(AprsSignableMessage mm,
                 java.lang.String alias)
          throws java.lang.NullPointerException,
                 java.lang.IllegalStateException,
                 java.lang.IllegalArgumentException,
                 java.security.GeneralSecurityException

Sign a timestamped APRS message with the specified key.

Parameters:

mm - MessageMessage to sign

alias - String name of key to use for signature

Throws:

java.lang.NullPointerException - if keystore password hasn't been correctly set yet

java.lang.IllegalStateException - if message has already been signed

java.lang.IllegalArgumentException - if no such key for specified alias

java.security.GeneralSecurityException - if key does not exist or signature algorithm doesn't work or isn't available

verify

public SignableMessage.SignatureState verify(AprsSignableMessage mm)
                                      throws java.security.GeneralSecurityException

Verify the signature (if any) in an APRS message against the keys in the local keystore.

Parameters:

mm - MessageMessage to verify

Returns:

SignatureState of the message

Throws:

java.security.GeneralSecurityException - if key does not exist or signature algorithm doesn't work or isn't available

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

unit test.

Parameters:

args - String array, [0] = password, [1] = alias to use for test

Throws:

java.lang.Exception - if test fails

chooseClientAlias

public java.lang.String chooseClientAlias(java.lang.String[] keyTypes,
                                          java.security.Principal[] principals,
                                          java.net.Socket socket)

Choose an alias to authenticate the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Specified by:

chooseClientAlias in interface javax.net.ssl.X509KeyManager

Parameters:

keyTypes - the key algorithm type name(s), ordered with the most-preferred key type first.

principals - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.

socket - he socket to be used for this connection. This parameter can be null, which indicates that implementations are free to select an alias applicable to any socket.

Returns:

the alias name for the desired key, or null if there are no matches

getClientAliases

public java.lang.String[] getClientAliases(java.lang.String algChoice,
                                           java.security.Principal[] principals)

Get the matching aliases for authenticating the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Specified by:

getClientAliases in interface javax.net.ssl.X509KeyManager

Parameters:

algChoice - the key algorithm type name

principals - the list of acceptable CA issuer subject names, or null if it does not matter which issuers are used.

Returns:

an array of the matching alias names, or null if there were no matches.

getServerAliases

public java.lang.String[] getServerAliases(java.lang.String algChoice,
                                           java.security.Principal[] principals)

Get the matching aliases for authenticating the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Specified by:

getServerAliases in interface javax.net.ssl.X509KeyManager

Parameters:

algChoice - the key algorithm type name

principals - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.

Returns:

an array of the matching alias names, or null if there were no matches.

chooseServerAlias

public java.lang.String chooseServerAlias(java.lang.String algChoice,
                                          java.security.Principal[] principals,
                                          java.net.Socket socket)

Choose an alias to authenticate the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Specified by:

chooseServerAlias in interface javax.net.ssl.X509KeyManager

Parameters:

algChoice - the key algorithm type name.

principals - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.

socket - the socket to be used for this connection. This parameter can be null, which indicates that implementations are free to select an alias applicable to any socket.

Returns:

the alias name for the desired key, or null if there are no matches.

getCertificateChain

public java.security.cert.X509Certificate[] getCertificateChain(java.lang.String alias)

Returns the certificate chain associated with the given alias.

Specified by:

getCertificateChain in interface javax.net.ssl.X509KeyManager

Parameters:

alias - the alias name

Returns:

the certificate chain (ordered with the user's certificate first and the root certificate authority last), or null if the alias can't be found.

getPrivateKey

public java.security.PrivateKey getPrivateKey(java.lang.String alias)
                                       throws java.lang.NullPointerException

Get the PrivateKey associated with the specified alias.

Specified by:

getPrivateKey in interface javax.net.ssl.X509KeyManager

Parameters:

alias - String name of key to look up

Returns:

PrivateKey for the alias, or null if no such key

Throws:

java.lang.NullPointerException - if the keystore has not been opened yet