Gnome.Keyring.Item

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 ItemInfo 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 AccessControl values.

Items

newtype ItemID

Constructors

ItemID Word32

Instances

Eq ItemID

Ord ItemID

Show ItemID

data ItemType

Constructors

ItemGenericSecret

ItemNetworkPassword

ItemNote

ItemChainedKeyringPassword

ItemEncryptionKeyPassword

ItemPublicKeyStorage

Instances

Eq ItemType

Show ItemType

itemCreate

Arguments

:: Maybe KeyringName

-> ItemType

-> Text

Display name

-> [Attribute]

-> Text

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 Nothing 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.

itemDelete :: Maybe KeyringName -> 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.

Item attributes

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

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

data Attribute

Constructors

TextAttribute Text Text

WordAttribute Text Word32

Instances

Eq Attribute

Show Attribute

attributeName :: Attribute -> Text

itemGetAttributes :: Maybe KeyringName -> ItemID -> Operation [Attribute]

Get all the attributes for an item.

itemSetAttributes :: Maybe KeyringName -> ItemID -> [Attribute] -> Operation ()

Set all the attributes for an item. These will replace any previous attributes set on the item.

Item info

data ItemInfoFlag

Constructors

ItemInfoBasics

ItemInfoSecret

Instances

Eq ItemInfoFlag

Show ItemInfoFlag

data ItemInfo

Note: setting mtime and ctime will not affect the keyring

Constructors

ItemInfo

Fields

itemType :: ItemType

itemSecret :: Maybe Text

itemDisplayName :: Maybe Text

itemMTime :: UTCTime

itemCTime :: UTCTime

Instances

Eq ItemInfo

Show ItemInfo

itemGetInfo :: Maybe KeyringName -> ItemID -> Operation ItemInfo

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.

itemGetInfoFull :: Maybe KeyringName -> ItemID -> Set ItemInfoFlag -> Operation ItemInfo

Get information about an item, optionally retrieving its secret.

If the flags include ItemInfoSecret, then the user may be prompted if the calling application doesn't have necessary access to read the item with its secret.

itemSetInfo :: Maybe KeyringName -> ItemID -> ItemInfo -> Operation ()

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

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

Access control

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 itemGetACL and itemSetACL.

data AccessControl

Constructors

AccessControl

Fields

accessControlName :: Maybe Text

accessControlPath :: Maybe Text

accessControlType :: Set AccessType

Instances

Eq AccessControl

Show AccessControl

data AccessType

Constructors

AccessRead

AccessWrite

AccessRemove

Instances

Eq AccessType

Ord AccessType

Show AccessType

itemGetACL :: Maybe KeyringName -> ItemID -> Operation [AccessControl]

Get the access control list for an item.

itemSetACL :: Maybe KeyringName -> ItemID -> [AccessControl] -> Operation ()

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

itemGrantAccessRights

Arguments

:: Maybe KeyringName

-> Text

Display name

-> Text

Application executable path

-> ItemID

-> Set AccessType

-> Operation ()

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

This is similar to performing itemGetACL and itemSetACL with appropriate parameters.

Searching for items

data FoundItem

Constructors

FoundItem

Fields

foundItemKeyring :: KeyringName

foundItemID :: ItemID

foundItemAttributes :: [Attribute]

foundItemSecret :: Text

Instances

Eq FoundItem

Show FoundItem

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.