The Ubiq Security dotnet (.NET) library provides convenient interaction with the Ubiq Security Platform API from applications written in the C# language for .NET. It includes a pre-defined set of classes that will provide simple interfaces to encrypt and decrypt data.

See the .NET API docs.

• .NET Framework (4.6.2 or newer) desktop development
• .NET Core (6.0 or newer) cross-platform development

Using the .NET Core command-line interface (CLI) tools:

dotnet add package ubiq-security

Using the NuGet Command Line Interface (CLI):

nuget install ubiq-security

Using the Package Manager Console:

Install-Package ubiq-security

From within the cloned local git repository folder, use Visual Studio to open the solution file:

ubiq-dotnet.sln

    dotnet build -c Release

• Visual Studio 2022 or newer
• In the Visual Studio Installer, make sure the following items are checked in the Workloads category:
  • .NET desktop development
  • .NET Core cross-platform development

Within the Solution Explorer pane, right-click the UbiqSecurity project, then select Set as Startup Project.

From the Build menu, execute Rebuild Solution to compile all projects.

See the reference sample applications.

Make sure your project has a reference to the UbiqSecurity DLL library, either by adding the NuGet package (if using prebuilt library) or by adding a project reference (if built from source). Then, add the following to the top of your C# source file:

using UbiqSecurity;

You can use the CryptographyBuilder to configure and build the ubiq objects that will be used to perform encrypt/decrpt operations.

using var structuredEncryptDecrypt = CryptographyBuilder.Create().BuildStructured();

// or

using var unstructuredEncrypt = CryptographyBuilder.Create().BuildUnstructuredEncrypt()

// or 

using var unstructuredDecrypt = CryptographyBuilder.Create().BuildUnstructuredDecrypt()

The library needs to be configured with your account credentials which is available in your Ubiq Dashboard. The credentials can be set using environment variables, loaded from an explicitly specified file, or loaded from a file in your Windows user account directory [c:/users/yourlogin/.ubiq/credentials].

If you do not explicitly specify credentials when using the CryptographyBuilder, an attempt will be made to load credentials from the default file location (c:/users/*yourlogin*/.ubiq/credentials) using the default profile name (default)

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentialsFromDefaultFileLocation("some-profile")
                                        .BuildStructured();

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentialsFromFile("path-to-credential-file", "some-profile")
                                        .BuildStructured();

Set the following environment variables:

• UBIQ_ACCESS_KEY_ID
• UBIQ_SECRET_SIGNING_KEY
• UBIQ_SECRET_CRYPTO_ACCESS_KEY

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentialsFromEnvironmentVariables()
                                        .BuildStructured();

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentials(creds => 
                                        {
                                            creds.AccessKeyId = "...";
                                            creds.SecretSigningKey = "...";
                                            creds.SecretCryptoAccessKey = "...";
                                        })
                                        .BuildStructured();

If a configuration is not explicitly set, default values will used.

For all configuration options, see Configuration File Format

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithConfigFromFile("path-to-config-json-file")
                                        .BuildStructured();

Ubiq currently supports both Okta and Entra IDP integration. Instead of using the credentials provided when creating the API Key, the username (email) and password will be used to authenticate with the IDP and provide access to the Ubiq platform.

Use the following environment variables to set the credential values

• IDP_USERNAME
• IDP_PASSWORD

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentialsFromEnvironmentVariables()
                                        .BuildStructured();

using var structuredEncryptDecrypt = CryptographyBuilder
                                        .Create()
                                        .WithCredentials(creds => 
                                        {
                                            creds.IdpUsername = idpUsername;
                                            creds.IdpPassword = idpPassword;
                                        })
                                        .BuildStructured();

Unsuccessful requests raise exceptions. The exception object will contain the error details.

Some users have experienced "hangs" during encryption and decryption operations. So far, this has been solved by adding .ConfigureAwait(false) to those calls as in:

await UbiqEncrypt.EncryptAsync(credentials, plainBytes).ConfigureAwait(false);

