keyring.go

// Copyright 2015 Jesse Sipprell. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

//go:build linux

// A Go interface to linux kernel keyrings (keyctl interface)
package keyutils

import (
	"bufio"
	"fmt"
	"os"
	"strconv"
	"strings"
	"syscall"
)

// All Keys and Keyrings have unique 32-bit serial number identifiers.
type Id interface {
	Id() int32
	Info() (Info, error)

	private()
}

// Basic interface to a linux keyctl keyring.
type Keyring interface {
	Id
	Add(string, []byte) (*Key, error)
	AddType(string, string, []byte) (*Key, error)
	Search(string) (*Key, error)
	SearchType(string, string) (*Key, error)
	SetDefaultTimeout(uint)
	AttachPersistent() (Keyring, error)
}

// Named keyrings are user-created keyrings linked to a parent keyring. The
// parent can be either named or one of the in-built keyrings (session, group
// etc). The in-built keyrings have no parents. Keyring searching is performed
// hierarchically.
type NamedKeyring interface {
	Keyring
	Name() string
}

type keyring struct {
	id         keyId
	defaultTtl uint
}

type namedKeyring struct {
	*keyring
	parent keyId
	name   string // for non-anonymous keyrings
	ttl    uint
}

func (kr *keyring) private() {}

// Returns the 32-bit kernel identifier of a keyring
func (kr *keyring) Id() int32 {
	return int32(kr.id)
}

// Returns information about a keyring.
func (kr *keyring) Info() (Info, error) {
	return getInfo(kr.id)
}

// Return the name of a NamedKeyring that was set when the keyring was created
// or opened.
func (kr *namedKeyring) Name() string {
	return kr.name
}

// Set a default timeout, in seconds, after which newly added keys will be
// destroyed.
func (kr *keyring) SetDefaultTimeout(nsecs uint) {
	kr.defaultTtl = nsecs
}

// Add a new key to a keyring. The key can be searched for later by name.
func (kr *keyring) Add(name string, key []byte) (*Key, error) {
	return kr.AddType(name, "user", key)
}

// Add a new key to a keyring with a specific key type. The key can be searched
// for later by name.
func (kr *keyring) AddType(name string, keyType string, key []byte) (*Key, error) {
	r, err := add_key(keyType, name, key, int32(kr.id))
	if err == nil {
		key := &Key{Name: name, id: keyId(r), ring: kr.id}
		if kr.defaultTtl != 0 {
			err = key.ExpireAfter(kr.defaultTtl)
		}
		return key, err
	}

	return nil, err
}

// Search for a key by name, this also searches child keyrings linked to this
// one. The key, if found, is linked to the top keyring that Search() was called
// from.
func (kr *keyring) Search(name string) (*Key, error) {
	return kr.SearchType(name, "user")
}

// Search for a key by name and type, this also searches child keyrings linked
// to this one. The key, if found, is linked to the top keyring that SearchType()
// was called from.
func (kr *keyring) SearchType(name string, keyType string) (*Key, error) {
	id, err := searchKeyring(kr.id, name, keyType)
	if err == nil {
		return &Key{Name: name, id: id, ring: kr.id}, nil
	}
	return nil, err
}

// Return the current login session keyring
func SessionKeyring() (Keyring, error) {
	return newKeyring(keySpecSessionKeyring)
}

// Return the current user-session keyring (part of session, but private to
// current user)
func UserSessionKeyring() (Keyring, error) {
	return newKeyring(keySpecUserSessionKeyring)
}

// Return the current user keyring.
func UserKeyring() (Keyring, error) {
	return newKeyring(keySpecUserKeyring)
}

// Return the current group keyring.
func GroupKeyring() (Keyring, error) {
	return newKeyring(keySpecGroupKeyring)
}

// Return the keyring specific to the current executing thread.
func ThreadKeyring() (Keyring, error) {
	return newKeyring(keySpecThreadKeyring)
}

// Return the keyring specific to the current executing process.
func ProcessKeyring() (Keyring, error) {
	return newKeyring(keySpecProcessKeyring)
}

