Quick Start: C++

You’re Alice and you have sensitive data to protect. (Don’t we all?)

Let’s see the fastest way to protect it server-side with the Virtru SDK.

Prerequisites

  • Compiler compatible with C++17 or newer:
    • Linux: gcc 7.40
    • macOS: XCode 11.3
    • Windows: Microsoft Visual Studio 2017
  • CMake (Linux, macOS, Windows)

1. Install the SDK

Linux

  1. Download the C++ archive for Linux.
  2. Unpack the archive.
  3. Move the unpacked folder into your project.
  4. Generate project files:
cd ./sample # from downloaded archive
cmake -G "Eclipse CDT4 - Unix Makefiles"
make # compile, link, and create an executable

macOS

  1. Download the C++ archive for macOS.
  2. Unpack the archive.
  3. Move the unpacked folder into your project.
  4. Generate project files:
cd ./sample # from downloaded archive
cmake .
make # compile, link, and create an executable

Windows

  1. Download the C++ archive for Windows.
  2. Unpack the archive.
  3. Move the unpacked folder into your project.
  4. Install Visual Studio 2017 or newer.
  5. Generate Visual Studio project files using CMake.
    Run this in the Developer PowerShell for Visual Studio:
Set-Location .\sample\
cmake -G "Visual Studio 15 2017 Win64"
  1. Open the virtru_tdf3_sensitive.sln file with Visual Studio.
  2. Select Release in configuration.
  3. Select Build > Build solution to compile, link and create an executable.

2. Get an identity

So Alice, who should own your sensitive data? You, obviously!

Authenticate to associate your email address (e.g. [email protected]) with any data you protect. You cannot protect data without authenticating. If the Virtru Platform doesn’t know who’s protecting data, no one would be able to access it later (when they’re also asked to authenticate).

The fastest way to authenticate on the server side is with an appId token. You can generate one from the Virtru Dashboard. If you need help, see detailed steps.

For safekeeping, don’t hard code your appID anywhere. A more secure option is to store it in your local environment:

export VIRTRU_SDK_EMAIL=[paste from Virtru Dashboard]
export VIRTRU_SDK_APP_ID=[paste from Virtru Dashboard]

To protect your sensitive data, we’ll need a Virtru client. We’ll associate anything you encrypt with your email and appId. Let’s make sure your email and appId can create a valid Virtru client to make further SDK calls:

#include <virtru_client.h>
#include <cstdlib>
#include <iostream>

using namespace virtru;

int main()
{
    auto email = std::getenv("VIRTRU_SDK_EMAIL");
    auto appId = std::getenv("VIRTRU_SDK_APP_ID");
    if (email == nullptr || appId == nullptr) {
        std::cerr << "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID" << std::endl;
        return EXIT_FAILURE;
    }
    Client client {email, appId};

    std::cout << "Ready to protect!" << std::endl;
    return EXIT_SUCCESS;
}

3. Ask for sensitive data

Now that we know who will own things, why don’t you enter your first piece of sensitive data? For simplicity’s sake, create a file named “sensitive.txt” with your sensitive data.

touch ./sensitive.txt
echo "sensitive data" >> ./sensitive.txt

4. Protect the sensitive data

Next, decide your encryption options. For now, it’s the file containing your sensitive data. In the future, this could include who else should have access and under what conditions.

std::string unprotectedFile = "sensitive.txt";
std::string protectedFile = unprotectedFile + ".tdf.html";
EncryptFileParams params {unprotectedFile, protectedFile};

Finally, encrypt the data:

client.encryptFile(params);

Here is the complete source code:

#include <virtru_client.h>
#include <cstdlib>
#include <iostream>

using namespace virtru;

int main()
{
    auto email = std::getenv("VIRTRU_SDK_EMAIL");
    auto appId = std::getenv("VIRTRU_SDK_APP_ID");
    if (email == nullptr || appId == nullptr) {
        std::cerr << "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID" << std::endl;
        return EXIT_FAILURE;
    }
    Client client {email, appId};

    std::string unprotectedFile = "sensitive.txt";
    std::string protectedFile = unprotectedFile + ".tdf.html";
    EncryptFileParams params {unprotectedFile, protectedFile};

    client.encryptFile(params);
    std::cout << "Encrypted file " << protectedFile << std::endl;
    return EXIT_SUCCESS;
}

5. Access the sensitive data

Now, let’s say you need to see your sensitive data again. Authenticate as [email protected] again and you can decrypt the protected file:

#include <virtru_client.h>
#include <cstdlib>
#include <iostream>

using namespace virtru;

int main()
{
    auto email = std::getenv("VIRTRU_SDK_EMAIL");
    auto appId = std::getenv("VIRTRU_SDK_APP_ID");
    if (email == nullptr || appId == nullptr) {
        std::cerr << "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID" << std::endl;
        return EXIT_FAILURE;
    }
    Client client {email, appId};

    std::string protectedFile = "sensitive.txt.tdf.html";
    std::string unprotectedFile = "sensitive_decrypted.txt";
    client.decryptFile(protectedFile, unprotectedFile);

    std::cout << "Decrypted file " << unprotectedFile << std::endl;
    return EXIT_SUCCESS;
}

The decrypted file should match your original one with the sensitive data:

diff sensitive.txt sensitive_decrypted.txt

6. Access the sensitive data anywhere

If you inspect the generated HTML file, you still won’t find your sensitive data. It stays protected. You can send that HTML file to another machine or anywhere you want. Only you will be able to access it. But how do you do that outside of this code?

We could build a whole set of functionality to authenticate, decrypt, and render files. Or we could use Virtru’s Secure Reader, which is built to do exactly that for thousands of security-conscious users every day. In fact, if you open that HTML file from the last step, it will redirect you to Secure Reader.

Secure Reader will ask you to authenticate. (You’re still Alice, aren’t you?)

Authenticating with Virtru Secure Reader

And if you authenticate with the same email address you used to create the HTML file, you should be able to view it in Secure Reader:

Decrypting with Virtru Secure Reader

Congrats Alice! Your sensitive data is safe wherever it goes.

Updated 5 months ago


Quick Start: C++


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.