encoder-create

C

/* Create the encoder. */
MTE_HANDLE encoder;
mte_enc_init_info e_info = MTE_ENC_INIT_INFO_INIT(
    MTE_DRBG_ENUM, MTE_TOKBYTES, MTE_VERIFIERS_ENUM,
    MTE_CIPHER_ENUM, MTE_HASH_ENUM, NULL, NULL, NULL, NULL, NULL, NULL);
mte_enc_args e_args = MTE_ENC_ARGS_INIT(NULL, 0, NULL, &t_cb, NULL);
encoder = MTE_ALLOCA(mte_enc_state_bytes(&e_info));
status = mte_enc_state_init(encoder, &e_info);
if (status != mte_status_success)
{
    fprintf(stderr, "Encoder init error (%s): %s\n",
        mte_base_status_name(status),
        mte_base_status_description(status));
    return status;
}
status = mte_enc_instantiate(encoder, &i_info);
if (status != mte_status_success)
{
    fprintf(stderr, "Encoder instantiate error (%s): %s\n",
        mte_base_status_name(status),
        mte_base_status_description(status));
    return status;
}

The entropy and nonce callbacks.

static mte_status ei_cb(void* context, mte_drbg_ei_info* info)
{
    MTE_SIZE_T input_bytes;
    (void)context;

    /* Get the entropy. */
    printf("Enter %u-%lu bytes of entropy> ",
        (unsigned)info->min_length,
        (unsigned long)info->max_length);
    fflush(stdout);
    (void)!fgets(ei_buff, sizeof(ei_buff), stdin);
    input_bytes = (MTE_SIZE_T)(strlen(ei_buff) - 1);

    /* If the entropy is less than the minimum required, we must return an
       error. */
    if (input_bytes < info->min_length)
    {
        return mte_status_drbg_catastrophic;
    }
    else if (input_bytes > info->bytes)
    {
        /* If the entropy is longer than the provided buffer, point at our buffer
           instead. */
        info->buff = (MTE_UINT8_T*)ei_buff;
    }
    else
    {
        /* Otherwise copy the entropy to the provided buffer. */
        memcpy(info->buff, ei_buff, input_bytes);
    }

    /* Set the actual entropy length. */
    info->bytes = input_bytes;

    /* We got it successfully. */
    return mte_status_success;
}

static void n_cb(void* context, mte_drbg_nonce_info* info)
{
    MTE_SIZE8_T i;
    MTE_UINT64_T u64;
    char line[80];
    (void)context;

    /* Get the nonce. */
    printf("Enter the nonce (decimal digits only)> ");
    fflush(stdout);
    (void)!fgets(line, sizeof(line), stdin);
    u64 = strtoul(line, NULL, 10);

    /* Copy the nonce in little-endian format to the nonce buffer. */
    for (i = 0; i < info->max_length && i < sizeof(u64); ++i)
    {
        info->buff[i] = (MTE_UINT8_T)(u64 >> (i * 8));
    }

    /* If the minimum length is greater than the size of the nonce we got, fill
       up to that length with zeros. */
    for (; i < info->min_length; ++i)
    {
        info->buff[i] = 0;
    }

    /* Set the actual nonce length. */
    info->bytes = i;
}

C++

// Create the encoder.
MteEnc encoder;
encoder.setEntropyCallback(&cbs);
encoder.setNonceCallback(&cbs);
encoder.setTimestampCallback(&cbs);
status = encoder.instantiate(personal);
if (status != mte_status_success)
{
    std::cerr << "Encoder instantiate error ("
        << MteBase::getStatusName(status)
        << "): "
        << MteBase::getStatusDescription(status)
        << std::endl;
    return status;
}

The entropy and nonce callbacks.

mte_status Cbs::entropyCallback(mte_drbg_ei_info& info)
{
  // Display a prompt.
  std::cout << "Enter "
            << static_cast<size_t>(info.min_length) << '-' << info.max_length
            << " bytes of entropy> " << std::flush;

  // Get a line of input.
  std::string line;
  std::cin >> line;

  // If the input was less than the minimum required, we must return an error.
  if (line.size() < info.min_length)
  {
    return mte_status_drbg_catastrophic;
  }

  // Set the actual entropy length. It cannot exceed the maximum required.
  size_t buffBytes = info.bytes;
  info.bytes = std::min(static_cast<MTE_SIZE_T>(line.size()), info.max_length);

  // If the length is greater than the length of the provided buffer, we have
  // to create our own buffer instead.
  if (info.bytes > buffBytes)
  {
    delete [] myEntropy;
    myEntropy = new uint8_t[info.bytes];
    info.buff = myEntropy;
  }

  // Copy the entropy to the buffer and we got it successfully.
  memcpy(info.buff, line.data(), info.bytes);
  return mte_status_success;
}

