Proposal: SecureStore Class for Cross-Platform Secure Storage in U++

[ismail-yilmaz]

Motivation

Many modern applications need to store passwords or OAuth tokens securely across platforms. Currently, there's no unified API in U++ to interact with the system’s native secure credential stores, leaving developers to roll their own implementations — which is error-prone and potentially insecure.

This proposal introduces a SecretStorage class that:

• Provides simple, secure APIs for storing, retrieving, and deleting secrets.

• Works across Linux, Windows, and macOS using platform-native facilities.

• Supports both simple string passwords and larger binary blobs (e.g. OAuth tokens, serialized settings), up to ~4KB.

---

Design Plan

Class Name

class SecureStore;

Platforms & Backends

Linux: libsecret

Windows: Credential Manager API

macOS: Keychain Services

These are all stable, system-supported facilities designed for secure storage.

---

Capabilities

For simple secrets (like passwords)

bool StorePassword(const String& key, const String& password);
String LoadPassword(const String& key);
bool DeletePassword(const String& key);

For larger blobs (up to ~4 KB)

bool StoreBlob(const String& key, const String& blob);
String LoadBlob(const String& key);
bool DeleteBlob(const String& key);

Note: Internally, StoreBlob() may compress or serialize input to ensure it fits platform limits. All blob inputs are treated as opaque data; caller is responsible for structure/encoding.

For error management

String GetErorDesc() const;

Service name (or path)

String service = "org.Upp.SecretStorage"

---

Platform Notes

• Linux:

  • Uses libsecret (via D-Bus and GNOME Keyring or KDE KWallet).

  • Requires libsecret and glib as runtime dependencies.

• Windows:

  • Uses CredWrite, CredRead, and CredDelete (Credential Manager).

  • Data is stored securely per-user.

• macOS:

  • Uses SecItemAdd, SecItemCopyMatching, and SecItemDelete.

  • Stored in the user’s Keychain, with optional UI prompts.

---

Scope Limitations

This is a minimalist and secure-by-default utility. It will:

• Not support schema definitions (as in full libsecret)

• Not support multiple user profiles, UI prompts, or third-party vaults

• Not expose raw credential handles or advanced platform-specific settings

---

Security Traits

• Always prefer system-managed storage for security and persistence.

• Avoid reinventing crypto: rely on what the platform provides.

• Secrets will never be stored in plaintext files or memory beyond necessary scope.

• All backends (Credential Manager, Keychain, libsecret) store data encrypted at rest.

Current Status