More information can be found about C# SynchronizationContext can be found here.

Pass credentials and plaintext bytes into the unstructured encryption function. The encrypted data bytes will be returned.

Note: This is a non-blocking function, so be sure to use the appropriate process controls to make sure the results are available when desired. See the the following Microsoft documentation for additional information.

using UbiqSecurity;

using var unstructuredEncrypt = CryptographyBuilder
                                    .Create()
                                    .BuildUnstructuredEncrypt();

byte[] plainBytes = ...;
byte[] encryptedBytes = await unstructuredEncrypt.EncryptAsync(plainBytes);

Pass credentials and encrypted data into the unstructured decryption function. The plaintext data bytes will be returned.

Note: This is a non-blocking function, so be sure to use the appropriate process controls to make sure the results are available when desired. See the the following Microsoft documentation for additional information.

using UbiqSecurity;

using var unstructuredDecrypt = CryptographyBuilder
                                    .Create()
                                    .BuildUnstructuredDecrypt();

byte[] encryptedBytes = ...;
byte[] plainBytes = await unstructuredDecrypt.DecryptAsync(encryptedBytes);

• Create an unstructured encryption object using the credentials.
• Call the encryption instance BeginAsync() method.
• Call the encryption instance Update() method repeatedly until all the data is processed.
• Call the encryption instance End() method.

Below is the working code from the test application in the reference source:

using UbiqSecurity;

using var ubiqEncrypt = CryptographyBuilder
                                .Create()
                                .BuildUnstructuredEncrypt();

using var plainStream = new FileStream(inFile, FileMode.Open);

using var cipherStream = new FileStream(outFile, FileMode.Create);

// start the encryption
var cipherBytes = await ubiqEncrypt.BeginAsync();
cipherStream.Write(cipherBytes, 0, cipherBytes.Length);

// process 128KB at a time
var plainBytes = new byte[0x20000];

// loop until the end of the input file is reached
int bytesRead = 0;
while ((bytesRead = plainStream.Read(plainBytes, 0, plainBytes.Length)) > 0)
{
    cipherBytes = ubiqEncrypt.Update(plainBytes, 0, bytesRead);
    cipherStream.Write(cipherBytes, 0, cipherBytes.Length);
}

// finish the encryption
cipherBytes = ubiqEncrypt.End();
cipherStream.Write(cipherBytes, 0, cipherBytes.Length);

In this example, the same data encryption key is used to encrypt several different plain text objects, object1 .. objectn. In each case, a different initialization vector, IV, is automatically used but the ubiq platform is not called to obtain a new data encryption key, resulting in better throughput. For data security reasons, you should limit n to be less than 2^32 (4,294,967,296) for each unique data encryption key.

1. Create an encryption object using the credentials.

2. Repeat following three steps as many times as appropriate

   • Call the encryption instance begin method
   • Call the encryption instance update method repeatedly until a single object's data is processed
   • Call the encryption instance end method

3. Call the encryption instance close method

    using UbiqSecurity;

    using var ubiqEncrypt = CryptographyBuilder
                                    .Create()
                                    .BuildUnstructuredEncrypt(1);

    List<Byte> cipherBytes = new List<Byte>();
    // object1 is a full unencrypted object
    byte[] tmp = await ubiqEncrypt.BeginAsync();
    cipherBytes.AddRange(tmp);
    tmp = ubiqEncrypt.Update(object1, 0, object1.length);
    cipherBytes.AddRange(tmp);
    tmp = ubiqEncrypt.End();
    cipherBytes.AddRange(tmp);
    // Do something with the encrypted data: cipherBytes

    // In this case, object2 is broken into two pieces, object2_part1 and object2_part2
    cipherBytes = new List<Byte>();
    tmp = await ubiqEncrypt.BeginAsync();
    cipherBytes.AddRange(Bytes.asList(tmp))
    tmp = ubiqEncrypt.update(object2_part1, 0, object2_part1.length);
    cipherBytes.AddRange(Bytes.asList(tmp))
    tmp = ubiqEncrypt.Update(object2_part2, 0, object2_part2.length);
    cipherBytes.AddRange(tmp);
    tmp = ubiqEncrypt.End();
    cipherBytes.AddRange(tmp);
    // Do something with the encrypted data: cipherBytes

    // In this case, objectb is broken into two pieces, object2_part1 and object2_part2
    cipherBytes = new List<Byte>();
    // objectn is a full unencrypted object
    tmp = await ubiqEncrypt.BeginAsync();
    cipherBytes.AddRange(tmp);
    tmp = ubiqEncrypt.Update(objectn, 0, objectn.length);
    cipherBytes.AddRange(tmp);
    tmp = ubiqEncrypt.End();
    cipherBytes.AddRange(tmp);
    // Do something with the encrypted data: cipherBytes
}