void Cbs::nonceCallback(mte_drbg_nonce_info& info)
{
  // Display a prompt.
  std::cout << "Enter the nonce (decimal digits only)> " << std::flush;

  // Get the nonce and ignore the rest of the line.
  MTE_UINT64_T u64;
  std::cin >> u64;
  std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');

  // Copy the nonce in little-endian format to the nonce buffer.
  size_t i;
  for (i = 0; i < info.max_length && i < sizeof(u64); ++i)
  {
    info.buff[i] = static_cast<MTE_UINT8_T>(u64 >> (i * 8));
  }

  // If the minimum length is greater than the size of the nonce we got, fill
  // up to that length with zeros.
  for (; i < info.min_length; ++i)
  {
    info.buff[i] = 0;
  }

  // Set the actual nonce length.
  info.bytes = static_cast<MTE_SIZE8_T>(i);
}

CSharp

// Create MTE Core Encoder with defaults
MteEnc mteEncoder = new MteEnc();

// Need entropy, nonce and personalization string
// These values should be unique and entropy must be treated like encryption keys!
// 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;

// *** 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.

// 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 = mteEncoder.GetDrbgsEntropyMinBytes(mteEncoder.GetDrbg());
string entropy = (entropyMinBytes > 0)
    ? new String('0', entropyMinBytes)
    : string.Empty;

// Set encoder entropy and nonce
mteEncoder.SetEntropy(Encoding.UTF8.GetBytes(entropy));
mteEncoder.SetNonce(nonce);

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

Java

// Create the MTE encoder
MteEnc mteEncoder = new MteEnc();

// Need entropy, nonce and personalization string
// These values should be unique and entropy must be treated like encryption keys!
// 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;

// *** 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.

// 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 = MteBase.getDrbgsEntropyMinBytes(mteEncoder.getDrbg());
String entropy = "0";
entropy = entropy.repeat(entropyMinBytes);

// Set encoder entropy and nonce
mteEncoder.setEntropy(entropy.getBytes());
mteEncoder.setNonce(nonce);

// Initialize MTE encoder
MteStatus encoderStatus = mteEncoder.instantiate(personalizationString.getBytes());
if (encoderStatus != MteStatus.mte_status_success)
{
    // MTE cannot continue so handle failure appropriately
    // Below is just an example
    throw new Exception("Failed to initialize the MTE encoder engine. Status: "
          + MteBase.getStatusName(encoderStatus)+ " / "
          + MteBase.getStatusDescription(encoderStatus));
}

JavaScript

import { MteEnc } from "mte-wasm-browser";

// Note: mteWasm must already be declared and instantiated

// assign module variable to be an encoder
const mteEncoder = MteEnc.fromdefault(mteWasm);

// set encoder entropy
// see Best Practice guides for generating secure entropy values
mteEncoder.setEntropyStr("SecretEntropyStringHere");
// set encoder nonce
mteEncoder.setNonce(12345678);
// instantiate using personalization token
const encoderStatus = mteEncoder.instantiate("SecretPersonalizationStringHere");

// check instantiation was successful
if (encoderStatus !== MteStatus.mte_status_success) {
  const status = mteBase.getStatusName(encoderStatus);
  const message = mteBase.getStatusDescription(encoderStatus);
  throw new Error(`Error instantiating MTE Encoder.\n${status}: ${message}`);
}

Swift

// Create the encoder.
let encoder = try! MteEnc()
encoder.setEntropyCallback(cbs)
encoder.setNonceCallback(cbs)
encoder.setTimestampCallback(cbs)
status = encoder.instantiate(personal)
if status != mte_status_success {
  print("Encoder instantiate error (\(MteBase.getStatusName(status))): " +
        MteBase.getStatusDescription(status))
  return Int32(status.rawValue)
}

The entropy and nonce callbacks.

