CETAN Documentation

Safe (secrets)

Safe is a robust C++‑based system for securely managing sensitive data—commonly referred to as secrets. It provides both a command‑line interface (CLI) for direct user interaction and a comprehensive C++ API for programmatic integration. Safe enables secure storage, retrieval, and lifecycle management of secrets within applications and systems, eliminating hardcoded credentials and insecure storage practices.

Core concepts

• Secret — a sensitive value such as a password, API key, token, or private key.
• Safe file — an encrypted .safe vault storing secrets at rest.
• Entry — a name/value pair stored inside a Safe file.

Typical usage

• Create a Safe file for your environment.
• Add entries for TLS passphrases, LDAP admin passwords, API keys, and other secrets.
• Reference Safe entries from cetan_config.xml to avoid storing secrets in plain text.
• Use the Safe API or CLI to retrieve or manage secrets securely.

Safe C++ API (SDK)

The Safe C++ API provides programmatic access to encrypted Safe files. Applications can create safes, add entries, retrieve values, and manage passwords without exposing secrets in plain text. All functionality is provided through the ctn::Safe class.

Class overview

namespace ctn {
  class Safe {
  public:
    Safe();
    Safe(const string& name, const string& key);
    bool exists(const string& name);
    inline const char* version() const;
    int create_safe(string& error);    
    int get_entry(Entry& e, string& error);
    int add_entry(const Entry& e, string& error);
    int remove_entry(const string& entry_name, string& error);
    int list_entries(vector<string>& names, string& error);
    int add_entry_from_file(const string& name,
                            const string& file,
                            string& error);
    int change_key(const string& name,
                   const string& current_key,
                   const string& new_key,
                   string& error);
  };
}

All methods returning int follow a standard convention: 0 = success, -1 = error. Error details are returned through the error reference parameter.

Constructors

Default constructor

Safe safe;

Creates an empty Safe instance. This form is used exclusively for change_key() operations.

Constructor with file + key

Safe safe("cetan", "password");

• name — Safe filename (adds .safe if missing).
• key — password protecting the Safe file.

Core API methods

Create Safe

int create_safe(string& error);

Add entry

int add_entry(const Entry& e, string& error);

Add entry from file

int add_entry_from_file(const string& name,
                        const string& file,
                        string& error);

List entries

int list_entries(vector<string>& names, string& error);

Get entry

int get_entry(Entry& e, string& error);

Remove entry

int remove_entry(const string& entry_name, string& error);

Verify key

bool key_verified(string& error);

Change Safe password

int change_key(const string& name,
               const string& current_key,
               const string& new_key,
               string& error);

Examples

Create a Safe

  #include "Safe.h"
  #include <string>
  #include <iostream>

  using namespace ctn;
  using namespace std;

  int main() {
    string error;
    Safe safe("cetan", "password");

    if(safe.create_safe(error) == -1)
      cout << "Could not create safe: " << error << "\n";
    else
      cout << "A new safe created\n";
  }

Add entry

  #include "Safe.h"
  #include "Entry.h"

  Entry e("entry_name", "entry value");
  safe.add_entry(e, error);

List entries

  vector<string> names;
  safe.list_entries(names, error);

Retrieve entry

  Entry e("entry_name");
  safe.get_entry(e, error);
  cout << e.value();

Remove entry

safe.remove_entry("entry_name", error);

Change Safe password

  Safe safe;
  safe.change_key("cetan.safe", "oldpass", "newpass", error);

Safe Command Line Interface (CLI)

Introduction

Safe Utilities is a standalone command‑line tool for secure management of secrets. It supports both interactive and non‑interactive modes, making it suitable for scripting, automation, and secure deployment workflows.

Installation

• Download the latest cetan-safe-tool-x.y.z.tar.gz.
• Extract the archive to any directory.
• Run the safe executable from that location.

Core concepts

• Secrets — API keys, passwords, private keys, and other sensitive values.
• Vault — the encrypted .safe file storing secrets at rest.

General usage

./safe COMMAND [OPTIONS] <ARG>...

Commands

Create Safe

./safe create --name safe-name --pass safe-password

Add entry

./safe add --name safe-name --pass safe-password --entry entry-name --value entry-value

Add entry from file

./safe add --name safe-name --pass safe-password --entry entry-name --infile filename

List entries

./safe list --name safe-name --pass safe-password

Get entry

./safe get --name safe-name --pass safe-password --entry entry-name
 ./safe get ... --out hex|HEX|base64
 ./safe get ... --outfile filename

Delete entry

./safe delete --name safe-name --pass safe-password --entry entry-name

Change Safe password

./safe change-password --name safe-name --pass safe-password --newpass new-password

Verify Safe password

./safe verify-password --name safe-name --pass safe-password

Generate salt

./safe gen-salt --length salt-length --out hex|HEX|base64

Generate password

./safe gen-password --length password-length

Compute HMAC

./safe compute-hmac --msg message --b64-salt salt --hash-algo algo --key password --out outform

Supported hash algorithms include SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, and SHA3-512.