keyctl2 0.1.0__py3-none-any.whl

keyctl2/__init__.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: 0BSD
+"""Python bindings for the Linux kernel key retention service.
+
+Create and search keys and keyrings through add_key(2), request_key(2)
+and keyctl(2) via ctypes; there are no runtime dependencies.
+
+Kernel references: keyctl(2), add_key(2), request_key(2), keyrings(7).
+"""
+
+from .errors import KeyctlError, UnsupportedError
+from .flags import (
+    KeyctlOp,
+    KeyPerm,
+    KeySpec,
+    KeyType,
+    MoveFlag,
+    ReqKeyDefault,
+)
+from .keys import (
+    Key,
+    KeyDescription,
+    add_key,
+    capabilities,
+    clear,
+    get_keyring_id,
+    get_persistent,
+    join_session_keyring,
+    keyring,
+    request_key,
+    restrict,
+    search,
+    session_to_parent,
+    set_reqkey_keyring,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Key",
+    "KeyDescription",
+    "KeyPerm",
+    "KeySpec",
+    "KeyType",
+    "KeyctlError",
+    "KeyctlOp",
+    "MoveFlag",
+    "ReqKeyDefault",
+    "UnsupportedError",
+    "__version__",
+    "add_key",
+    "capabilities",
+    "clear",
+    "get_keyring_id",
+    "get_persistent",
+    "join_session_keyring",
+    "keyring",
+    "request_key",
+    "restrict",
+    "search",
+    "session_to_parent",
+    "set_reqkey_keyring",
+]

keyctl2/_syscall.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: 0BSD
+"""Raw ctypes bindings for add_key(2), request_key(2) and keyctl(2).
+
+glibc has no wrappers for these syscalls on most architectures, so all
+three are invoked through libc's syscall(2). The numbers differ per
+architecture; the table covers the common ones and everything else gets
+UnsupportedError.
+"""
+
+import ctypes
+import ctypes.util
+import errno
+import os
+import platform
+import sys
+from typing import NoReturn
+
+from .errors import KeyctlError, UnsupportedError
+from .flags import KeyctlOp
+
+_libc: ctypes.CDLL | None = None
+_numbers: tuple[int, int, int] | None = None
+
+
+def _get_libc() -> ctypes.CDLL:
+    global _libc
+    if _libc is None:
+        if sys.platform != "linux":
+            raise UnsupportedError("keyctl2 is only available on Linux")
+        name = ctypes.util.find_library("c")
+        _libc = ctypes.CDLL(name or None, use_errno=True)
+        _libc.syscall.restype = ctypes.c_long
+    return _libc
+
+
+def _syscall_numbers() -> tuple[int, int, int]:
+    """Return the (add_key, request_key, keyctl) numbers for this arch."""
+    global _numbers
+    if _numbers is not None:
+        return _numbers
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        _numbers = (248, 249, 250)
+    elif machine in ("aarch64", "arm64", "riscv64", "loongarch64"):
+        # asm-generic syscall table
+        _numbers = (217, 218, 219)
+    elif machine in ("i386", "i486", "i586", "i686", "x86"):
+        _numbers = (286, 287, 288)
+    else:
+        raise UnsupportedError(
+            f"no add_key/request_key/keyctl numbers for architecture {machine}"
+        )
+    return _numbers
+
+
+def _raise_errno(err: int) -> NoReturn:
+    if err in (errno.ENOSYS, errno.EOPNOTSUPP):
+        raise UnsupportedError(err, os.strerror(err))
+    raise KeyctlError(err, os.strerror(err))
+
+
+def _call(nr: int, *args: object) -> int:
+    ret = int(_get_libc().syscall(nr, *args))
+    if ret == -1:
+        _raise_errno(ctypes.get_errno())
+    return ret
+
+
+def _keyctl(op: int, *args: object) -> int:
+    return _call(_syscall_numbers()[2], op, *args)
+
+
+def _u32(value: int) -> ctypes.c_uint32:
+    # unsigned 32-bit argument, so -1 style sentinels marshal correctly
+    return ctypes.c_uint32(value & 0xFFFFFFFF)
+
+
+def add_key(
+    type_: bytes,
+    description: bytes | None,
+    payload: bytes | None,
+    ringid: int,
+) -> int:
+    """add_key(2): create or update a key in ringid, return its serial."""
+    plen = 0 if payload is None else len(payload)
+    return _call(_syscall_numbers()[0], type_, description, payload, plen, ringid)
+
+
+def request_key(
+    type_: bytes,
+    description: bytes,
+    callout_info: bytes | None,
+    ringid: int,
+) -> int:
+    """request_key(2): find or conjure a key, return its serial."""
+    return _call(_syscall_numbers()[1], type_, description, callout_info, ringid)
+
+
+def get_keyring_id(ringid: int, create: bool) -> int:
+    """KEYCTL_GET_KEYRING_ID: resolve a key or special ID to a serial."""
+    return _keyctl(KeyctlOp.GET_KEYRING_ID, ringid, int(create))
+
+
+def join_session_keyring(name: bytes | None) -> int:
+    """KEYCTL_JOIN_SESSION_KEYRING: return the joined ring's serial."""
+    return _keyctl(KeyctlOp.JOIN_SESSION_KEYRING, name)
+
+
+def update(serial: int, payload: bytes | None) -> None:
+    """KEYCTL_UPDATE: replace a key's payload."""
+    plen = 0 if payload is None else len(payload)
+    _keyctl(KeyctlOp.UPDATE, serial, payload, plen)
+
+
+def revoke(serial: int) -> None:
+    """KEYCTL_REVOKE: revoke a key."""
+    _keyctl(KeyctlOp.REVOKE, serial)
+
+
+def chown(serial: int, uid: int, gid: int) -> None:
+    """KEYCTL_CHOWN: set ownership; -1 leaves a field unchanged."""
+    _keyctl(KeyctlOp.CHOWN, serial, _u32(uid), _u32(gid))
+
+
+def setperm(serial: int, perm: int) -> None:
+    """KEYCTL_SETPERM: set a key's permission mask."""
+    _keyctl(KeyctlOp.SETPERM, serial, _u32(perm))
+
+
+def describe(serial: int) -> bytes:
+    """KEYCTL_DESCRIBE: return the type;uid;gid;perm;description string."""
+    size = _keyctl(KeyctlOp.DESCRIBE, serial, None, 0)
+    buf = ctypes.create_string_buffer(size)
+    _keyctl(KeyctlOp.DESCRIBE, serial, buf, size)
+    return bytes(buf.value)
+
+
+def clear(ringid: int) -> None:
+    """KEYCTL_CLEAR: remove all links from a keyring."""
+    _keyctl(KeyctlOp.CLEAR, ringid)
+
+
+def link(serial: int, ringid: int) -> None:
+    """KEYCTL_LINK: link a key into a keyring."""
+    _keyctl(KeyctlOp.LINK, serial, ringid)
+
+
+def unlink(serial: int, ringid: int) -> None:
+    """KEYCTL_UNLINK: remove a key's link from a keyring."""
+    _keyctl(KeyctlOp.UNLINK, serial, ringid)
+
+
+def search(ringid: int, type_: bytes, description: bytes, destringid: int) -> int:
+    """KEYCTL_SEARCH: find a key in a ring, return its serial."""
+    return _keyctl(KeyctlOp.SEARCH, ringid, type_, description, destringid)
+
+
+def read(serial: int) -> bytes:
+    """KEYCTL_READ: return a key's payload or a keyring's serial list."""
+    size = _keyctl(KeyctlOp.READ, serial, None, 0)
+    if size == 0:
+        return b""
+    buf = ctypes.create_string_buffer(size)
+    got = _keyctl(KeyctlOp.READ, serial, buf, size)
+    return buf.raw[:got]
+
+
+def set_reqkey_keyring(default: int) -> int:
+    """KEYCTL_SET_REQKEY_KEYRING: set the request_key(2) default ring."""
+    return _keyctl(KeyctlOp.SET_REQKEY_KEYRING, default)
+
+
+def set_timeout(serial: int, timeout: int) -> None:
+    """KEYCTL_SET_TIMEOUT: expire a key after timeout seconds."""
+    _keyctl(KeyctlOp.SET_TIMEOUT, serial, _u32(timeout))
+
+
+def session_to_parent() -> None:
+    """KEYCTL_SESSION_TO_PARENT: install our session keyring on the parent."""
+    _keyctl(KeyctlOp.SESSION_TO_PARENT)
+
+
+def invalidate(serial: int) -> None:
+    """KEYCTL_INVALIDATE: mark a key invalid."""
+    _keyctl(KeyctlOp.INVALIDATE, serial)
+
+
+def get_persistent(uid: int, ringid: int) -> int:
+    """KEYCTL_GET_PERSISTENT: return a user's persistent keyring serial."""
+    return _keyctl(KeyctlOp.GET_PERSISTENT, _u32(uid), ringid)
+
+
+def restrict_keyring(
+    ringid: int, type_: bytes | None, restriction: bytes | None
+) -> None:
+    """KEYCTL_RESTRICT_KEYRING: limit which keys may link to a ring."""
+    _keyctl(KeyctlOp.RESTRICT_KEYRING, ringid, type_, restriction)
+
+
+def move(serial: int, from_ringid: int, to_ringid: int, flags: int) -> None:
+    """KEYCTL_MOVE: move a key's link between keyrings."""
+    _keyctl(KeyctlOp.MOVE, serial, from_ringid, to_ringid, _u32(flags))
+
+
+def capabilities() -> bytes:
+    """KEYCTL_CAPABILITIES: return the subsystem capability bits."""
+    buf = ctypes.create_string_buffer(8)
+    got = _keyctl(KeyctlOp.CAPABILITIES, buf, len(buf))
+    return buf.raw[:got]