• Create a unstructured decryption object using the credentials.
• Call the decryption instance Begin() method.
• Call the decryption instance UpdateAsync() method repeatedly until all data is processed.
• Call the decryption instance End() method

Below is the working code from the test application in the reference source:

    using var ubiqDecrypt = CryptographyBuilder
                                    .Create()
                                    .BuildUnstructuredDecrypt();

    using var cipherStream = new FileStream(inFile, FileMode.Open);

    using var plainStream = new FileStream(outFile, FileMode.Create);

    // start the decryption
    var plainBytes = ubiqDecrypt.Begin();
    plainStream.Write(plainBytes, 0, plainBytes.Length);

    // process 128KB at a time
    var cipherBytes = new byte[0x20000];

    // loop until the end of the input file is reached
    int bytesRead = 0;
    while ((bytesRead = cipherStream.Read(cipherBytes, 0, cipherBytes.Length)) > 0)
    {
        plainBytes = await ubiqDecrypt.UpdateAsync(cipherBytes, 0, bytesRead);
        plainStream.Write(plainBytes, 0, plainBytes.Length);
    }

    // finish the decryption
    plainBytes = ubiqDecrypt.End();
    plainStream.Write(plainBytes, 0, plainBytes.Length);

The structured encryption functions work with the credentials file and/or environmental variables in the same way as described earlier in this document. You'll only need to make sure that the API keys you pull from the Ubiq dashboard are are associated with a structured dataset.

Create an Encryption / Decryption object with the credentials and then allow repeatedly call encrypt data using a structured dataset and the data. The encrypted data will be returned after each call.

Note that you would only need to create the "ubiqEncryptDecrypt" object once for any number of EncryptAsync and DecryptAsync calls, for example when you are bulk processing many such encrypt / decrypt operations in a session.

    using var ubiqEncryptDecrypt = CryptographyBuilder
                                                .Create()
                                                .BuildStructured();

    var cipherText = await ubiqEncryptDecrypt.EncryptAsync(FfsName, plainText);

    Console.WriteLine($"ENCRYPTED cipherText= {cipherText}\n");

Create an Encryption / Decryption object with the credentials and then repeatedly decrypt data using a structured dataset and the data. The decrypted data will be returned after each call.

Note that you would only need to create the "ubiqEncryptDecrypt" object once for any number of EncryptAsync and DecryptAsync calls, for example when you are bulk processing many such encrypt / decrypt operations in a session.

    using var ubiqEncryptDecrypt = CryptographyBuilder
                                                .Create()
                                                .BuildStructured();
    
    var plainText = await ubiqEncryptDecrypt.DecryptAsync(FfsName, cipherText);
    
    Console.WriteLine($"DECRYPTED plainText= {plainText}\n");

There are cases where a developer would like to attach metadata to usage information reported by the application. Both the structured and unstructured interfaces allow user_defined metadata to be sent with the usage information reported by the libraries.

The AddReportingUserDefinedMetadata function accepts a string in JSON format that will be stored in the database with the usage records. The string must be less than 1024 characters and be a valid JSON format. The string must include both the { and } symbols. The supplied value will be used until the object goes out of scope. Due to asynchronous processing, changing the value may be immediately reflected in subsequent usage. If immediate changes to the values are required, it would be safer to create a new encrypt / decrypt object and call the AddReportingUserDefinedMetadata function with the new values.