// Return a named global keyring.
func GlobalKeyring(name string) (NamedKeyring, error) {
	id, err := requestKey("keyring", name, 0)
	if err != nil || id < 0 {
		f, err := os.Open("/proc/keys")
		if err != nil {
			return nil, err
		}
		defer f.Close()

		scanner := bufio.NewScanner(f)
		for scanner.Scan() {
			fields := strings.Fields(scanner.Text())
			if len(fields) < 9 {
				continue
			}

			if fields[3] == "expd" {
				continue
			}

			keyType := fields[7]
			if keyType != "keyring" {
				continue
			}

			keyDesc := fields[8]
			if !strings.HasPrefix(keyDesc, name) {
				continue
			}

			idInt, err := strconv.ParseInt(fields[0], 16, 32)
			if err != nil {
				return nil, fmt.Errorf("error parsing key id: %w", err)
			}

			id = keyId(idInt)
		}

		if err := scanner.Err(); err != nil {
			return nil, fmt.Errorf("error reading /proc/keys: %w", err)
		}
	}

	if id < 0 {
		return nil, fmt.Errorf("key not found: %w", syscall.ENOKEY)
	}

	keyring, err := newKeyring(id)
	if err != nil {
		return nil, err
	}

	return &namedKeyring{
		keyring: keyring,
		name:    name,
	}, nil
}

// Creates a new named-keyring linked to a parent keyring. The parent may be
// one of those returned by SessionKeyring(), UserSessionKeyring() and friends
// or it may be an existing named-keyring. When searching is performed, all
// keyrings form a hierarchy and are searched top-down. If the keyring already
// exists it will be destroyed and a new one with the same name created. Named
// sub-keyrings inherit their initial ttl (if set) from the parent but can
// outlive the parent as the timer is restarted at creation.
func CreateKeyring(parent Keyring, name string) (NamedKeyring, error) {
	var ttl uint

	parentId := keyId(parent.Id())
	kr, err := createKeyring(parentId, name)
	if err != nil {
		return nil, err
	}

	if pkr, ok := parent.(*namedKeyring); ok {
		ttl = pkr.ttl
	}
	ring := &namedKeyring{
		keyring: kr,
		parent:  parentId,
		name:    name,
		ttl:     ttl,
	}

	if ttl > 0 {
		if err := keyctl_SetTimeout(ring.id, ttl); err != nil {
			return nil, err
		}
	}

	return ring, nil
}

// Search for and open an existing keyring with the given name linked to a
// parent keyring (at any depth).
func OpenKeyring(parent Keyring, name string) (NamedKeyring, error) {
	parentId := keyId(parent.Id())
	id, err := searchKeyring(parentId, name, "keyring")
	if err != nil {
		return nil, err
	}

	return &namedKeyring{
		keyring: &keyring{id: id},
		parent:  parentId,
		name:    name,
	}, nil
}

// Set the time to live in seconds for an entire keyring and all of its keys.
// Only named keyrings can have their time-to-live set, the in-built keyrings
// cannot (Session, UserSession, etc).
func SetKeyringTTL(kr NamedKeyring, nsecs uint) error {
	err := keyctl_SetTimeout(keyId(kr.Id()), nsecs)
	if err == nil {
		kr.(*namedKeyring).ttl = nsecs
	}
	return err
}

// Link an object to a keyring.
func Link(parent Keyring, child Id) error {
	return keyctl_Link(keyId(child.Id()), keyId(parent.Id()))
}

// Unlink an object from a keyring.
func Unlink(parent Keyring, child Id) error {
	return keyctl_Unlink(keyId(child.Id()), keyId(parent.Id()))
}

// Unlink a named keyring from its parent.
func UnlinkKeyring(kr NamedKeyring) error {
	return keyctl_Unlink(keyId(kr.Id()), kr.(*namedKeyring).parent)
}

// Move a key from one keyring to another.
func Move(source Keyring, dest Keyring, child Id, excl bool) error {
	var flags uint
	if excl {
		flags = keyctlMoveExcl
	}
	return moveKey(keyId(child.Id()), keyId(source.Id()), keyId(dest.Id()), flags)
}

// AttachPersistent attaches the current executing context's persistent
// keyring to this keyring. See persistent-keyring(7) for more info.
// It returns either an error, or the persistent Keyring.
func (kr *keyring) AttachPersistent() (Keyring, error) {
	return attachPersistent(kr.id)
}