purego-pam

Linux-PAM binding for Go 1.27, normally built with CGO_ENABLED=0, using github.com/bnema/purego. Supported ABI targets: Linux amd64 and arm64 (LP64, 32-bit C int). This is not an authentication product.

API

• Open() (*Library, error) loads system libpam.so.0 and libc.so.6 with eager, local symbol resolution. Binding failure returns an error.
• Library.Start(service, user, NativeConversation) requires an explicit nonempty service and a native conversation function. Empty user becomes NULL; embedded NULs are rejected.
• Library.StartConversation(service, user, Conversation) adds the managed Go conversation bridge with library-owned answer buffers.
• Transaction.Authenticate(flags) and AcctMgmt(flags) return nil only for PAM_SUCCESS. Every other status produces a typed *Error. Supported flags are SILENT and DISALLOW_NULL_AUTHTOK; other bits are rejected.
• Transaction.End() passes the last operation status, consumes the transaction even on error, and releases native storage after pam_end returns. Reuse is rejected.
• Library.Close() rejects active transactions before unloading symbols.

Neither Library nor Transaction may be copied. Their zero values are closed. All operations on a Library and its Transactions require serialized caller ownership. Native calls are synchronous and may block; there is no timeout, cancellation, or thread-affinity guarantee.

Authentication success alone is not account authorization. Callers must check both Authenticate and AcctMgmt; End is cleanup, not permission to grant access. The library does not install or validate PAM service policy. System fallback configuration may apply when the named service is absent.

Native memory boundary

Start copies service/user strings into libc-owned memory and allocates the conversation structure and handle output slot there. Storage remains valid through End. On failed Start, the undefined output handle is never read or passed to pam_end. Successful Start with a NULL handle fails closed.

NativeConversation is a trusted unsafe boundary, not a safe Go callback API. Function must be a valid C-ABI conversation function address. Data must be NULL or caller-owned native memory, never a Go pointer. The caller must keep both valid until End returns; the type system cannot validate these addresses. This external API is distinct from the managed bridge below.

Managed conversation bridge

Conversation.Respond(Message, answer []byte) (length int, err error) receives copied message bytes and a zeroed 512-byte answer buffer. Write a non-NUL answer and return its byte length; informational messages require length zero. Do not retain buffers, log their contents, call transaction/library methods from the handler, or recursively invoke its conversation. Handler calls are serialized per conversation, including concurrent native entries. A handler must return; End can wait indefinitely for a blocked handler.

The bridge handles 1..32 Linux-PAM messages, represented as an array of message pointers. It accepts ECHO_OFF, ECHO_ON, ERROR_MSG and TEXT_INFO only. Message text must be NUL-terminated within 512 bytes; answers may contain at most 512 bytes. NULL and alignment checks do not make arbitrary native addresses safe: PAM modules must supply readable message memory and writable output slots.

One shared C-ABI callback lives for the process lifetime and is never unreferenced. Application data contains a nonreused numeric opaque cookie, not a memory address; neither PAM nor the bridge may dereference it. Unknown or retired cookies return CONV_ERR without touching message/output memory. Registry admission remains open during pam_end, then closes and waits for admitted callbacks before transaction storage is freed. Native modules that continue callbacks after pam_end violate the normal lifetime contract; retired cookies reject their calls, but this does not validate their behavior.

Responses are a contiguous libc-owned array with zero return codes and libc-owned strings for prompts. Successful return transfers ownership to the PAM module, which must free both. Failure publishes no response array and wipes and frees partial native answer allocations. Go prompt and answer buffers are wiped on success, handler error, and handler panic. Errors and panic payloads are not logged or returned. Handler-private copies and successful native responses after ownership transfer remain outside the library's wiping control.

Development

Production code depends on github.com/bnema/purego and the standard library. Tests use Mockery v3's generated testify mocks of PAM calls, conversation handlers and native memory through EXPECT() and RunAndReturn, alongside real libc allocations.

make check  # vet, test, build (incl. arm64), mocks-check, staticcheck
make race                       # separate CGO1 race diagnostic

Make targets use offline module resolution. Go requires CGO_ENABLED=1 for -race; no C helper is included. Tests require installed system libpam/libc and resolve PAM symbols, but PAM transaction calls go only to generated mocks. Synthetic purego.SyscallN calls exercise the actual callback ABI, including failure cleanup and callback retirement. Tests use no real authentication or credentials. Native layout sizes, offsets, and alignment have compile-time assertions for both targets; arm64 native calls remain unverified without a matching libc/libpam sysroot.

Not included: PAM service installation, CLI, worker process, defaults, setuid, shadow/password handling, sessions, credential establishment, or password changes.

License

MIT. See LICENSE.