PIRL.Utilities

## Class Authentication

- java.lang.Object
- - PIRL.Utilities.Authentication

    public class Authentication
    extends Object

The Authentication class contains a set of functions used for public-private key pair authentication.

The typical uses for the Authentication functions is with a server that needs to authenticate a client connection. For example:

1. Password - The client and the server obtain the same password.

   The password, a text string, need not be limited to a single, short word; a pass phrase is likely to be more secure. How the client and server obtain the password is application specific. A client is likely to obtain the password by means of an interactive dialog with the user. A server is likely to obtain the password from a permission protected file.

2. Keys - The server initializes the public-private key pair.

   The key pair provides a public key that will be sent to the client and a private key that will be used to decrypt the encrypted password returned by the client. This may be done once at server startup if a single key pair is considered suffient for authenticating all clients. Alternatively each time a client connection occurs a key pair may be generated in which case each key pair must be associated with the corresponding client.

3. Public_Key - The server generates an encoded public key.

   The public key from the key pair is serialized and encoded as a hexadecimal representation string. This is done to ensure that the public key can be sent by the server to the client even when binary data transport is not supported. As with the key pair, this may be done once for use with all clients or for each client connection.

4. The server sends the encoded public key to the client.

   When a client connects to the server a handshake occurs during which authentication information is exchanged. The first step of the authentication handshake exchange is the server sending the public key to the client.

5. Encoded_Password - The client encryptes and encodes its password using the public key.

   The public key received from the server is used to encrypt and encode the password. As with the public key, the encoded form of the encrypted password provides a hexidecimal respresentation string of encryption bytes which can be sent to the server even if binary data transport is not avaialable.

6. The client sends the encoded password to the server.

   This is the second step of the client-server authentication handshake exchange.

7. Authenticate - The server decodes and decryptes the encoded password using the private key.

   The server decodes and decrypts the encoded password received from the client using the private key of the key pair. If the resultant string matches the password that server knows then the client is successfully authenticated. Otherwise the client has failed to provide the required authentication information.

### Field Summary

Fields
`static String` `ID` Class identification name with source code version and date.

### Method Summary

Methods
`static boolean` `Authenticate(KeyPair keys, String encoded_password, String password)` Authenticate an encoded password.
`static byte[]` `Decode_Hex(String string)` Decode a hexadecimal string to its byte array equivalent.
`static String` `Encode_Hex(byte[] bytes)` Encode a byte array to a hexadecimal string representation.
`static String` `Encoded_Password(String password, String public_key)` Encrypte and encode a password using an encoded public key.
`static KeyPair` `Keys()` Generate a public-private key pair.
`static String` `Public_Key(KeyPair keys)` Create a string representation of a public key.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### ID

    public static final String ID

Class identification name with source code version and date.

See Also:
  Constant Field Values

### Method Detail

#### Keys

    public static KeyPair Keys()
                        throws NoSuchAlgorithmException,
                               NoSuchProviderException

Generate a public-private key pair.

A KeyPairGenerator is initialized with a SecureRandom seed and then used to generate a KeyPair.

Returns:
  A KeyPair to be used for asymmetric encryption.
Throws:
  `NoSuchAlgorithmException`
  `NoSuchProviderException`

#### Public_Key

    public static String Public_Key(KeyPair keys)
                             throws IOException

Create a string representation of a public key.

The `public key` of the `public-private key pair` is serialized as a byte array that is `encoded` as a string in hexadecimal notation.

An encoded public key is expected to be sent to a client for use in generating an `encoded password`.

Parameters:
  `keys` - A KeyPair that contains a public key.
Returns:
  A String representation of a public key. This will be null if the keys are null.
Throws:
  `IOException`

#### Encoded_Password

    public static String Encoded_Password(String password,
                          String public_key)

Encrypte and encode a password using an encoded public key.

An `encoded public key` is `decoded` from its hexadecimal representation and then de-serialzed to a PublicKey object. This is used to encrypt the password string. The encrypted bytes are `encoded` into a hexadecimal representation string.

An encoded password provides secure authentication credentials for a client. It is expected to be sent to the server that provided the encoded public key for `authentication`.

Parameters:
  `password` - The clear text String that is to be encrypted.
  `public_key` - A hexadecimal String representation of a serialized PublicKey.
Returns:
  A hexadecimal String representation of the encryped password. This will be null if the password is null, the public_key is null, the public_key could not be decoded or de-serialized, or the password could not be encrypted. Only a valid non-null String will be returned.

#### Authenticate

    public static boolean Authenticate(KeyPair keys,
                       String encoded_password,
                       String password)

Authenticate an encoded password.

The `encoded` password string is `decoded` and then decrypted using the `private key` of the `key pair`. If the result matches all the same characters of the specified password string then authentication has succeeded.

N.B.: No exceptions are thrown; if any problem occurs the authentication fails.

Parameters:
  `keys` - The KeyPair used to decrypt the encoded password. If null false is returned.
  `encoded_password` - An `encoded` password string. If null false is returned.
  `password` - The password string to be compared against the encoded password after it has been decoded and decrypted. If null false is returned.
Returns:
  true if the decoded encoded password matches the password; false otherwise. N.B.: false will be returned if any of the arguments are null; any special rules, such as "anonymous" authenticaton when the password is null, are the responsibility of the application.

#### Encode_Hex

    public static String Encode_Hex(byte[] bytes)

Encode a byte array to a hexadecimal string representation.

Each byte in the array is represented by two characters that are the hexadecimal value of the byte ('0' padded if the value of the byte is less than or equal to 0xF). All hex characters for each byte of the array are concatenated in byte array order.

Parameters:
  `bytes` - An array of byte values. If null, null is returned.
Returns:
  A String providing the hexadecimal representation of the byte array values.
See Also:
  `Decode_Hex(String)`

#### Decode_Hex

    public static byte[] Decode_Hex(String string)

Decode a hexadecimal string to its byte array equivalent.

Each pair of characters in the string are translated into the binary value they represent and stored in a byte array in the order in which they occur in the string.

Parameters:
  `string` - A String of hexadecimal character pairs. If null, null is returned.
Returns:
  An array of bytes containing the values represented by each character pair in the string in the order they occur.
Throws:
  `NumberFormatException` - If the length of the string is odd or any character in it does not represent a hexadecimal value (0-9 and a-f, case insensitive).
See Also:
  `Encode_Hex(byte[])`