• Linux prototype: done, working.
• Windows: prototype done, working
• MacOS: NEEDS HELP (I don't have MacOS access now, so it should probably be implemented by a co-author)

[mirek-fidler]

Sounds good...

[ismail-yilmaz]

Ok, I have uploaded the prototype here
You can clone, test and review it. It includes a basic autotest.

Notes:

• On Linux it requires libsecret. This is a gtk library but unfortunately there is no better/neutral alternative on linux. Since U++ requires Gtk (glib-2 etc.), this little library shouldn't be a big problem. It uses pkgconfig, so the setup is pretty straight-forward.
• ATM, works on Linux and Windows. No MacOS support (yet).
• Includes an API doc.

[klugier]

What about putting it to the new package Core/SecreteStorage. Then libsecret won't be hard requirements and it will only be needed when application will need to use secrete storage. For example at the moment TheIDE don't need it, so this requirement will be overhead if we implement it within the Core. Alternativly, we can put it on UppHub if we do not want this as a part of the framework.

Also, we should discuss how we should name it. SecureStorage is a one option. But, we definitely have alternatives. SecreteManager, KeychainManager etc. For the package name Core/SecreteStorage we might use something with one world instead of two. Core/SecreteSotrage is long if you compare it to packages like Core/SSL. Maybe Core/Secretes?

Moreover, I found in your code that GetPathName() is not configurable. IMO, This is mistake and it should be confugrable per class. Thanks to that consumers will be able to use soemthing diffrent than "org.Upp.SecretStorag". BTW, Our domain is org.ultimatepp and I am using it for Flatpak. Some time ago I checked if upp.org is something we can register and unfortunettly it is not available.

For platform, I think it shouldn't be Linux. For example Android is Linux and it is uses diffrent mechanisms for storing secretes. Also, your implemention should work on FreeBSD, too. So, I think it could depend on GTK flag (GUI_GTK?).

[ismail-yilmaz]

What about putting it to the new package Core/SecreteStorage.

My intention is to put it in Core/SecretStorage If rejected I can of course put it on UppHub. But I think in this day and age, a credential manager, however minimal, should be a core part of any framework. Speaking of credentials,

Also, we should discuss how we should name it. SecureStorage is a one option. But, we definitely have alternatives. SecreteManager, KeychainManager etc.

Sure, Core/Credentials might be even better. I chose "secret" because we already have ReadSecret() function for reading sensitive information on console. class name can be CredentialManager

Moreover, I found in your code that GetPathName() is not configurable.

Good point. I'll make it virtual instead of static, so that it can be easily configurable. And I'll change the path to org.ultimatepp.[final-classname]

or platform, I think it shouldn't be Linux. For example Android is Linux and it is uses diffrent mechanisms for storing secretes. Also, your implemention should work on FreeBSD, too. So, I think it could depend on GTK flag (GUI_GTK?).

AFAIK GUI_GTK requires it to be GUI app. But SecretStorage should be available for console apps too. How about if we just dynamically link to libsecret on Linux and add an IsAvailable() method that'll check the availability of the library (.so)? On other supported platforms this method will always return true.

[klugier]

Good point. I'll make it virtual instead of static, so that it can be easily configurable. And I'll change the path to org.ultimatepp.[final-classname]

This is definitely better, but to change it, you will need to override the class. I think passing this value as parameter is easier and do not require defining new class.

AFAIK GUI_GTK requires it to be GUI app. But SecretStorage should be available for console apps too. How about if we just dynamically link to libsecret on Linux and add an IsAvailable() method that'll check the availability of the library (.so)? On other supported platforms this method will always return true.

I would stay with IFDEF's. They are better than checking this kind of information on runtime. I think is POSIX and not MACOS and not ANDROID should work as expected.

[ismail-yilmaz]

This is definitely better, but to change it, you will need to override the class. I think passing this value as parameter is easier and do not require defining new class.

But client-code is already able to do that. Key parameter can be any string. They can just prepend the path to their actual key.

Defining it as a virtual method in this specific case seems more elegant to me. For example, you can define several different credential manager paths along with your derived classes (UppCredentials, BobcatCredentials, MyOrgsCredentials`) and store them in the same container (Index, Array, Vector), access them through the same interface. This isn't technically a better solution than your suggestion of course, but I think it allows a better semantic differentiation. Moreover this class isn't a performance-critical component, i.e. having virtual methods won't hurt performance.

I would stay with IFDEF's. They are better than checking this kind of information on runtime. I think is POSIX and not MACOS and not ANDROID should work as expected.

I'm not against IFDEFS, but GUI_GTK is far too restrictive. As I noted above, the package should be available to pure console applications too.

[klugier]

But client-code is already able to do that. Key parameter can be any string. They can just prepend the path to their actual key.

Defining it as a virtual method in this specific case seems more elegant to me. For example, you can define several different credential manager paths along with your derived classes (UppCredentials, BobcatCredentials, MyOrgsCredentials`) and store them in the same container (Index, Array, Vector), access them through the same interface. This isn't technically a better solution than your suggestion of course, but I think it allows a better semantic differentiation. Moreover this class isn't a performance-critical component, i.e. having virtual methods won't hurt performance.

Thanks! Makes sense to me. We should document it wisely. At least noticed that it is recommended for each lab to override this method and use own instance of the class. Also, the example should also override the instance of the manager. Not a fan of making this method pure virtual, but it should be somehow indicated that default store should not be used in real world scenarios.

I'm not against IFDEFS, but GUI_GTK is far too restrictive. As I noted above, the package should be available to pure console applications too.

I agreee, GUI_GTK is too wide. As, I said using POSIX and then negatic MAC_OS and ANDROID should work as expected.

[ismail-yilmaz]

I decided to take this matter into my own hands and have proposed AES-256-GCM encryption/decryption support for U++ (#266).

In short, if this proposal is accepted:

• U++ will gain a very secure, password/passphrase-based modern encryption/decryption facility with minimal maintenance requirements.
• It will likely eliminate the need for platform-specific implementations of keyrings.
• It will enable the development of a fully-fledged, cross-platform keyring that can be built separately and included in UppHub.

At that point, we could build a cross-platform keyring using AES-256 and SQLite.

[Trilec]

How about SecureStore , short, CamelCase, and immediately convey ‘put secrets safely.’ , reads naturally alongside Core/SSL, Core/DB, etc.

[klugier]

@ismail-yilmaz do we want to change the name SecureStorage sounds batter to me too. Also Trilec is from New Zeland, so I assume he feels English better than us :) And, we still can rename it since it is not part of any release.

[ismail-yilmaz]

Yep, SecureStore sounds lot better. I'm working on an updated version (both src, and this description), with all the securexxx stufff :)

[Trilec]

well mate, when you hear the accents here you would wonder..lol