HCVault.Core 1.4.0

HCVault

A library for creating, opening and editing VeraCrypt-compatible encrypted container files — no driver, no mounting, no admin rights.

English | 简体中文

If you need VeraCrypt volumes inside your own application — an encrypted document store, a mobile vault app, a backup tool — this library does the volume work directly: create containers, open them with password / keyfiles / PIM, and read or write the decrypted contents at the sector or file level. Containers made here open in the official VeraCrypt application, and the other way round.

The volume core is the actual VeraCrypt source (1.26.29), vendored and patched only where portability required it. The cryptography is untouched. It is exposed through a small C API (vcapi.h, 35 functions) and a .NET 8 / .NET 10 wrapper on top of that.

 your app (C#, C/C++, or anything with an FFI)
        │                │
        │ P/Invoke       │ C ABI (vcapi.h)
        ▼                ▼
 HCVault.Core      hcvault-core
 (.NET wrapper)    (VeraCrypt core + FatFs, CMake)

Status and disclaimer

This is an independent project. It is not affiliated with, endorsed by, or in any way connected to IDRIX or the VeraCrypt project. "VeraCrypt" is their trademark; the VeraCrypt License forbids derivative names, which is why this project is called HCVault (after the .hc container extension). See THIRD-PARTY-NOTICES.md.

The code and documentation of this project were produced with AI assistance and have not been security-audited. The cryptographic core is inherited from VeraCrypt, but the integration around it is new and unreviewed. Read what you ship, keep backups of your data, and do not trust either this library or any encryption software with irreplaceable files as the only copy.

Security

Is a volume created here as secure as one created by the official application? For the container itself, yes: it is the same volume format, produced by the same source code — the header layout, cipher cascades, KDFs, XTS mode, self-tests and RNG design are all literally VeraCrypt's. This is not a reimplementation.

What differs is everything around the container:

• This project has no independent audit. VeraCrypt has been audited; the glue code here (the C API, the .NET wrapper, the build packaging) has not been reviewed by anyone.
• Quick mode (the default) does not wipe the data area before formatting — same as official VeraCrypt's quick mode. Pass full format if you need the wipe.
• On the .NET side, SecurePassword is pinned and wiped on disposal, but ordinary file buffers (byte[]) handed to the API live in managed memory and are not zeroed afterwards.
• Smartcard / security-token keyfiles are not supported (the PKCS#11 chain was removed; file keyfiles work as usual). TrueCrypt-mode volumes are not supported either.
• As with all software encryption, a compromised host defeats everything.

What it can and cannot do

It can:

• create normal and hidden file-hosted volumes (200 KiB minimum), with any cipher / KDF / keyfile / PIM combination
• open volumes from current and legacy (V1 layout) VeraCrypt releases, including reading through the embedded backup header when the primary one is damaged
• read and write the decrypted data area at sector level, or through the built-in FAT driver / bundled exFAT (FatFs R0.15) — list, read, write, mkdir, delete, and query total / free space
• rotate a volume's password, KDF and keyfiles by re-encrypting only the header
• run on Android down to API 21 inside your own app

It cannot:

• mount volumes, show drive letters, or encrypt system disks / full drives (that needs kernel drivers, deliberately out of scope)
• act as a replacement for the VeraCrypt application — it is a library for building your own tools

Compatibility

Quick start

C#:

dotnet add package HCVault.Core     # the wrapper
dotnet add package HCVault.Native   # prebuilt native libraries (all platforms)
                                    # build your app with a RuntimeIdentifier

using HCVault.Core;

// create a container with an exFAT filesystem inside
using (var pw = SecurePassword.FromText("correct horse battery staple"))
{
    Volume.Create(new VolumeCreationOptions
    {
        Path = "demo.hc", SizeBytes = 64 * 1024 * 1024,
        Password = pw, Cipher = VcCipher.Aes, Kdf = VcKdf.Argon2id,
        Filesystem = VcFilesystem.ExFat,
    });
}

// open it and work with files inside
using (var pw = SecurePassword.FromText("correct horse battery staple"))
using (var vol = Volume.Open(new VolumeOpenOptions { Path = "demo.hc", Password = pw }))
using (var fs = VolumeFilesystem.Mount(vol))      // FAT or exFAT, auto-detected
{
    fs.WriteFile("\\notes.txt", "hello, encryption"u8.ToArray());
    foreach (var e in fs.ListDirectory("\\"))
        Console.WriteLine($"{e.Name}  {e.SizeBytes} B");
}

C:

#include "vcapi.h"

vc_init();
vc_create_volume("demo.hc", 64ULL << 20, "pw", 2, NULL, 0,
                 "AES", "Argon2", "FAT", 0, 1, 0, NULL, NULL);
vc_volume *v = vc_open_volume("demo.hc", "pw", 2, NULL, 0, 0, 0, 0);
uint8_t sector[512];
vc_read_sectors(v, sector, 0, sizeof sector);   /* decrypted first sector */
vc_close_volume(v);

Full API documentation for both layers: docs/API.md (中文).

Building

Prerequisites: .NET 10 SDK (the class library also targets .NET 8 — the test suite runs one pass per installed runtime), CMake ≥ 3.15, a C++ toolchain. Android also needs NDK r26/r27; the MAUI demo needs the maui-android workload.

.\build.ps1                              # native (host arch) + managed + tests + WPF demo
.\build.ps1 -Arch All                   # native x64 + x86 + ARM64
.\build.ps1 -Android                    # all 4 Android ABIs
.\build.ps1 -Arch All -Android -Pack    # everything + both NuGet packages

./build.sh                               # native linux-x64 + managed + tests
./build.sh --android                     # all 4 Android ABIs
./build.sh --all --pack                  # everything + both NuGet packages

The scripts find CMake, the NDK and Ninja on their own (and can fetch a portable Ninja — -NoDownload / VCN_NO_DOWNLOAD=1 disables that). CI builds the demo apps and the NuGet package on every push: .github/workflows/build-demos.yml.

Android demo APKs: a plain build produces the default package (arm64-v8a + x86_64); dotnet publish -c Release -r android-arm64 (also -arm/-x64/ -x86) builds a single-ABI APK for smaller downloads.

Repository layout

License

Apache-2.0 — see LICENSE. The vendored components keep their own licenses (VeraCrypt: Apache-2.0 / TrueCrypt-3.0 dual; FatFs: BSD-style; Argon2: CC0), listed in THIRD-PARTY-NOTICES.md. Release history: CHANGELOG.md.