class Cbs: MteEntropyCallback, MteNonceCallback, MteTimestampCallback {
  func entropyCallback(_ minEntropy: Int,
                  _ minLength: Int,
                  _ maxLength: UInt64,
                  _ entropyInput: inout [UInt8],
                  _ eiBytes: inout UInt64,
                  _ entropyLong: inout UnsafeMutableRawPointer?) -> mte_status {
    // Display a prompt.
    print("Enter \(minLength)-\(maxLength) bytes of entropy> ", terminator: "")

    // Get a line of input.
    let line = readLine()!

    // If the input was less than the minimum required, we must return an error.
    if line.utf8.count < minLength {
      return mte_status_drbg_catastrophic
    }

    // Set the actual entropy length. It cannot exceed the maximum required.
    let buffBytes = eiBytes
    eiBytes = min(UInt64(line.utf8.count), maxLength)

    // If the length is greater than the length of the provided buffer, we have
    // to create our own buffer instead.
    if eiBytes > buffBytes {
      // Get the entropy input as an array.
      let ei = [UInt8](line.utf8)

      // If there is previous raw entropy, deallocate it.
      if myEntropyRaw != nil {
        myEntropyRaw!.deallocate()
      }

      // Allocate unsafe memory for the entropy.
      myEntropyRaw =
        UnsafeMutableRawPointer.allocate(byteCount: ei.count, alignment: 16)

      // Copy from the entropy array to the unsafe memory.
      ei.withUnsafeBytes { buff in
        let raw = myEntropyRaw!.assumingMemoryBound(to: UInt8.self)
        let ei = buff.bindMemory(to: UInt8.self)
        raw.assign(from: ei.baseAddress!, count: ei.count)
      }

      // Set the raw pointer to point at the unsafe memory.
      entropyLong = myEntropyRaw
    }
    else {
      // Copy the entropy to the buffer.
      entropyInput.replaceSubrange(Range(uncheckedBounds: (0, Int(eiBytes))),
                                   with: line.utf8.prefix(Int(eiBytes)))
    }

    // Success.
    return mte_status_success
  }
  func nonceCallback(_ minLength: Int,
                     _ maxLength: Int,
                     _ nonce: inout [UInt8],
                     _ nBytes: inout Int) {
    // Display a prompt.
    print("Enter the nonce (decimal digits only)> ", terminator: "")

    // Get the nonce and ignore the rest of the line.
    let u64 = UInt64(readLine()!)!

    // Copy the nonce in little-endian format to the nonce buffer.
    let nCopied = min(nonce.count, MemoryLayout.size(ofValue: u64))
    for i in 0..<nCopied {
      nonce[i] = UInt8(UInt64(u64 >> (i * 8)) & 0xFF)
    }

    // If the minimum length is greater than the size of the nonce we got, fill
    // up to that length with zeros.
    if nCopied < minLength {
      for i in nCopied..<minLength {
        nonce[i] = 0
      }
      nBytes = minLength
    }
    else {
      nBytes = nCopied
    }
  }

Python

# Create MTE Core Encoder with defaults.
mte_encoder = MteEnc.fromdefault()

# 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.
personalization_string = "MySecretPersonalizationStringGoesHere"
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.
entropy_min_bytes = MteBase.get_drbgs_entropy_min_bytes(mte_encoder.get_drbg())
entropy = bytes("0" * entropy_min_bytes, 'utf-8')

# Set encoder entropy and nonce.
mte_encoder.set_entropy(entropy)
mte_encoder.set_nonce(nonce)

# Initialize MTE encoder.
encoder_status = mte_encoder.instantiate(personalization_string)
if encoder_status != MteStatus.mte_status_success:
    # MTE cannot continue so handle failure appropriately.
    # Below is an Example.
    raise Exception("Failed to initialize the MTE encoder engine. Status: {0} / {1}\n".format(MteBase.get_status_name(encoder_status),
    MteBase.get_status_description(encoder_status)))

Go

// Create Encoder with default options
// In practice,  you will create an encoder this way, create a custom encoder,
// or create MKE or FLEN encoder. See developer guide for more information
mteEncoder := mte.NewEncDef()
defer mteEncoder.Destroy()

// Need entropy, nonce and personalization string.
// These values should be unique and treated like encryption keys!
// The following personalization string and nonce values are for demonstration purposes
// and should NOT be used in production environments
personalizationString := "MySecretPersonalizationStringGoesHere"
nonce := 12345678

// Create all-zero entropy for this demo. The nonce will also be set to 0.
// This should never be done in real applications.
entropyBytes := mte.GetDrbgsEntropyMinBytes(mteEncoder.GetDrbg())
entropy := make([]byte, entropyBytes)

// Set entropy and nonce
mteEncoder.SetEntropy(entropy)
mteEncoder.SetNonceInt(nonce)

// Instantiate the encoder.
encoderStatus := mteEncoder.InstantiateStr(personalizationString)
if encoderStatus != mte.Status_mte_status_success {
    // Handle an error here -- below is a sample
    fmt.Fprintf(os.Stderr, "Encoder instantiate error (%v): %v\n",
      mte.GetStatusName(encoderStatus), mte.GetStatusDescription(encoderStatus))
    return int(encoderStatus)
}

PHP

<?php
// Create Encoder with default options
// In practice,  you will create an encoder this way, create a custom encoder,
// or create MKE or FLEN encoder. See developer guide for more information
$mteEncoder = new mteEnc();

// Need entropy, nonce and personalization string.
// These values should be unique and treated like encryption keys!
// The following personalization string and nonce values are for demonstration purposes
// and should NOT be used in production environments
$personalizationString = "MySecretPersonalizationStringGoesHere";
$nonce = 12345678;

// Create all-zero entropy for this demo. The nonce will also be set to 0.
// This should never be done in real applications.
$entropyBytes = $mteEncoder->getDrbgEntropyMinBytes(constant($mteEncoder->getDrbg()));
$entropy = "";
$entropy = str_pad($entropy, $entropyBytes);

// Set entropy and nonce
$mteEncoder->setEntropy($entropy);
$mteEncoder->setNonce($nonce);

// Instantiate the Encoder.
$encoded = $mteEncoder->instantiate($personalizationString);
if (constant($encoded["status"])==mte_status_success) {
    // Handle an error here -- below is a sample
    echo "Encoder instantiate error: ".$mteEncoder->getStatusName(constant($encoded["status"])).":"
                                      .$mteEncoder->getStatusDescription(constant($encoded["status"]));
    return $mteEncoder->getStatusCode(constant($encoded["status"]));
}
?>