Repository navigation
Releases
haskoki v0.5.0.0
Haskoki 0.5.0.0 — first public release
Haskoki is a PKCS#11 software token written in Haskell, with OpenSSL doing
the cryptography. Use it to learn PKCS#11 and to test clients, with
disposable keys rather than real secrets.
Start here
docker run --rm --network none ghcr.io/mingulov/haskoki-demo:v0.5.0.0Expect demo-ok: 8/8 verifications hold. No checkout, build or hardware is
needed. The hands-on guide
shows how to keep the output, generate a key with pkcs11-tool and sign a
message.
What's new
- Keys are protected by default. New private and secret keys cannot be
read back unless you allow it when you create them, and sensitive values
are never returned or matched by searches. - Keys are used only as intended. Deriving is off unless you enable it,
CKA_ALLOWED_MECHANISMSnow also applies to derive, wrap, unwrap and
KEM, keys of the wrong type or class are refused, and wrong-length
signatures are rejected. - New storage format. Stores move to schema 3, with a one-time
migration that writes a verified backup. - Tested with real clients. OpenSC
pkcs11-tool, GnuTLS, Java
(SunPKCS11) and OpenSSL pass 61 of 61 journeys with the installed bundle
and 28 of 28 in the demo image. - Fixes, among them a hang with several GHC RTS capabilities, a crash
risk when closing a session during a native async call, DH secrets that
lost a leading zero byte, and stale store locks. - Tracing is off by default.
Upgrading from 0.4
- Run
haskoki-ctl store migrateonce per store;haskoki-ctl store check
tells you what a store needs. Older binaries cannot open a migrated store,
so keep the backup if you may go back. See
Upgrading a v0.4 token store. - New keys are unextractable and have
CKA_DERIVE=falseunless the
template says otherwise. - Token serials are now 16 hex digits; update saved
pkcs11:URIs that use
serial=. - Some error codes are more precise, and non-ASCII token labels and PINs are
refused. The changelog
lists every change.
Known limitations
- Key values read back as DER (SPKI or PKCS#8) rather than the raw PKCS#11
encoding; DSA and DH public keys read back as rawy. CKM_RSA_PKCSencryption is not offered; useCKM_RSA_PKCS_OAEP.- When Haskoki starts the GHC runtime itself, it uses one capability and
ignoresGHCRTS. - 91 of 104 PKCS#11 3.2 functions and 316 of 464 catalogued mechanisms are
served; the rest refuse with explicit error codes. See
coverage. - Token storage is not encrypted.
- Linux amd64 only. The full checker profile reports 21 documented findings
(results);
no conformance or certification is claimed.
Downloads
The release has the Linux bundle, the source archive, test logs,
release-manifest.json and SHA256SUMS. Check downloads with
sha256sum -c SHA256SUMS. This release is not signed. Published on
October 19, 2026 from source 091a222.
haskoki v0.4.0.0
Haskoki 0.4.0.0 — provisioned tokens
This release makes tokens provisionable in-band. Haskoki remains a Haskell
PKCS#11 software token for learning and integration tests; use disposable
keys, not production secrets.
Start here
docker run --rm --network none ghcr.io/mingulov/haskoki-demo:v0.4.0.0Expect demo-ok: 8/8 verifications hold. No checkout, local build, or
hardware is required. Files are disposable unless you mount /out.
The hands-on guide
shows how to keep them, generate a key with pkcs11-tool, and sign a message.
Improvements
C_InitToken,C_InitPIN, andC_SetPINwork end to end: the default
slot-0 token (haskoki-demo, SO PIN5678) can be reinitialized and
given fresh user PINs, durably across restarts; other slots can also
be relabeled (slot 0 keeps itshaskoki-demolabel).- Re-initialization is authorized: the caller PIN must match the existing
SO PIN, otherwise the call is refused (CKR_PIN_INCORRECT) and the
token's objects, jobs, credentials and counters are unchanged. This is
about token state: opening a persistent store can first commit a schema
migration even when the open is then refused (see limitations). - A logout oracle and executable reference cover session teardown, and
login-reopen plus provisioning-guard journeys extend consumer coverage. - New guides: the supported-hosts matrix and operations notes; the
publishing, hands-on, and results guides are refreshed for this release.
Correctness repairs in this release
- SQLite write transactions stop at the first failed statement group. A
failure after SQLite has rolled a transaction back can no longer be
followed by a later group committing independently while the caller is
told nothing committed. - Commit and cleanup failures are classified from the native transaction
state. A failedROLLBACK, or aCOMMITerror whose outcome cannot be
established, returns an unknown-outcome result and quarantines the
affected tokens (or the whole connection while a transaction may still be
open) instead of reporting "not committed". A mismatch while verifying an
ambiguous commit is likewise unknown, not "absent". Quarantine is
process-local to the live store handle. No production trigger for an
unknownCOMMIThas been demonstrated; the paths were exercised through
test-only SQLite hooks. - Key derivation validates the destination object before publication: the
key type must be a served symmetric type (or data) and the length must fit
that type, otherwiseCKR_TEMPLATE_INCONSISTENT. A request past the
mechanism's own output ceiling still returnsCKR_KEY_SIZE_RANGEfirst.
PKCS#11 length defaults are applied for the hash (MD5, SHA-1, SHA-2,
SHA-3 and BLAKE2B), concatenation and XOR derivations (for example DES3
defaults to 24 bytes; an untyped SHA-256 derive yields a 32-byte generic
secret). For hash derivation an explicitCKK_GENERIC_SECRETwithout a
length now failsCKR_TEMPLATE_INCOMPLETE; BLAKE2B used to give it the
digest width. - A multi-output derivation that mixes valid and invalid destinations
publishes nothing. This was already so; it is now pinned by the public
regressiontests/c/consumer_derive_atomic.c(SQLite store closed and
reopened) andKeyManagementSpec. - SP 800-108 additional-key templates decode like the primary template: a
badly shaped value failsCKR_TEMPLATE_INCONSISTENT(a shortCK_ULONG
was accepted before), an unknown attribute type
CKR_ATTRIBUTE_TYPE_INVALID, aCK_ULONGlarger than a platform integer
CKR_KEY_SIZE_RANGE, and a byte value over 4 MiB
CKR_TEMPLATE_INCONSISTENT(these wereCKR_ARGUMENTS_BAD). A new
total packed-size limit failsCKR_ARGUMENTS_BAD.CKA_EC_PARAMSOIDs
are mapped to a curve name as for primary-created objects. The whole
request creates nothing. - Test oracles only (no product change): the native DSA domain-parameter
check no longer demands a 128-byte generator and is length-aware with a
shorter-generator fixture; DH short-public and padding-tamper checks are
deterministic; a native matrix exercises per-use context-specific
authentication for marked keys through the public C interface.
Client-visible behavior changes
Storage:
- A statement failure after SQLite has already rolled back the transaction
no longer lets later write groups commit independently while the caller
is told "not committed" (this could durably clear a user PIN). - A
COMMITerror after the transaction ended is an unknown outcome and
the store reconciles: if the write landed the call returnsCKR_OK; if
not,CKR_GENERAL_ERRORand the affected token is quarantined until
C_Finalize. While quarantined its writes, including login-counter
writes, fail withCKR_GENERAL_ERROR. - A
ROLLBACKfailure is no longer discarded. If the transaction still
ended, affected tokens are quarantined; if it stays open, the whole
connection is quarantined andC_Login,C_InitToken/C_InitPIN/
C_SetPIN, token-object creation, derive and job reservation fail with
CKR_GENERAL_ERRORuntilC_Finalizeand a freshC_Initialize. COMMITreturningSQLITE_BUSYis unchanged (a clean "not committed"),
now pinned by a test. No on-disk format change; quarantine is
process-local.
C_DeriveKey:
- A length that does not fit the destination key type now fails
CKR_TEMPLATE_INCONSISTENTin every shared derive family (it used to
succeed): AES not 16/24/32, DES3 not 24, ChaCha20 not 32, HOTP outside
16-64, RC4 outside 1-256, other served types outside their sizes, and
TLS/SSL3 key-material outputs. - Asymmetric, unserved or vendor key types on a secret-key destination fail
CKR_TEMPLATE_INCONSISTENT. A request past the mechanism's maximum
output still fails first withCKR_KEY_SIZE_RANGE. - Hash derivation (MD5, SHA-1/2/3) with no type and no length now succeeds
with a generic secret of digest width (it wasCKR_TEMPLATE_INCOMPLETE). - Fixed-length key types with no length take their defined length on hash
derivation, concatenate and XOR; if the mechanism cannot produce that
many bytes the result isCKR_KEY_SIZE_RANGE, and types without a single
defined length (AES, HMAC) giveCKR_TEMPLATE_INCOMPLETE. - BLAKE2B with explicit
CKK_GENERIC_SECRETand no length now fails
CKR_TEMPLATE_INCOMPLETE(it used to give the digest width). - SP 800-108 additional-key template error codes changed as described
above.
Known limitations and v0.5 deferrals
This is a bounded release. These items are not claimed and are planned for
v0.5 or later.
- Qualification not executed. The 25-cell behavioral native matrix, the
private-RTS runs (-N1/-N2/-N4) and targeted sanitizer qualification
were not run. HPC module reconciliation gaps remain. The installed
independent client portfolio (OpenSC, GnuTLS, Java) and a
matching-certificate application journey are TO-QUALIFY, not qualified. - Identity and credentials. The public token serial is derived from the
slot index, not the stable token identity. The configuration file remains
the credential authority until a token is first provisioned; durable
seeding of new stores is v0.5. - Upgrade and refusal. A rejected persistent open can first commit the
schema-1 to schema-2 migration, so there is no no-write-on-refusal
guarantee; back up the database before upgrading. An upgrade rehearsal,
and a preflight/migrate command, are v0.5. - Scenario runner.
haskoki-ctl scenario runaccepts operational fields
it does not consume (token, mechanism, key, data, capacity, polled
function), and a wrong-PIN login bypasses expectation handling.
scenario-okdescribes the logical simulation only. - Configured versus effective policy. Reserved configuration knobs
parse and are reported but are not enforced limits. See the
configuration reference. - Proxy coverage (issue #17). Policy coverage through pkcs11-proxy-ng is
direct-only. - Transaction outcome (issue #18). No production trigger for an unknown
COMMIThas been demonstrated, and quarantine is process-local. - Derivation. Unequal-length XOR derivation is restricted. Pre-existing
inconsistencies remain for generic-secret defaults: explicit generic
concatenation/XOR without a length, typed defaults for extract, HKDF,
SP 800-108, PBKDF2, ECDH and SHAKE, DES3 key generation producing 16 bytes
while derive and unwrap use 24, and no DES parity adjustment.
Contents and limits
The Linux amd64 image carries the tool set recorded in the
dependency inventory.
Other architectures and Docker Desktop paths are unqualified. The C
library version reported by C_GetInfo is now {0, 4}.
The mechanism inventory and documented full-checker findings still apply.
The p11-kit example covers basic operations, not a full PKCS#11 3.x remoting
matrix. Token storage is unencrypted. See
results
and host limits.
Downloads
Release assets include the native Linux bundle, source archive, test logs,
release-manifest.json, and SHA256SUMS. The manifest records the exact
source and image digest. SHA256SUMS.asc is included only if the owner
configures release signing; do not assume it exists. After downloading the
archives and manifest alongside the checksums, run sha256sum -c SHA256SUMS.
The publishing guide
explains the GitHub-only build and publication workflow. A source branch
preparing this version does not mean its release or image has been publ...
haskoki v0.3.1.0
Haskoki 0.3.1.0 — easier to try
This release focuses on the first demo experience. Haskoki remains a Haskell
PKCS#11 software token for learning and integration tests; use disposable
keys, not production secrets.
Start here
docker run --rm --network none ghcr.io/mingulov/haskoki-demo:v0.3.1.0Expect demo-ok: 8/8 verifications hold. No checkout, local build, or
hardware is required. Files are disposable unless you mount /out.
The hands-on guide
shows how to keep them, generate a key with pkcs11-tool, and sign a message.
Improvements
- A shorter README explains the project and crypto vocabulary before the
implementation details. The creation story explains Haskell, the related
tools, and the dated AI-usage measurements. - The image works without an output mount.
shellprepares a token store,
puts tools onPATH, and exposesHASKOKI_MODULEandHASKOKI_CONFIG. proxy-demoruns the existing pkcs11-proxy-ng example directly.p11-kit-demodemonstrates the alternative p11-kit server/client route
over a local Unix socket, including signature, digest, tamper-rejection,
and disconnected-server checks. It needs no proxy-ng service.- The GitHub demo contracts exercise these beginner paths on the same image
used by the other checks, without external network access and under an
arbitrary numeric UID. Build logs record the image size and identity.
Contents and limits
The Linux amd64 image includes the Haskoki runtime, OpenSSL, OpenSC,
pkcs11-check 0.2.3, pkcs11-proxy-ng v0.2.2, p11-kit, and examples.
Compilers are separate; optional vector collections are downloaded only
when requested. Other architectures and Docker Desktop paths are unqualified.
The mechanism inventory and documented full-checker findings still apply.
The p11-kit example covers basic operations, not a full PKCS#11 3.x remoting
matrix. Token storage is unencrypted. See
results
and host limits.
Downloads
Release assets include the native Linux bundle, source archive, test logs,
release-manifest.json, and SHA256SUMS. The manifest records the exact
source and image digest. SHA256SUMS.asc is included only if the owner
configures release signing; do not assume it exists. After downloading the
archives and manifest alongside the checksums, run sha256sum -c SHA256SUMS.
The publishing guide
explains the GitHub-only build and publication workflow. A source branch
preparing this version does not mean its release or image has been published.
haskoki v0.3.0.0
Haskoki 0.3.0.0 - first public release (draft notes)
Draft for tag
v0.3.0.0. Pre-publish: reading this file does
not mean the tag, the release, or the image exists yet.
Purpose
Haskoki is a Haskell PKCS#11 soft token (demonstrator) covering
APIs 2.40, 3.0, 3.1 and 3.2: real in-process crypto over
OpenSSL with honest refusals for the genuinely unsupported
calls. Not a certified HSM; no production-security claim.
Artifacts
| Asset | Contents |
|---|---|
haskoki-0.3.0.0-linux-x86_64.tar.gz |
Bundle tree: libhaskoki.so, haskoki-ctl, bundled closure, licenses, smoke |
haskoki-0.3.0.0.tar.gz |
Verified source distribution (unpacked + built + tested outside the checkout) |
test-results-0.3.0.0.tar.gz |
Staged gate-evidence logs (Haskell suites, fast lane, demo-image runs) |
release-manifest.json |
Source SHA, versions, build env, artifact hashes, tool pins |
SHA256SUMS |
Checksums of the three archives and manifest |
SHA256SUMS.asc |
Detached GPG signature of the checksum file |
ghcr.io/mingulov/haskoki-demo:v0.3.0.0 |
Demo image (bundle + pinned proxy + external checker + entrypoint). Digest recorded in the release evidence; latest is a convenience pointer only, never the verified identifier. |
Before publication, the owner must provide the public verification key
location and full fingerprint here; see the release checklist.
After importing that trusted key, verify gpg --verify SHA256SUMS.asc SHA256SUMS, then sha256sum -c SHA256SUMS (four OK results). Compare
the image repository digest with release-manifest.json.
Quick start
Prerequisites: Docker alone (the image pulls from GHCR on
first run; no checkout or local build needed). Then:
mkdir -p out
docker run --rm --network none --user "$(id -u):$(id -g)" -v "$PWD/out:/out" \
ghcr.io/mingulov/haskoki-demo:v0.3.0.0 demo
# demo-ok: 8/8 verifications holdTo build and verify locally instead of pulling: from a
checkout of this tag, build the toolchain image per the
container Quick Start
(base image only), then run the release driver, which
stages the bundle, builds the demo image, and asserts
every lane:
HASKOKI_DEMO_TEST_OUT="$PWD/out/qualification" \
HASKOKI_DEMO_REVISION="$(git rev-parse HEAD)" \
sh scripts/test-demo-image.sh
# PASS: test-demo-image.sh (...); wall ~85 min(Post-publish form shown; the image does not exist on GHCR
until the release is cut.)
Confirmed matrix
- Hosts: Linux x86-64, glibc >= 2.43 (
ubuntu:26.04+
libgmp10/libffi8/libnuma1verified; the image carries
its own userland). - Checker
pkcs11-check0.2.3 (PyPI pin), offline
smoke/full profiles; proxypkcs11-proxy-ngv0.2.2
(TEST-ONLY loopback transport). - CI gates: static gates +
cabal test all+ bundle build +
bare-install test + sdist out-of-checkout verify + fast
lane + full demo-image lanes (demo, smoke, full direct,
full proxy, compare).
Results (candidate CI at 0603322)
- Checker smoke (743 collected tests, including skips and expected failures): zero findings, direct and proxied.
- Checker full (10993 collected tests): direct 22 triaged findings
(4 families); proxied 22 findings, all shared with direct,
zero proxy-only. - Compare direct-vs-proxy: 83 frozen exclusions in 6 reasoned
families + 22 shared findings (zero allowed variance). - Direct/proxy parity on the pinned proxy: 70 consumer legs
hold; 19 quarantined legs in 5 quarantine entries with upstream
causes. - Demo: 8/8 verifications hold. Proxy example: 5/5 steps hold.
- Counts include skips and expected failures; findings are not silently
treated as passing tests. Full tables and triage: release-results.
Limitations
- Demonstrator scope: no certification; proxy example is
TEST-ONLY transport (loopback, no auth/TLS). - 316 of 464 catalog mechanisms behavior-covered. Proxy v0.2.2
resolved the previously recorded #35/#36/#37/#39 defects; the
compared subset still has documented exclusions and skipped cases. - Vector corpora ship unfetched (separate opt-in recipe).
- Full list: SUPPORTED-HOSTS;
component licenses: dependency
inventory.
Related tools
pkcs11-check
(external checker, same author),
pkcs11-proxy-ng
(proxy),
p11scope (call
observer; sample capture),
P11Lab (lab setup).
Development story
Read the development history and
Haskell design. The usage snapshot linked from
the history is cutoff-limited, not a final cost or personal-time claim.