Examples are shown below.

    using var ubiqEncryptDecrypt = CryptographyBuilder
                                                .Create()
                                                .BuildStructured();

    ubiqEncryptDecrypt.AddReportingUserDefinedMetadata("{\"some_meaningful_flag\" : true }");
}

    using var ubiqEncrypt = CryptographyBuilder
                                    .Create()
                                    .BuildUnstructuredEncrypt(1);

    ubiqEncrypt.AddReportingUserDefinedMetadata("{\"some_key\" : \"some_value\" }");

For example say we want to search for an employee by SSN, but that field was encrypted in the database. The encryption key may have rotated since the employee SSN was originally encrypted, so we can use the EncryptForSearchAsync() method to get an array of all possible encrypted values.

using var ubiqEncryptDecrypt = CryptographyBuilder
                                                .Create()
                                                .BuildStructured();

var encryptedSsns = await ubiqEncryptDecrypt.EncryptForSearchAsync("SSN_Dataset", unencryptedSsn)

var user = _dbContext
                .Employees
                .Where(x => encryptedSsns.Contains(x.EncryptedSSN))
                .FirstOrDefault();

A sample configuration file is shown below. The configuration is in JSON format. The event_reporting section contains values to control how often the usage is reported.

• wake_interval indicates the number of seconds to sleep before waking to determine if there has been enough activity to report usage

• minimum_count indicates the minimum number of usage records that must be queued up before sending the usage

• flush_interval indicates the sleep interval before all usage will be flushed to server.

• trap_exceptions indicates whether exceptions encountered while reporting usage will be trapped and ignored or if it will become an error that gets reported to the application

• timestamp_granularity indicates the how granular the timestamp will be when reporting events. Valid values are

  • "NANOS"
    // DEFAULT: values are reported down to the nanosecond resolution when possible
  • "MILLIS"
    // values are reported to the millisecond
  • "SECONDS"
    // values are reported to the second
  • "MINUTES"
    // values are reported to minute
  • "HOURS"
    // values are reported to hour
  • "HALF_DAYS"
    // values are reported to half day
  • "DAYS"
    // values are reported to the day

  Key Caching

  The key_caching section contains values to control how and when keys are cached.

  • ttl_seconds indicates how many seconds a cache element should remain before it must be re-retrieved. (default: 1800)
  • structured indicates whether keys will be cached when doing structured encryption and decryption. (default: true)
  • unstructured indicates whether keys will be cached when doing unstructured decryption. (default: true)
  • encrypt indicates if keys should be stored encrypted. If keys are encrypted, they will be harder to access via memory, but require them to be decrypted with each use. (default: false)

  IDP specific parameters

  • provider indicates the IDP provider, either okta, entra, or ubiq
  • ubiq_customer_id The UUID for this customer. Will be provided by Ubiq.
  • idp_token_endpoint_url The endpoint needed to authenticate the user credentials, provided by Okta or Entra
  • idp_tenant_id contains the tenant value provided by Okta or Entra
  • idp_client_secret contains the client secret value provided by Okta or Entra

{
  "event_reporting": {
    "wake_interval": 1,
    "minimum_count": 2,
    "flush_interval": 2,
    "trap_exceptions": false,
    "timestamp_granularity" : "NANOS"
  },
  "key_caching" : {
     "structured" : true,
     "unstructured" : true,
     "encrypted" : false,
     "ttl_seconds" : 1800
  },
   "idp": {
    "provider": "okta",
    "ubiq_customer_id": "f6f.....08c5",
    "idp_token_endpoint_url": " https://dev-<domain>.okta.com/oauth2/v1/token",
    "idp_tenant_id": "0o....d7",
    "idp_client_secret": "yro.....2Db"
  }
}

Occasionally, you may encounter issues when interacting with the Ubiq API.