keyctl2/errors.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: 0BSD
+"""Exception types raised by keyctl2."""
+
+
+class KeyctlError(OSError):
+    """A key management syscall failed.
+
+    The errno attribute carries the kernel error. Common values are
+    ENOKEY for a missing or non-searchable key, EACCES for a revoked,
+    expired or inaccessible key, EDQUOT for an exceeded key quota and
+    EKEYEXPIRED or EKEYREVOKED for keys in those states.
+    """
+
+
+class UnsupportedError(KeyctlError):
+    """The running kernel or architecture does not support the operation."""

keyctl2/flags.py

@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: 0BSD
+"""Constants for the kernel key retention service.
+
+Values are from linux/keyctl.h and keyutils.h. See keyctl(2), keyrings(7)
+and the kernel documentation under Documentation/security/keys/.
+"""
+
+from enum import Enum, IntEnum, IntFlag
+
+__all__ = [
+    "KeyPerm",
+    "KeySpec",
+    "KeyType",
+    "KeyctlOp",
+    "MoveFlag",
+    "ReqKeyDefault",
+]
+
+
+class KeySpec(IntEnum):
+    """Special keyring IDs, resolved by the kernel per caller.
+
+    The negative values are passed to the kernel verbatim; they are not
+    real key serials.
+    """
+
+    THREAD_KEYRING = -1
+    PROCESS_KEYRING = -2
+    SESSION_KEYRING = -3
+    USER_KEYRING = -4
+    USER_SESSION_KEYRING = -5
+    GROUP_KEYRING = -6
+    REQKEY_AUTH_KEY = -7
+    REQUESTOR_KEYRING = -8
+
+    @classmethod
+    def from_name(cls, name: str) -> "KeySpec":
+        """Resolve a short name like "session" or "user" to a KeySpec."""
+        table = {
+            "thread": cls.THREAD_KEYRING,
+            "process": cls.PROCESS_KEYRING,
+            "session": cls.SESSION_KEYRING,
+            "user": cls.USER_KEYRING,
+            "user_session": cls.USER_SESSION_KEYRING,
+            "group": cls.GROUP_KEYRING,
+            "reqkey_auth": cls.REQKEY_AUTH_KEY,
+            "requestor": cls.REQUESTOR_KEYRING,
+        }
+        try:
+            return table[name]
+        except KeyError:
+            raise ValueError(f"unknown keyring name: {name!r}") from None
+
+
+class KeyPerm(IntFlag):
+    """Key permission bits, one hex digit per class.
+
+    Each of the possessor, user, group and other classes holds the same
+    six bits: VIEW, READ, WRITE, SEARCH, LINK and SETATTR. The ALL masks
+    cover a whole class; KeyPerm.ALL covers everything.
+    """
+
+    NONE = 0
+    POS_VIEW = 0x01000000
+    POS_READ = 0x02000000
+    POS_WRITE = 0x04000000
+    POS_SEARCH = 0x08000000
+    POS_LINK = 0x10000000
+    POS_SETATTR = 0x20000000
+    POS_ALL = 0x3F000000
+    USR_VIEW = 0x00010000
+    USR_READ = 0x00020000
+    USR_WRITE = 0x00040000
+    USR_SEARCH = 0x00080000
+    USR_LINK = 0x00100000
+    USR_SETATTR = 0x00200000
+    USR_ALL = 0x003F0000
+    GRP_VIEW = 0x00000100
+    GRP_READ = 0x00000200
+    GRP_WRITE = 0x00000400
+    GRP_SEARCH = 0x00000800
+    GRP_LINK = 0x00001000
+    GRP_SETATTR = 0x00002000
+    GRP_ALL = 0x00003F00
+    OTH_VIEW = 0x00000001
+    OTH_READ = 0x00000002
+    OTH_WRITE = 0x00000004
+    OTH_SEARCH = 0x00000008
+    OTH_LINK = 0x00000010
+    OTH_SETATTR = 0x00000020
+    OTH_ALL = 0x0000003F
+    ALL = 0x3F3F3F3F
+
+
+class KeyType(str, Enum):
+    """Common kernel key types.
+
+    Plain strings are accepted everywhere a KeyType is, so types not
+    listed here can still be used.
+    """
+
+    USER = "user"
+    LOGON = "logon"
+    KEYRING = "keyring"
+    BIG_KEY = "big_key"
+    ASYMMETRIC = "asymmetric"
+
+
+class KeyctlOp(IntEnum):
+    """Operation codes for the keyctl(2) syscall."""
+
+    GET_KEYRING_ID = 0
+    JOIN_SESSION_KEYRING = 1
+    UPDATE = 2
+    REVOKE = 3
+    CHOWN = 4
+    SETPERM = 5
+    DESCRIBE = 6
+    CLEAR = 7
+    LINK = 8
+    UNLINK = 9
+    SEARCH = 10
+    READ = 11
+    SET_REQKEY_KEYRING = 14
+    SET_TIMEOUT = 15
+    SESSION_TO_PARENT = 18
+    INVALIDATE = 21
+    GET_PERSISTENT = 22
+    RESTRICT_KEYRING = 29
+    MOVE = 30
+    CAPABILITIES = 31
+
+
+class MoveFlag(IntFlag):
+    """Flags for KEYCTL_MOVE."""
+
+    NONE = 0
+    EXCL = 0x00000001  # KEYCTL_MOVE_EXCL, do not displace a matching key
+
+
+class ReqKeyDefault(IntEnum):
+    """Default destination keyring for request_key(2), KEY_REQKEY_DEFL_*."""
+
+    NO_CHANGE = -1
+    DEFAULT = 0
+    THREAD_KEYRING = 1
+    PROCESS_KEYRING = 2
+    SESSION_KEYRING = 3
+    USER_KEYRING = 4
+    USER_SESSION_KEYRING = 5
+    GROUP_KEYRING = 6
+    REQUESTOR_KEYRING = 7

