Gnome.Keyring

The GNOME Keyring is a service for securely storing per-user secret information, such as passwords and encryption keys. This library is a binding to the libgnome-keyring C library.

Documentation for the original library is available at http://library.gnome.org/devel/gnome-keyring/stable/

Service status

available :: IO Bool

Check whether the client can communicate with the GNOME Keyring service.

Items

A keyring contains multiple items. Each item has a secret, attributes and access information associated with it.

An item is identified by an ItemID unique to the keyring in which it exists. An item's name is for displaying to the user. Each item has a single secret, which is Unicode text. This secret is stored in non-pageable memory in the server, and encrypted on disk. All of this information is exposed via Item values.

Note that the underlying C library stores secrets in non-pageable memory, but the Haskell bindings currently do not.

Attributes allow various other pieces of information to be associated with an item. These can also be used to search for relevant items.

Each item has an access control list, which specifies which applications may read, write or delete an item. The read access applies only to reading the secret. All applications can read other parts of the item. ACLs are accessed and changed through Access values.

data ItemID

Instances

Eq ItemID

Ord ItemID

Show ItemID

data ItemType

Constructors

ItemGenericSecret

ItemNetworkPassword

ItemNote

ItemChainedKeyringPassword

ItemEncryptionKeyPassword

ItemPublicKeyStorage

ItemApplicationSecret

Instances

Eq ItemType

Show ItemType

createItem

Arguments

:: Keyring

-> ItemType

-> String

Display name

-> [Attribute]

-> String

The secret

-> Bool

Update an existing item, if one exists.

-> Operation ItemID

Create a new item in a keyring.

The user may have been prompted to unlock necessary keyrings. If defaultKeyring is specified as the keyring and no default keyring exists, the user will be prompted to create a new keyring.

If an existing item should be updated, the user may be prompted for access to the existing item.

Whether a new item is created or not, the ID of the item will be returned.

deleteItem :: Keyring -> ItemID -> Operation ()

Delete an item in a keyring.

The user may be prompted if the calling application doesn't have necessary access to delete the item.

listItemIDs :: Keyring -> Operation [ItemID]

Get a list of all the IDs for items in the keyring. All items which are not flagged as ItemApplicationSecret are included in the list. This includes items that the calling application may not (yet) have access to.

Item info

data Item

Instances

Eq Item

Show Item

getItem

Arguments

:: Keyring

-> Bool

Whether to read the secret.

-> ItemID

-> Operation Item

Get information about an item and its secret.

The user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

setItem :: Keyring -> ItemID -> Item -> Operation ()

Set information on an item, like its display name, secret, etc.

Only the fields in the Item which are not Nothing or non-zero will be set on the item.

itemType :: Item -> ItemType

Get or set the item's type.

itemSecret :: Item -> Maybe String

Get or set the item's secret.

itemDisplayName :: Item -> Maybe String

Get or set the item's display name.

itemModified :: Item -> UTCTime

Get when the item was last modified.

itemCreated :: Item -> UTCTime

Get when the item was created.

Item attributes

data Attribute

Attributes allow various other pieces of information to be associated with an item. These can also be used to search for relevant items. Use getItemAttributes or setItemAttributes to manipulate attributes in the keyring.

Each attribute is either Unicode text, or an unsigned 32-bit integer.

Constructors

TextAttribute String String

WordAttribute String Word32

Instances

Eq Attribute

Show Attribute

attributeName :: Attribute -> String

getItemAttributes :: Keyring -> ItemID -> Operation [Attribute]

Get all the attributes for an item.

setItemAttributes :: Keyring -> ItemID -> [Attribute] -> Operation ()

Set all the attributes for an item. These will replace any existing attributes.

Access control

data Access

Each item has an access control list, which specifies which applications may read, write or delete an item. The read access applies only to reading the secret. All applications can read other parts of the item. ACLs are accessed and changed with getItemAccess and setItemAccess.

Constructors

Access

Fields

accessName :: Maybe String

accessPath :: Maybe String

accessType :: [AccessType]

Instances

Eq Access

Show Access

data AccessType

Constructors

AccessRead

AccessWrite

AccessRemove

Instances

Eq AccessType

Ord AccessType

Show AccessType

getItemAccess :: Keyring -> ItemID -> Operation [Access]

Get the access control list for an item.

setItemAccess :: Keyring -> ItemID -> [Access] -> Operation ()

Set the full access control list on an item. This replaces any previous ACL set on the item.

grantItemAccess

Arguments

:: Keyring

-> String

Display name

-> String

Application executable path

-> ItemID

-> [AccessType]

-> Operation ()

Will grant the application access rights to the item, provided callee has write access to said item.

This is similar to performing getItemAccess and setItemAccess with appropriate parameters.

Searching for items

data FoundItem

Instances

Eq FoundItem

Show FoundItem

foundItemKeyring :: FoundItem -> Keyring

Get which keyring the item was found in.

foundItemID :: FoundItem -> ItemID

Get the found item's ID.

foundItemAttributes :: FoundItem -> [Attribute]

Get the found item's attributes.

foundItemSecret :: FoundItem -> String

Get the found item's secret.

findItems :: ItemType -> [Attribute] -> Operation [FoundItem]

Searches through all keyrings for items that match the attributes. The matches are for exact equality.

The user may be prompted to unlock necessary keyrings, and will be prompted for access to the items if needed.

Returns an empty list if no items were found.

Keyrings

data Keyring

GNOME Keyring manages multiple keyrings. Each keyring can store one or more items, containing secrets.

Each keyring can be in a locked or unlocked state. A password must be specified, either by the user or the calling application, to unlock the keyring.

