Home /Modules/advantage/keystore.h

keystore.h

advantage/transport/keystore.h · 98 line(s) · c

/*
 * keystore.h - Encrypted-at-rest secret/key store for the acquisition layer.
 *
 * Stores named secrets (passwords, API tokens, private key material, derived
 * session keys) in a single file that is encrypted with AES-256-GCM. The
 * file encryption key is derived from a passphrase with PBKDF2-HMAC-SHA-256
 * (a large, tunable iteration count). Every record is individually sealed
 * with its own nonce and authentication tag, so tampering is detected on
 * read.
 *
 * Security properties:
 *   - Confidentiality + integrity at rest (AES-256-GCM, per-record nonce/tag).
 *   - Passphrase never stored; only the PBKDF2 salt and parameters are.
 *   - Atomic, idempotent writes: the store is serialized to a temp file and
 *     rename(2)'d into place, so a crash never leaves a half-written store.
 *   - Secret buffers are zeroed before being freed.
 *
 * This is a thin, auditable wrapper over OpenSSL's EVP interfaces; it does
 * not invent cryptography.
 */
#ifndef ADVANTAGE_KEYSTORE_H
#define ADVANTAGE_KEYSTORE_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct ks_store ks_store;

typedef enum {
    KS_OK = 0,
    KS_ERR_IO = -1,       /* file open/read/write/rename failed            */
    KS_ERR_CRYPTO = -2,   /* OpenSSL primitive failed                      */
    KS_ERR_AUTH = -3,     /* wrong passphrase or tampered data (GCM fail)  */
    KS_ERR_FORMAT = -4,   /* corrupt or unrecognized store format          */
    KS_ERR_NOTFOUND = -5, /* no record with the requested name             */
    KS_ERR_ARG = -6,      /* invalid argument                              */
    KS_ERR_NOMEM = -7     /* allocation failed                             */
} ks_status;

/*
 * Open (or create, if absent) a keystore backed by `path`, unlocked with
 * `passphrase`. If the file exists it is decrypted and verified; a wrong
 * passphrase or tampering yields KS_ERR_AUTH. On success *out receives an
 * owned handle that must be released with ks_close().
 */
ks_status ks_open(const char *path, const char *passphrase, ks_store **out);

/*
 * Store (or replace) the secret named `name`. Idempotent: storing the same
 * name+value twice leaves the store in the same logical state. The change is
 * persisted atomically before returning KS_OK.
 */
ks_status ks_put(ks_store *ks, const char *name,
                 const uint8_t *value, size_t value_len);

/* Convenience for NUL-terminated string secrets. */
ks_status ks_put_str(ks_store *ks, const char *name, const char *value);

/*
 * Fetch the secret named `name`. On success *out_value is a freshly
 * allocated buffer (owned by the caller; free with ks_free_secret) and
 * *out_len its length. Returns KS_ERR_NOTFOUND if absent.
 */
ks_status ks_get(ks_store *ks, const char *name,
                 uint8_t **out_value, size_t *out_len);

/* Remove the named secret. Idempotent: removing an absent name is KS_OK. */
ks_status ks_remove(ks_store *ks, const char *name);

/* Number of records currently held. */
size_t ks_count(const ks_store *ks);

/*
 * List record names into caller-provided array `names` (each NUL-terminated,
 * caller frees each with free()). Writes up to `max` names; returns the count
 * written, or a negative ks_status on error.
 */
int ks_list(const ks_store *ks, char **names, size_t max);

/* Securely wipe and free a secret returned by ks_get. */
void ks_free_secret(uint8_t *value, size_t len);

/* Flush any pending state and release the handle. */
void ks_close(ks_store *ks);

/* Human-readable message for a status code. */
const char *ks_strerror(ks_status st);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* ADVANTAGE_KEYSTORE_H */