github.com/053x/sdf is a Go wrapper for the GM/T 0018-2012 Security Device
Framework (SDF) API. It follows the same deployment model as
github.com/miekg/pkcs11: the application is built once and loads the selected
vendor shared library at runtime.
The module deliberately targets the 2012 ABI used by SoftSDF and the referenced vendor-style libraries. GM/T 0018-2012 was superseded by GM/T 0018-2023; this initial release does not claim the 2023 additions or compatibility with a vendor header that changes the 2012 data layouts.
The package is intentionally a thin ABI wrapper. It owns library loading, type-safe handles, Go/C structure conversion, standard error values, and buffer management. Device policy, key lifecycle, cryptographic protocols, and vendor compatibility decisions remain in the caller.
- Go 1.22 or newer.
- cgo and a C compiler.
- A GM/T 0018-2012 compatible
.so,.dylib, or.dll.
ctx, err := sdf.Open("/usr/local/lib/libsoftsdf.dylib")
if err != nil {
log.Fatal(err)
}
defer ctx.Close()
device, err := ctx.OpenDevice()
if err != nil {
log.Fatal(err)
}
defer ctx.CloseDevice(device)
session, err := ctx.OpenSession(device)
if err != nil {
log.Fatal(err)
}
defer ctx.CloseSession(session)
random, err := ctx.GenerateRandom(session, 32)Context may be used by multiple goroutines and Close waits for in-flight
calls. No concurrency guarantee is made for a vendor device, session, key, or
agreement handle. Serialize access to the same handle unless the vendor SDK
explicitly documents stronger behavior.
Every successful device/session open and session-key creation must be paired
with its matching close or destroy operation. An agreement handle is consumed
by the corresponding key-agreement flow. Context.Close only unloads the
shared library; it does not silently close device/session handles or destroy
keys.
SDF vendors are known to ship headers that differ from GM/T 0018-2012 and from
one another. This package uses fixed-width 32-bit scalar fields and the SoftSDF
255-byte ECCCipher.C profile. Compare DeviceInfo, RSA/ECC structures,
calling convention, and ciphertext capacity with the exact target SDK header
before hardware acceptance. Vendor extensions belong in separate packages and
must not be inferred by this base wrapper.
The loaded module is trusted native code in the application process. This package does not sandbox the module, validate its transitive dependencies, or make an untrusted library safe. Applications should resolve an absolute path, verify the deployed artifact according to their trust policy, keep device credentials outside logs and command-line arguments, and isolate vendor code in a supervised subprocess when crash or hang containment is required.
The default test suite builds and loads a small fake SDF library. An initialized SoftSDF build can be exercised explicitly:
SDF_SOFTSDF_LIBRARY=/absolute/path/to/libsoftsdf.so \
SDF_SOFTSDF_DATA_DIR=/absolute/path/to/initialized/softsdf-data \
go test -run TestSoftSDFIntegration -count=1 -vThis is software compatibility evidence only. It is not a target HSM or vendor device acceptance result.
- GmSSL/SoftSDF
- jeffrey1205/gosdf
- GM/T 0018-2023 standard record
- GM/T 0018-2012, Interface Specifications of Cryptography Device Application
Apache License 2.0. See LICENSE and NOTICE.