Instances

Eq Keyring

Show Keyring

defaultKeyring :: Keyring

sessionKeyring :: Keyring

keyring :: String -> Keyring

Basic operations

getDefaultKeyring :: Operation (Maybe String)

Get the name of the default keyring. If no keyring is the default, returns Nothing.

setDefaultKeyring :: String -> Operation ()

Change the default keyring.

listKeyringNames :: Operation [String]

Get a list of keyring names. If no keyrings exist, an empty list will be returned.

createKeyring

Arguments

:: String

Keyring name

-> Maybe String

Keyring password, or Nothing to prompt the user.

-> Operation ()

Create a new keyring with the specified name. In most cases, Nothing will be passed as the password, which will prompt the user to enter a password of their choice.

deleteKeyring :: String -> Operation ()

Delete a keyring. Once a keyring is deleted, there is no mechanism for recovery of its contents.

changeKeyringPassword

Arguments

:: String

Keyring name

-> Maybe String

Old password, or Nothing to prompt the user.

-> Maybe String

New password, or Nothing to prompt the user.

-> Operation ()

Change the password for a keyring. In most cases, Nothing would be specified for both the original and new passwords to allow the user to type both.

Locking and unlocking keyrings

lockKeyring :: Keyring -> Operation ()

Lock a keyring, so that its contents may not be accessed without first supplying a password.

Most keyring operations involving items require that the keyring first be unlocked. One exception is findItems and related computations.

unlockKeyring :: Keyring -> Maybe String -> Operation ()

Unlock a keyring, so that its contents may be accessed. In most cases, Nothing will be specified as the password, which will prompt the user to enter the correct password.

Most keyring operations involving items require that the keyring first be unlocked. One exception is findItems and related computations.

lockAll :: Operation ()

Lock all the keyrings, so that their contents may not be accessed without first unlocking them with a password.

Keyring information

data KeyringInfo

Instances

Show KeyringInfo

keyringLockOnIdle :: KeyringInfo -> Bool

Get or set whether the keyring should be locked when idle.

keyringLockTimeout :: KeyringInfo -> Word32

Get or set the keyring lock timeout.

keyringModified :: KeyringInfo -> UTCTime

Get when the keyring was last modified.

keyringCreated :: KeyringInfo -> UTCTime

Get when the keyring was created.

keyringIsLocked :: KeyringInfo -> Bool

Get whether the keyring is locked.

getKeyringInfo :: Keyring -> Operation KeyringInfo

Get information about the keyring.

setKeyringInfo :: Keyring -> KeyringInfo -> Operation ()

Set flags and info for the keyring. The only fields in the KeyringInfo which may be modified are keyringLockOnIdle and keyringLockTimeout.

Network passwords

data NetworkPassword

Networks passwords are a simple way of saving passwords associated with a certain user, server, protocol, and other fields.

Instances

Eq NetworkPassword

Show NetworkPassword

networkPasswordKeyring :: NetworkPassword -> Keyring

Get which keyring the password is stored in.

networkPasswordSecret :: NetworkPassword -> String

Get the network password's secret value.

networkPasswordItemID :: NetworkPassword -> ItemID

Get the ID of the network password's keyring item.

networkPasswordNetwork :: NetworkPassword -> Network

Get the network location metadata associated with the network password.

data Network

A set of predicates to store with a NetworkPassword, used to find the password later.

Instances

Eq Network

Show Network

network :: Network

A Network with no set fields.

networkProtocol :: Network -> Maybe String

Get or set the network protocol.

networkServer :: Network -> Maybe String

Get or set the network server name.

networkObject :: Network -> Maybe String

Get or set the network object.

networkAuthType :: Network -> Maybe String

Get or set the type of authentication.

networkPort :: Network -> Word32

Get or set the network port. A port of 0 is considered blank.

networkUser :: Network -> Maybe String

Get or set the network user name.

networkDomain :: Network -> Maybe String

Get or set the network domain name.

findNetworkPassword :: Network -> Operation [NetworkPassword]

Find a previously stored NetworkPassword. Searches all keyrings.

The user may be prompted to unlock necessary keyrings, and will be prompted for access to the items if needed.

Network passwords are items with the ItemType ItemNetworkPassword.

Returns an empty list if no items were found.

setNetworkPassword :: Keyring -> Network -> String -> Operation ItemID

Store a network password.

If an item already exists for with this network info (ie: user, server, etc.) then it will be updated.

Whether a new item is created or not, the item's ID will be returned.

Network passwords are items with the ItemType ItemNetworkPassword.

Operations

data Operation a

A keyring operation can be run synchronously or asynchronously. Asynchronous execution requires a running GLib event loop.

data KeyringError

Instances

Eq KeyringError

Show KeyringError

keyringErrorMessage :: KeyringError -> String

sync :: Operation a -> IO (Either KeyringError a)

Runs an operation synchronously, and returns either the result or an error.

Running an operation synchronously does not require a GLib event loop to be active.

sync_ :: Operation a -> IO a

Runs an operation synchronously. If it succeeded, returns the result. Otherwise, throws a KeyringError.

Running an operation synchronously does not require a GLib event loop to be active.

async :: Operation a -> (KeyringError -> IO ()) -> (a -> IO ()) -> IO CancellationKey

Runs an operation asynchronously, calling one of the given callbacks on success or failure.

The returned CancellationKey can be used to cancel a pending operation.

Running an operation asynchronously requires a running GLib event loop.

data CancellationKey

cancel :: CancellationKey -> IO ()

Cancel a running asynchronous operation. The error callback will be called with a KeyringError stating that the operation was canceled.