Overview

The Ixia Public Core Services API uses REST over HTTPS, and hence uses HTTP error codes to indicate API errors. It also uses HTTP verbs (GET, POST, etc.) to indicate the action to be taken in a specific request. The request body of every API call is a JSON object, and the response to every API call is also a JSON object.

The JSON for each API request has the following basic structure:

Authentication

Every API call requires authentication. You authenticate to the Ixia API by submitting an encrypted SHA256 hash of the current date, and by including your pre-assigned client id.

Spec

Examples

"authentication": {
    "clientID": "MY_PREASSIGNED_CLIENT_KEY",
    "date": 1439401799,
    "dateSignature": "AAAAB3NzaC1yc2EAAAEAJ30M..."
}

To get started making API calls, you will need your pre-assigned client id (provided by Ixia), and a X.509 public/private key pair. The easiest and possibly most common way to generate a X.509 key is to use OpenSSL.

# Linux-compatible platforms
                
# Generate a new 2048-bit RSA private key and X.509 certificate (self-signed)
> openssl req -x509 -nodes -days 36500 -newkey rsa:2048 -keyout my-private-key -out my-cert

# Given the certificate, extract the public key to a separate file
> openssl x509 -in my-cert -pubkey -noout > my-public-key

# Once generated, the private and public keys will look like this:

# private key
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAwWTmnYJ3iWHdycoK8Coib1GBw1ZPClN52tRJLKa6GX8vbNDu
vVxHasItS7nF9sXNWGypFgdas6boiNQ8Zg73tom8S2seGL5zWKTewO6WEfDSbIP0
F5ioftVtY5i8DyC65CylkxKXaYuI7OZTdAC...
-----END RSA PRIVATE KEY-----

# public key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwWTmnYJ3iWHdycoK8Coi
b1GBw1ZPClN52tRJLKa6GX8vbNDuvVxHasItS7nF9sXNWGypFgdas6boiNQ8Zg73
tom8S2seGL5zWKTewO6WEfDSbIP0F5ioftV...
-----END PUBLIC KEY-----

# Note that to load the private key in Java, you must first convert it to PKCS#8 encoding
> openssl pkcs8 -topk8 -nocrypt -outform DER < my-private-key > my-private-key-pkcs8

Once generated, send your public key file to Ixia. Then use the private key to create a cryptographic signature of the date field. Writing code to generate the date and date signature is relatively straightforward. Below are code snippets in Bash and Java.

# Linux-compatible platforms
         
# Get the current date in seconds since the Epoch, and write to a file
> date +%s | awk '{printf $0}' > date.txt

# Get the signature of the date, and write to a file
> openssl sha -sha256 -binary < date.txt | openssl rsautl -inkey my-private-key -sign | openssl base64 | awk '{printf $0}' > signature.txt

# The date and date signature are now in date.txt and signature.txt respectively
import java.io.ByteArrayOutputStream;
import java.io.FileInputStream;
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
 
import javax.crypto.Cipher;
 
import org.apache.commons.codec.binary.Base64;
 
public class DateSignatureSample {
public static void main( String[] args ) throws Exception {
// get the current date as seconds since the Epoch
long dateSeconds = System.currentTimeMillis() / 1000;
String dateString = String.valueOf( dateSeconds );
 
// load the PKCS#8 version of the private key from a file
FileInputStream inputStream = new FileInputStream( "my-private-key-pkcs8" );
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
 
byte[] bytes = new byte[0xFFFF];
while( true ) {
int bytesRead = inputStream.read( bytes );
if( bytesRead == -1 ) {
break;
}
outputStream.write( bytes, 0, bytesRead );
}
outputStream.flush();
inputStream.close();
 
KeyFactory keyFactory = KeyFactory.getInstance( "RSA" );
PrivateKey privateKey = keyFactory.generatePrivate( new PKCS8EncodedKeySpec( outputStream.toByteArray() ) );
 
// get the sha-256 digest of the date
MessageDigest shaSum = MessageDigest.getInstance( "SHA-256" );
byte[] shaDigest = shaSum.digest( dateString.getBytes() );
 
// encrypt the digest
Cipher rsaCipher = Cipher.getInstance( "RSA" );
rsaCipher.init( Cipher.ENCRYPT_MODE, privateKey );
byte[] encryptedDigest = rsaCipher.doFinal( shaDigest );
 
String signatureString = new String( Base64.encodeBase64( encryptedDigest ) );
 
System.err.println( "dateString: " + dateString );
System.err.println( "signatureString: " + signatureString );
}
}

Note that the above Java code sample uses Apache Commons.

MetaData

Some API calls require meta data to be included in the request. This meta data structure is unique to each individual API call, and contains additional parameters that control how the request is processed.

Spec

Examples

"metadata": {
        ... fields related to the specific API call ...
}

Request Details

The request details contain the content of the request, and are hence unique to each individual API call.

Spec

Examples

"requestDetails": {
... fields related to the specific API call ...
}

HTTP Methods

There are two HTTP verbs that can be used to make API calls; GET and POST.

GET requests:

Spec

GET /<requestType>?query=...

# where the query cgi parameter is the base-64 form of the JSON basic request structure.

Examples

GET /salestax?query=iVBORw0KGgoAAAANSUhEUgAAAFEAAAAmCAYAAAC8qHdPAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1...

# where iVBORw0KGgoAAAANSUhEUgAAAFEAAAAmCAYAAAC8qHdPAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1 is the base-64 encoded version of the JSON request object

POST requests:

POST /<requestType>

, where the POST data of the request is the JSON basic request structure.

Copyright 2019 Ixia, Inc.