keyctl2/keys.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: 0BSD
+"""High-level interface to the kernel key retention service.
+
+Serials returned by add_key() and friends are plain ints. Wrap one in a
+Key to describe, read, update, link or revoke it. Keyring arguments
+accept a serial, a KeySpec member or a short name like "session".
+
+Kernel references: keyctl(2), add_key(2), request_key(2), keyrings(7).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from . import _syscall
+from .flags import KeyPerm, KeySpec, KeyType, MoveFlag, ReqKeyDefault
+
+__all__ = [
+    "Key",
+    "KeyDescription",
+    "add_key",
+    "capabilities",
+    "clear",
+    "get_keyring_id",
+    "get_persistent",
+    "join_session_keyring",
+    "keyring",
+    "request_key",
+    "restrict",
+    "search",
+    "session_to_parent",
+    "set_reqkey_keyring",
+]
+
+_KeyringLike = int | KeySpec | str
+_KeyTypeLike = str | KeyType
+
+
+def _ring(ring: _KeyringLike) -> int:
+    if isinstance(ring, str):
+        return int(KeySpec.from_name(ring))
+    return int(ring)
+
+
+def _type(type_: _KeyTypeLike) -> bytes:
+    if isinstance(type_, KeyType):
+        type_ = type_.value
+    return os.fsencode(type_)
+
+
+def _desc(description: str) -> bytes:
+    data = os.fsencode(description)
+    if b"\x00" in data:
+        raise ValueError("description must not contain NUL")
+    return data
+
+
+def add_key(
+    type_: _KeyTypeLike,
+    description: str,
+    payload: bytes | None = None,
+    keyring: _KeyringLike = KeySpec.SESSION_KEYRING,
+) -> int:
+    """Create a key in the given keyring and return its serial.
+
+    If a matching key already exists in the keyring its payload is
+    updated instead. EDQUOT means the caller's key quota is exhausted.
+    """
+    return _syscall.add_key(_type(type_), _desc(description), payload, _ring(keyring))
+
+
+def request_key(
+    type_: _KeyTypeLike,
+    description: str,
+    keyring: _KeyringLike = KeySpec.SESSION_KEYRING,
+    callout_info: str | None = None,
+) -> int:
+    """Search the caller's keyrings for a key, return its serial.
+
+    If the key is not found and callout_info is given, the kernel asks
+    /sbin/request-key to instantiate it, passing callout_info along.
+    With callout_info=None a miss raises ENOKEY.
+    """
+    info = None if callout_info is None else os.fsencode(callout_info)
+    return _syscall.request_key(_type(type_), _desc(description), info, _ring(keyring))
+
+
+def join_session_keyring(name: str | None = None) -> int:
+    """Join or create a session keyring, return its serial.
+
+    This replaces the calling process's session keyring. name=None
+    joins a fresh anonymous keyring.
+    """
+    return _syscall.join_session_keyring(None if name is None else os.fsencode(name))
+
+
+def get_keyring_id(ring: _KeyringLike, create: bool = False) -> int:
+    """Resolve a key or special keyring ID to a real serial.
+
+    With create=True, special keyring IDs are created on demand.
+    """
+    return _syscall.get_keyring_id(_ring(ring), create)
+
+
+def keyring(ring: _KeyringLike) -> Key:
+    """Wrap a keyring serial, KeySpec member or name in a Key."""
+    return Key(_ring(ring))
+
+
+def clear(ring: _KeyringLike) -> None:
+    """Remove all links from a keyring."""
+    _syscall.clear(_ring(ring))
+
+
+def search(
+    ring: _KeyringLike,
+    type_: _KeyTypeLike,
+    description: str,
+    dest: _KeyringLike = 0,
+) -> int:
+    """Search a keyring tree for a key, return its serial.
+
+    If dest is nonzero the found key is also linked into that keyring.
+    ENOKEY means no matching key was found or it was not searchable.
+    """
+    return _syscall.search(_ring(ring), _type(type_), _desc(description), _ring(dest))
+
+
+def restrict(
+    ring: _KeyringLike,
+    type_: _KeyTypeLike | None = None,
+    restriction: str | None = None,
+) -> None:
+    """Restrict which keys may be linked into a keyring.
+
+    With type=None and restriction=None the ring rejects all further
+    links. A type may only be named if it implements a restriction
+    scheme, like "asymmetric" does; the restriction string then selects
+    the scheme, for example "builtin_trusted". Restriction is permanent.
+    """
+    _syscall.restrict_keyring(
+        _ring(ring),
+        None if type_ is None else _type(type_),
+        None if restriction is None else os.fsencode(restriction),
+    )
+
+
+def session_to_parent() -> None:
+    """Install this process's session keyring on the parent process."""
+    _syscall.session_to_parent()
+
+
+def get_persistent(uid: int, ring: _KeyringLike) -> int:
+    """Return a user's persistent keyring, linked into ring.
+
+    The persistent keyring survives logout for a kernel-configured
+    grace period. EOPNOTSUPP means the kernel lacks persistent ring
+    support.
+    """
+    return _syscall.get_persistent(uid, _ring(ring))
+
+
+def set_reqkey_keyring(default: ReqKeyDefault) -> None:
+    """Set the default destination ring for request_key(2) calls."""
+    _syscall.set_reqkey_keyring(int(default))
+
+
+def capabilities() -> bytes:
+    """Return the keyrings subsystem capability bits."""
+    return _syscall.capabilities()
+
+
+@dataclass(frozen=True)
+class KeyDescription:
+    """Parsed result of KEYCTL_DESCRIBE."""
+
+    type: str
+    uid: int
+    gid: int
+    perm: KeyPerm
+    description: str
+
+    @classmethod
+    def parse(cls, text: bytes) -> KeyDescription:
+        """Parse a type;uid;gid;perm;description string.
+
+        The description itself may contain semicolons, so at most four
+        fields are split off the front.
+        """
+        parts = text.split(b";", 4)
+        if len(parts) != 5:
+            raise ValueError(f"malformed describe string: {text!r}")
+        return cls(
+            type=parts[0].decode("ascii"),
+            uid=int(parts[1]),
+            gid=int(parts[2]),
+            perm=KeyPerm(int(parts[3], 16)),
+            description=os.fsdecode(parts[4]),
+        )
+
+
+class Key:
+    """A key or keyring, referenced by serial or KeySpec member."""
+
+    __slots__ = ("_serial",)
+
+    def __init__(self, serial: int | KeySpec) -> None:
+        self._serial = int(serial)
+
+    @property
+    def serial(self) -> int:
+        """The key serial number, possibly a negative KeySpec value."""
+        return self._serial
+
+    def describe(self) -> KeyDescription:
+        """Fetch the key's attributes."""
+        return KeyDescription.parse(_syscall.describe(self._serial))
+
+    def read(self) -> bytes:
+        """Read the key's payload, or a keyring's serial list.
+
+        EKEYREVOKED, EKEYEXPIRED or EACCES mean the key can no longer be
+        read by this caller.
+        """
+        return _syscall.read(self._serial)
+
+    def update(self, payload: bytes | None) -> None:
+        """Replace the key's payload."""
+        _syscall.update(self._serial, payload)
+
+    def set_timeout(self, seconds: int) -> None:
+        """Make the key expire after the given number of seconds."""
+        if seconds < 0:
+            raise ValueError(f"timeout out of range: {seconds}")
+        _syscall.set_timeout(self._serial, seconds)
+
+    def set_perm(self, perm: KeyPerm) -> None:
+        """Set the key's permission mask."""
+        _syscall.setperm(self._serial, int(perm))
+
+    def link(self, ring: _KeyringLike) -> None:
+        """Link the key into a keyring."""
+        _syscall.link(self._serial, _ring(ring))
+
+    def unlink(self, ring: _KeyringLike) -> None:
+        """Remove the key's link from a keyring."""
+        _syscall.unlink(self._serial, _ring(ring))
+
+    def move(
+        self,
+        from_ring: _KeyringLike,
+        to_ring: _KeyringLike,
+        flags: MoveFlag = MoveFlag.NONE,
+    ) -> None:
+        """Atomically move the key's link between two keyrings.
+
+        With MoveFlag.EXCL, a matching key already in to_ring is kept
+        and the call fails with EEXIST instead of displacing it.
+        """
+        _syscall.move(self._serial, _ring(from_ring), _ring(to_ring), int(flags))
+
+    def revoke(self) -> None:
+        """Revoke the key, making it unusable."""
+        _syscall.revoke(self._serial)
+
+    def invalidate(self) -> None:
+        """Mark the key invalid, making it vanish promptly."""
+        _syscall.invalidate(self._serial)
+
+    def chown(self, uid: int = -1, gid: int = -1) -> None:
+        """Set the key's owner; -1 leaves a field unchanged."""
+        _syscall.chown(self._serial, uid, gid)
+
+    def search(
+        self,
+        type_: _KeyTypeLike,
+        description: str,
+        dest: _KeyringLike = 0,
+    ) -> int:
+        """Search this keyring for a key, return its serial."""
+        return search(self._serial, type_, description, dest)
+
+    def __int__(self) -> int:
+        return self._serial
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._serial})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Key):
+            return self._serial == other._serial
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._serial)

