# Go SDK Reference

> The pure-Go Peios SDK: package conventions and native security-descriptor operations.

---

# 1.1 Overview

_Peios / Developing for Peios / Go SDK Reference / Go SDK conventions_

> Where peios-go fits, what its packages expose, and how native calls report errors and own resources.

`github.com/peios/peios-go` is the independent, pure-Go Peios SDK. Applications do not need cgo, libpeios, or libp-go at runtime. The API uses Go values and standard interfaces rather than reproducing each C function's calling convention.

This book documents the Go API. The [source repository](https://github.com/peios/peios-go) contains package documentation and a per-symbol conformance inventory. Start with [security descriptors and selectors](/peios/developing-for-peios/go-sdk-reference/go-sdk-security/security-descriptors-and-selectors.md) for reading or changing an object's security metadata.

## 1.1.1 Packages

| Package | Purpose |
| --- | --- |
| `security` | Portable SIDs, GUIDs, ACLs, descriptors, SDDL, conditions, claims, and inheritance. |
| `msgpack` | Portable MessagePack encoding, decoding, cursors, and validation. |
| `access` | Audit contexts and native access checks. |
| `file` | Native file creation/opening, security descriptors, System V IPC descriptors, and mount policy. |
| `token` | Token specifications and native identity, sessions, adjustments, and impersonation. |
| `socket` | Peer identity, message identity, and descriptor transfer. |
| `process` | Process security-block queries and mitigation activation; ordinary process creation uses Go's `os/exec`. |
| `registry` | Keys, values, descriptors, notifications, transactions, layers, and backup/restore. |
| `registry/source` | Portable registry-source codecs and native source hosting. |
| `event` | Event emission, policy, record decoding, rings, and readers. |

Native operations target Linux/amd64 with the Peios kernel ABI. Compiling an application on ordinary Linux does not supply that ABI: unsupported system calls return `syscall.ENOSYS`. Portable functionality, including `security` and `msgpack`, can also run on other operating systems.

## 1.1.2 Errors and ownership

Native errors use `syscall.Errno` and support `errors.Is`. Check the error before using a result; parsing a descriptor verifies its binary structure, not whether the caller may install it on a particular object. The kernel still enforces authorization on native operations.

Descriptor parsers and encoders return Go-owned values and bytes. Close owned native handles when finished. File operations accepting `syscall.Conn`, including an `*os.File`, protect the descriptor against concurrent close and reuse during the call. Raw `dirfd` arguments are borrowed: the caller must keep them open for the entire operation.

Binary descriptors preserve information that SDDL cannot always express. Use binary parsing and encoding when preserving unknown ACEs or descriptor control metadata matters; SDDL formatting can reject an ACE or payload it cannot represent.

---

# 2.1 Security descriptors and selectors

_Peios / Developing for Peios / Go SDK Reference / Go SDK security_

> Read and update selected descriptor components, including mandatory-integrity labels, through the Go SDK.

`security.SecurityInformation` is the bitmask that selects components of a security descriptor. Use its named constants with file and registry descriptor operations:

| Constant | Value | Selected component |
| --- | --- | --- |
| `security.InfoOwner` | `0x01` | Owner SID. |
| `security.InfoGroup` | `0x02` | Group SID. |
| `security.InfoDACL` | `0x04` | Discretionary ACL. |
| `security.InfoSACL` | `0x08` | Full system ACL. |
| `security.InfoLabel` | `0x10` | Mandatory-integrity label within the SACL. |

Combine selectors with `|`, for example `security.InfoOwner | security.InfoDACL`. `InfoLabel` can accompany owner, group, or DACL selection, but **must not be combined with `InfoSACL`**; the kernel rejects that combination with `EINVAL`.

`InfoLabel` reads or writes a descriptor containing the label ACE in its SACL. Its payload is not a raw integrity SID. Reading the label requires `READ_CONTROL`; writing it requires `WRITE_OWNER`. Raising a label above the caller's integrity also requires `SeRelabelPrivilege`. Selecting the full SACL instead requires `ACCESS_SYSTEM_SECURITY`, gated by `SeSecurityPrivilege`.

Updates preserve components that were not selected. In particular, selecting only `InfoLabel` changes the mandatory label without replacing the other SACL entries. All selected components must pass their applicable authorization checks.

## 2.1.1 File descriptors

`file.GetDescriptor(f, info)` returns owned descriptor bytes; `file.SetDescriptor(f, info, sd)` applies selected components from binary descriptor bytes. Both accept `syscall.Conn`, including `*os.File`. The path-relative variants are `file.GetDescriptorAt(dirfd, path, info, flags)` and `file.SetDescriptorAt(dirfd, path, info, sd, flags)`.

For example, read and parse just the mandatory label:

```go
package example

import (
    "os"

    "github.com/peios/peios-go/file"
    "github.com/peios/peios-go/security"
)

func readLabel(f *os.File) (security.Descriptor, error) {
    wire, err := file.GetDescriptor(f, security.InfoLabel)
    if err != nil {
        return security.Descriptor{}, err
    }
    return security.ParseDescriptor(wire)
}
```

To request a medium-integrity, no-write-up label, build the descriptor and select only its label:

```go
func setMediumLabel(f *os.File) error {
    sd, err := security.ParseSDDL("S:(ML;;NW;;;ME)")
    if err != nil {
        return err
    }
    wire, err := sd.MarshalBinary()
    if err != nil {
        return err
    }
    return file.SetDescriptor(f, security.InfoLabel, wire)
}
```

The second example uses the first example's imports. These functions perform native Peios operations and still depend on the caller's authority; constructing valid SDDL does not grant permission to set it.

## 2.1.2 Registry keys

`(*registry.Key).GetDescriptor(info)` returns binary descriptor bytes, and `(*registry.Key).SetDescriptor(info, sd, tx)` writes selected components. They use the same `security.Info*` selectors, including `InfoLabel`, and the same prohibition on combining label and full-SACL selection. Pass a `*registry.Transaction` for a transactional update, or `nil` for an update without an explicit transaction.

Use `security.ParseDescriptor` to decode returned bytes and `Descriptor.MarshalBinary` to encode a descriptor for an update. `security.ParseSDDL` is available when constructing a descriptor from text. An absent DACL and an empty DACL are different: preserve that distinction when building or rewriting descriptors.