# Administrative Operations

# Introduction

The Akixi Application must be correctly configured in order to receive real-time call reporting data from the telephony environment. When the initial Akixi Telephony Server component configuration is correctly performed, then the Akixi Application will be able to monitor call and/or ACD status against various device elements within the corresponding telephony environment - this in turn allows Customers to run Akixi reports and view real-time & historic call & ACD statistics.

However, it is sometimes necessary to subsequently update the Akixi Service configuration. For example, you might consider excluding irrelevant Devices/Agents from Akixi reporting or amending existing ones. Operations invoked in order to add, change, get and delete configuration elements of the Akixi Service are called Administrative Operations. These operations can be accessed via Web Services interface (by sending corresponding requests from the client-side logic) and via Web Interface (by manually signing in through your Web Browser and navigating to the Administration tab/menu option).

The full list of administrative areas that can be accessed via Web Services is listed below.

# Password Property Values

# Setting Password Values

Some Web Services API operations allow password Property values to be specified for certain Akixi Service configuration components. An example of this is when Akixi Telephony Server components are added or changed, where the telephony platform API password credentials can be provided in order that the corresponding Telephony Server component can actually successfully authenticate & communicate with the underlying telephony platform.

In order to provide a degree of obscurity for password values sent over unencrypted HTTP Web API sessions, all password values must be AES-128 ECB encrypted and then finally encoded as Base64 text values. The 128-bit encryption key used should be the first 128 bytes of the API session nonce’s text value, after UTF-8 encoding it into a sequence of bytes. The session nonce is the value returned via the CreateSession API operation, see the previous “Creating Sessions” section.

However, the use of HTTPS is strongly recommended as opposed unencrypted HTTP. Note that even when using HTTPS, password Property values must still be encrypted using AES-128 ECB.

# Reading Password Values

Almost all password Property values can never ever be subsequently read again, once values for them are set, either via the Akixi Service web user interface or from Web Services operations.

This includes telephony platform API password credentials for Telephony Server components, the passwords for Application Users, as well as the monitor passwords required for extension devices on BroadSoft M6 telephony platform environments. However, password credentials can be partially read for Call Recording Integration entries, where the password’s first & last character may be obtained in CallRecIntList and CallRecIntInfo API operations.

# Password Encryption Sequence

The entire password encryption operation can most easily be represented as the following formula:

 Base64Encode( AES128EncryptWithFinalBlockZeroPadding( TruncateOrZeroExpandTo16Bytes( UTF8Encode([Nonce]) ), UTF8Encode([Password]) ) )

Where:

Firstly, you will need to convert the session nonce text to a UTF-8 encoded byte array; then if the resultant array is longer than 128 bits (16 bytes) actually truncate it to 128 bits, or if shorter, actually extend it instead to 128 bits filling the additional added bits with zeroes.

Secondly, the new password value should be UTF-8 encoded as a sequence of bytes.

The 3rd step is to perform the actual AES-128 ECB encryption operation on the UTF-8 encoded password value using the encryption key previously derived from the first step above. The encryption routine should be sequentially run across progressive 128-bit (16 byte) blocks of the UTF-8 encoded password value. If the trailing/remaining block of the unencrypted password input value, is less than 128 bits, then the routine must perform the final block’s encryption phase by expanding the trailing block to 16 bytes and filling it with padded zeros, before generating the block’s encrypted result. Note that in Java implementations of this algorithm, we would recommend you actually use a “AES/ECB/NOPADDING” cipher (via javax.crypto.getInstance(“AES/ECB/NOPADDING”)), but apply the trailing block extension & padding in your own code by specifically creating a zeroed-out 16 octet byte array, as well as copying the trailing UTF-8 encoded password bytes to the beginning of it.

Finally, the resultant encrypted password byte array should be encoded into a Base64 text value.

All the above steps are summarised below:

Note that the AES-128 encryption assumes that the programming language implementation of the algorithm automatically includes the AES (Rijndael) Key Schedule steps that expand the original Short Key into a number of separate Round Keys. In Java, this particular set of steps is implicitly done when creating a SecretKeySpec instance, for example:

// Extract 128 bits of UTF-8 encoded nonce, which becomes the encryption key used.
//...Etc...
// Create AES ECB cipher instance.
Cipher pCipher = Cipher.getInstance("AES/ECB/NoPadding");
// Create key resource, which performs a key expansion operation in order to // generate a Key Schedule.
SecretKeySpec pKeySpec = new SecretKeySpec(pEncryptionKeyAs128Bits, "AES"); // Initialise Cipher.
pCipher.init(Cipher.ENCRYPT_MODE, pKeySpec);
// Sequentially perform encryption in 128-bit blocks, zero padding the last trailing block // if required.
//...Etc...

As a final note, it is worth mentioning that the Akixi Service decryption implementation trims all “whitespace” (any Unicode character <= 32 decimal or 0x20 hex) from the decrypted password, which implicitly handles scenarios where zero-padding was required to be added by the client-side encryption mechanism in the trailing cipher block. This therefore has an inherent limitation of not allowing any whitespace characters to be set at the beginning & end of password Property values configured via the Web Services API.

# Password Encryption Example

Values provided in the following example can be used to test your implementation of password value encryption. To test your implementation, you can generate the resultant Base64 text output for predefined sample password & nonce values. If your output is identical to the result provided in this example, it means that your procedure correctly replicates the encryption mechanism in the expected way.

1. Step: Create a test method that will include sample values from this example.

You will need to generate a multi-digest password hash within your client-side logic. Sample values that will help you to test your implementation are provided below:

2. Step: AES-128 ECB Encrypt the password value.

Please ensure that your password encryption routine matches the following pseudocode:

Base64Encode( AES128EncryptWithFinalBlockZeroPadding( TruncateOrZeroExpandTo16Bytes( UTF8Encode(“84c3c1e5b58a0039bfc8219169cbe7a6”) ), UTF8Encode(“p4S5w*rd”) ) )

3. Step: Verify the result.

If the password encryption mechanism has been implemented correctly, it must return the following Base64 text value:

VnFr/A7vdhjOsl7s/Gi2jQ==

If the final value does not match, please ensure that you have fully replicated the encryption logic, including the zero-initialised padding implementations where required for the key preparation and final trailing encryption block steps. If you are entirely sure that you have met all requirements described in this document, please e-mail support@akixi.com with details related to your particular implementation for password encryption operations. These can include code/pseudo-code fragments as appropriate, etc.

# Example Routine In Sample Code

An example password value encryption routine is provided in the sample code by static method AES128EncryptWithFinalBlockZeroPadding(), which is defined by class com.Akixi.Public.Utils.Security.CSecurity within the WSClientUtils project. To learn more about the sample code, refer to the corresponding page (“Developing Client Applications”).