keyctl2-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: keyctl2
+Version: 0.1.0
+Summary: Python bindings for the Linux kernel keyring
+Project-URL: Homepage, https://quad4.io
+Project-URL: Repository, https://github.com/Quad4-Software/keyctl2
+Project-URL: Issues, https://github.com/Quad4-Software/keyctl2/issues
+Project-URL: Changelog, https://github.com/Quad4-Software/keyctl2/blob/master/CHANGELOG.md
+Author: Quad4
+License-Expression: 0BSD
+License-File: LICENSE
+Keywords: keyctl,keyring,linux,secrets,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# keyctl2
+
+[![CI](https://github.com/Quad4-Software/keyctl2/actions/workflows/ci.yml/badge.svg)](https://github.com/Quad4-Software/keyctl2/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Quad4-Software/keyctl2/actions/workflows/codeql.yml/badge.svg)](https://github.com/Quad4-Software/keyctl2/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Quad4-Software/keyctl2/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Quad4-Software/keyctl2)
+[![PyPI](https://img.shields.io/pypi/v/keyctl2.svg)](https://pypi.org/project/keyctl2/)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue)](LICENSE)
+
+Dependency-free Python bindings for the Linux kernel keyring: add,
+search, read, describe, link and unlink keys in session and process
+keyrings, without shelling out to keyctl(1).
+
+Requires Python 3.10+ and Linux. No runtime dependencies: the bindings
+call add_key(2), request_key(2) and keyctl(2) through ctypes.
+
+## Install
+
+    pip install keyctl2
+
+## Example
+
+    import keyctl2
+
+    # Add a user key to the session keyring and read it back.
+    serial = keyctl2.add_key("user", "my-secret", b"hunter2")
+    key = keyctl2.Key(serial)
+    assert key.read() == b"hunter2"
+
+    # Search the session keyring for it later.
+    assert keyctl2.search("session", "user", "my-secret") == serial
+
+    # Inspect it and clean up.
+    print(key.describe())   # KeyDescription(type='user', ...)
+    key.unlink("session")
+
+## Development
+
+    uv sync --group dev
+    make check
+
+License: 0BSD. Quad4 Software, https://quad4.io

keyctl2-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+keyctl2/__init__.py,sha256=BZQSSjXi6F1JtWY9lHVrK9PcUxwhcDYU9ZRmHn-ztj8,1192
+keyctl2/_syscall.py,sha256=UyUluf3FWlQgbesF-vrHfzARdJTO4XVxaLOp-eyq7zk,6646
+keyctl2/errors.py,sha256=GE9AtXAuBPJZ9uYKbI0of55A79FN6gTTNX-gRiflads,533
+keyctl2/flags.py,sha256=Fb7Yk6SKttKILOoJaG9lwbzRsu2qzubscAa6ATUlAAs,3732
+keyctl2/keys.py,sha256=IeIsnxXtrn2zSF0qUlhs16O4fJfM1FcwzK8qCiALVYg,8934
+keyctl2/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keyctl2-0.1.0.dist-info/METADATA,sha256=h-UGB6wR5epE6BTDVOE6vJRDZFXThpqXVHLDxeszq7M,2756
+keyctl2-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+keyctl2-0.1.0.dist-info/licenses/LICENSE,sha256=3Hnwsz5EXuTC9iTlGjzA171dKQtIVsgjFoF5DEMRl48,633
+keyctl2-0.1.0.dist-info/RECORD,,

keyctl2-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

keyctl2-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Quad4
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.