README
¶
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 ¶
- Variables
- func Chgrp(k Id, group int) error
- func Chown(k Id, user int) error
- func Link(parent Keyring, child Id) error
- func NewReader(key *Key) io.Reader
- func OpenReader(name string, ring Keyring) (io.Reader, error)
- func SetKeyringTTL(kr NamedKeyring, nsecs uint) error
- func SetPerm(k Id, p KeyPerm) error
- func Unlink(parent Keyring, child Id) error
- func UnlinkKeyring(kr NamedKeyring) error
- type Flusher
- type Id
- type Info
- type Key
- type KeyPerm
- type Keyring
- type NamedKeyring
- type Reference
Constants ¶
This section is empty.
Variables ¶
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") )
var ErrStreamClosed = errors.New("keyctl write stream closed")
Error returned when attempting to close or flush an already closed stream
Functions ¶
func NewReader ¶
Returns an io.Reader interface object which will read the key's data from the kernel.
func OpenReader ¶
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 UnlinkKeyring ¶
func UnlinkKeyring(kr NamedKeyring) error
Unlink a named keyring from its parent.
Types ¶
type Flusher ¶
func CreateWriter ¶
Create a new key and stream writer with a given name on an open keyring.
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 ¶
Returns permissions in symbolic format.
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 ¶
To expire a key automatically after some period of time call this method.
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.
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 ProcessKeyring ¶
Return the keyring specific to the current executing process.
func SessionKeyring ¶
Return the current login session keyring
func ThreadKeyring ¶
Return the keyring specific to the current executing thread.
func UserSessionKeyring ¶
Return the current user-session keyring (part of session, but private to current user)
type NamedKeyring ¶
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 ¶
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 ¶
Loads the referenced keyctl object, which must either be a key or a keyring otherwise ErrUnsupportedKeyType will be returned.
Source Files
¶
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. |