keyctl

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 18, 2021 License: BSD-3-Clause Imports: 9 Imported by: 13

README

GoDoc Build Status

keyctl

A native Go API for the security key management system (aka "keyrings") found in Linux 2.6+

The keyctl interface is nominally provided by three or so Linux-specific syscalls, however it is almost always wrapped in a library named libkeyutils.so.

This package interacts directly with the syscall interface and does not require CGO for linkage to the helper library provided on most systems.

Example Usages

To access the default session keyring (and create it if it doesn't exist)

package main
   
import (
  "log"
  "github.com/jsipprell/keyctl"
)
    
func main() {
  keyring, err := keyctl.SessionKeyring()
  if err != nil {
    log.Fatal(err)
  }
      
  // default timeout of 10 seconds for new or updated keys
  keyring.SetDefaultTimeout(10)
  secureData := []byte{1,2,3,4}
  id, err := keyring.Add("some-data", secureData)
  if err != nil {
    log.Fatal(err)
  }
  log.Printf("created session key id %v", id)
}

To search for an existing key by name:

package main

import (
  "log"
  "github.com/jsipprell/keyctl"
)

func main() {
  keyring, err := keyctl.SessionKeyring()
  if err != nil {
    log.Fatal(err)
  }
  key, err := keyring.Search("some-data")
  if err != nil {
    log.Fatal(err)
  }
 
  data, err := key.Get()
  if err != nil {
    log.Fatal(err)
  }
  log.Printf("secure data: %v\n", data)
}

Documentation

Overview

A Go interface to linux kernel keyrings (keyctl interface)

Index

Constants

This section is empty.

Variables

View Source
var (
	// Error returned if the Get() method is called on a Reference that doesn't
	// represent a key or keychain.
	ErrUnsupportedKeyType = errors.New("unsupported keyctl key type")
	// Error returned if a reference is stale when Info() or Get() is called on
	// it.
	ErrInvalidReference = errors.New("invalid keyctl reference")
)
View Source
var ErrStreamClosed = errors.New("keyctl write stream closed")

Error returned when attempting to close or flush an already closed stream

Functions

func Chgrp

func Chgrp(k Id, group int) error

Change group ownership on a key or keyring.

func Chown

func Chown(k Id, user int) error

Change user ownership on a key or keyring.

func Link(parent Keyring, child Id) error

Link an object to a keyring

func NewReader

func NewReader(key *Key) io.Reader

Returns an io.Reader interface object which will read the key's data from the kernel.

func OpenReader

func OpenReader(name string, ring Keyring) (io.Reader, error)

Open an existing key on a keyring given its name

func SetKeyringTTL

func SetKeyringTTL(kr NamedKeyring, nsecs uint) error

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 SetPerm

func SetPerm(k Id, p KeyPerm) error

Set permissions on a key or keyring.

func Unlink(parent Keyring, child Id) error

Unlink an object from a keyring

func UnlinkKeyring

func UnlinkKeyring(kr NamedKeyring) error

Unlink a named keyring from its parent.

Types

type Flusher

type Flusher interface {
	io.Writer
	io.Closer
	Flush() error
}

func CreateWriter

func CreateWriter(name string, ring Keyring) (Flusher, error)

Create a new key and stream writer with a given name on an open keyring.

func NewWriter

func NewWriter(key *Key) Flusher

Create a new stream writer to write key data to. The writer MUST Close() or Flush() the stream before the data will be flushed to the kernel.

type Id

type Id interface {
	Id() int32
	Info() (Info, error)
	// contains filtered or unexported methods
}

All Keys and Keyrings have unique 32-bit serial number identifiers.

type Info

type Info struct {
	Type, Name string
	Uid, Gid   int
	Perm       KeyPerm
	// contains filtered or unexported fields
}

Information about a keyctl reference as returned by ref.Info()

func (Info) Permissions

func (i Info) Permissions() string

Returns permissions in symbolic format.

func (Info) Valid

func (i Info) Valid() bool

Returns true if the Info fetched by ref.Info() is valid.

type Key

type Key struct {
	Name string
	// contains filtered or unexported fields
}

Represents a single key linked to one or more kernel keyrings.

func (*Key) ExpireAfter

func (k *Key) ExpireAfter(nsecs uint) error

To expire a key automatically after some period of time call this method.

func (*Key) Get

func (k *Key) Get() ([]byte, error)

Get the key's value as a byte slice

func (*Key) Id

func (k *Key) Id() int32

Returns the 32-bit kernel identifier for a specific key

func (*Key) Info

func (k *Key) Info() (Info, error)

Return information about a key.

func (*Key) Set

func (k *Key) Set(b []byte) error

Set the key's value from a bytes slice. Expiration, if active, is reset by calling this method.

func (k *Key) Unlink() error

Unlink a key from the keyring it was loaded from (or added to). If the key is not linked to any other keyrings, it is destroyed.

type KeyPerm

type KeyPerm uint32

KeyPerm represents in-kernel access control permission to keys and keyrings as a 32-bit integer broken up into four permission sets, one per byte. In MSB order, the perms are: Processor, User, Group, Other.

const (
	PermOtherView KeyPerm = 1 << iota
	PermOtherRead
	PermOtherWrite
	PermOtherSearch
	PermOtherLink
	PermOtherSetattr
)
const (
	PermGroupView KeyPerm = 1 << (8 + iota)
	PermGroupRead
	PermGroupWrite
	PermGroupSearch
	PermGroupLink
	PermGroupSetattr
)
const (
	PermUserView KeyPerm = 1 << (16 + iota)
	PermUserRead
	PermUserWrite
	PermUserSearch
	PermUserLink
	PermUserSetattr
)
const (
	PermProcessView KeyPerm = 1 << (24 + iota)
	PermProcessRead
	PermProcessWrite
	PermProcessSearch
	PermProcessLink
	PermProcessSetattr
)
const (
	PermOtherAll KeyPerm = 0x3f << (8 * iota)
	PermGroupAll
	PermUserAll
	PermProcessAll
)

func (KeyPerm) Group

func (p KeyPerm) Group() string

Returns the group permissions in symbolic form

func (KeyPerm) Other

func (p KeyPerm) Other() string

Returns other (default) permissions in symbolic form

func (KeyPerm) Process

func (p KeyPerm) Process() string

Returns processor permissions in symbolic form

func (KeyPerm) String

func (p KeyPerm) String() string

func (KeyPerm) User

func (p KeyPerm) User() string

Returns the user permissions in symbolic form

type Keyring

type Keyring interface {
	Id
	Add(string, []byte) (*Key, error)
	Search(string) (*Key, error)
	SetDefaultTimeout(uint)
}

Basic interface to a linux keyctl keyring.

func GroupKeyring

func GroupKeyring() (Keyring, error)

Return the current group keyring.

func ProcessKeyring

func ProcessKeyring() (Keyring, error)

Return the keyring specific to the current executing process.

func SessionKeyring

func SessionKeyring() (Keyring, error)

Return the current login session keyring

func ThreadKeyring

func ThreadKeyring() (Keyring, error)

Return the keyring specific to the current executing thread.

func UserSessionKeyring

func UserSessionKeyring() (Keyring, error)

Return the current user-session keyring (part of session, but private to current user)

type NamedKeyring

type NamedKeyring interface {
	Keyring
	Name() string
}

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.

func CreateKeyring

func CreateKeyring(parent Keyring, name string) (NamedKeyring, error)

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 OpenKeyring

func OpenKeyring(parent Keyring, name string) (NamedKeyring, error)

Search for and open an existing keyring with the given name linked to a parent keyring (at any depth).

type Reference

type Reference struct {
	// Id is the kernel key or keychain identifier referenced.
	Id int32
	// contains filtered or unexported fields
}

Reference is a reference to an unloaded keyctl Key or Keychain. It can be dereferenced by calling the Get() method.

func ListKeyring

func ListKeyring(kr Keyring) ([]Reference, error)

List the contents of a keyring. Each contained object is represented by a Reference struct. Addl information is available by calling ref.Info(), and contained objects which are keys or subordinate keyrings can be fetched by calling ref.Get()

func (*Reference) Get

func (r *Reference) Get() (Id, error)

Loads the referenced keyctl object, which must either be a key or a keyring otherwise ErrUnsupportedKeyType will be returned.

func (*Reference) Info

func (r *Reference) Info() (i Info, err error)

Return Information about a keyctl reference.

func (*Reference) Valid

func (r *Reference) Valid() bool

Returns true if the keyctl reference is valid. Refererences can become invalid if they have expired since the reference was created.

Directories

Path Synopsis
Provides a keyring with an openpgp.ReadMessage wrapper method that when called will automatically attempt private key decryption and save the passphrase in the private session kernel keyring for a configurable amount of time.
Provides a keyring with an openpgp.ReadMessage wrapper method that when called will automatically attempt private key decryption and save the passphrase in the private session kernel keyring for a configurable amount of time.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL