Skip to main content

MTE Fixed Length Add-On Code Examples

Purpose​

The objective of an MTE fixed length "Examples" is to provide short examples of how to use the MTE fixed length Encoder and MTE Decoder.

The Fixed Length Add-On is a replacement for the core encoder that ensures all messages are encoded to a fixed length. If the input is too long, it will be truncated to the fixed length. If the input is shorter than the fixed length, random padding bytes will be added to the end of the input to the fixed length size. See code decoder samples for decoding examples.

The Fixed length add-on must be used if using the sequencing verifier with MTE and wish to decode asynchronously or recover from missing MTE packets. For more information, please see the official MTE developer guides.

MTE Fixed Length (FLEN) Encoder​

Create MTE FLEN Encoder​

The MTE FLEN Encoder will be created using default options. The default options will set preferred security options recommended by Eclypses. Custom options should only be used in special circumstances and after reading and understanding how to select the best options for a given situation. More information about how to select these options can be found in the official MTE Developer Guides.

Create Default Encoder

// The fixed length each MTE packet will be equal.
// To avoid data loss this number must be larger
// than any anticipated input data.
int fixedBytes = 20;

// Create MTE Core Encoder with defaults
MteFlenEnc flenEncoder = new MteFlenEnc(fixedBytes);

// Need entropy, nonce and personalization string
// *** IMPORTANT NOTE ***
// Entropy is critical to security and should be created and
// handled like encryption keys. To permit decoding of encoded
// value, Encoder and Decoder must use identical Entropy, Nonce and
// Personalization String as well as Options . See Developer Guides for more information.
//-----------------------------------------------------------------
// The following personalization string and nonce values are for
// demonstration only and should not be used in a production environment
string personalizationString = "MySecretPersonalizationStringGoesHere";
long nonce = 12345678;

// Check how long of entropy we need.
// This example fills entropy with at string of zeros
// this should NOT be used in a production environment
int entropyMinBytes = flenEncoder.GetDrbgsEntropyMinBytes(flenEncoder.GetDrbg());
string entropy = (entropyMinBytes > 0)
    ? new String('0', entropyMinBytes)
    : string.Empty;

// Set Encoder entropy and nonce
flenEncoder.SetEntropy(Encoding.UTF8.GetBytes(entropy));
flenEncoder.SetNonce(nonce);

// Initialize MTE Encoder
MteStatus encoderStatus = flenEncoder.Instantiate(personalizationString);
if(encoderStatus !=MteStatus.mte_status_success)
{
    // MTE cannot continue so handle failure appropriately
    // Below is an Example
    throw new ApplicationException($"Failed to initialize the MTE Encoder engine." +
     $"Status: {flenEncoder.GetStatusName(encoderStatus)} / " +
     $"{flenEncoder.GetStatusDescription(encoderStatus)}");
}

Encoding to a base64 string or byte[]​

Use the following methods to encode a string or a byte[]. The samples below display all the options that can be used to encode, only one method needs to be used to encode the data. The developer should select the method that works with the type of data that is used.

// Fixed length must be at least as long as the largest expected input size.
// Padding will be added to the input if necessary so they are always the same size.

// Example values to be encoded.
string inputString = "What I want to be encoded goes here";
byte[] bytesToBeEncoded = Encoding.ASCII.GetBytes(inputString);

// Create MteStatus variable.
MteStatus encoderStatus;

// Below are 4 different examples of how to encode.
// ONLY ONE needs to be used.
// Encode byte[] to a base64 string
string encodedBytesAsString = flenEncoder.EncodeB64(bytesToBeEncoded, out encoderStatus);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Handle encode failure appropriately
    // Below is only an example
    throw new Exception("Failed to encode. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}
// Encode string to a base64 string
string encodedStringAsString = flenEncoder.EncodeB64(inputString, out encoderStatus);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Handle encode failure appropriately
    // Below is only an example
    throw new Exception("Failed to encode. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}
// Encode byte[] to a byte[]
byte[] encodedBytesAsBytes = flenEncoder.Encode(bytesToBeEncoded, out encoderStatus);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Handle encode failure appropriately
    // Below is only an example
    throw new Exception("Failed to encode. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}
// Encode string to a byte[]
byte[] encodedStringAsBytes = flenEncoder.Encode(inputString, out encoderStatus);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Handle encode failure appropriately
    // Below is only an example
    throw new Exception("Failed to encode. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}

FLEN Encoder State​

The FLEN encoder state can be saved and restored with either byte[] or a base64 string using the following methods. Below are several examples of how to use it, based on your data type you only need to use one of the following examples.

// Save and restore Encoder state with bytes
// Get byte[] of Encoder state
byte[] encoderByteState = flenEncoder.SaveState();

// Restore Encoder with byte[] state
MteStatus encoderStatus = flenEncoder.RestoreState(encoderByteState);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Mte cannot continue, handle restore failure appropriately
    // Below is only an example
    throw new Exception("Failed to restore Encoder state. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}
// Save and restore Encoder state with string
// Get string of Encoder state
string encoderStrState = flenEncoder.SaveStateB64();

// Restore Encoder with string state
MteStatus encoderStatus = flenEncoder.RestoreStateB64(encoderStrState);
if(encoderStatus != MteStatus.mte_status_success)
{
    // Mte cannot continue, handle restore failure appropriately
    // Below is only an example
    throw new Exception("Failed to restore Encoder state. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}

Uninstantiate Encoder​

Uninstantiate encoder, this will zeroize the DRBG state and returns the status.

// Uninstantiate the Encoder
MteStatus encoderStatus = flenEncoder.Uninstantiate();
if(encoderStatus != MteStatus.mte_status_success)
{
    // MTE was not uninstantiated as desired so handle failure appropriately
    // Below is only an example
    throw new Exception("Failed to uninstantiate Encoder. Status: "
        + flenEncoder.GetStatusName(encoderStatus)+ " / "
        + flenEncoder.GetStatusDescription(encoderStatus));
}