Portability | non-portable (FFI) |
---|---|
Stability | experimental |
Maintainer | John Millikin <jmillikin@gmail.com> |
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.
- newtype ItemID = ItemID Word32
- data ItemType
- itemCreate :: Maybe KeyringName -> ItemType -> Text -> [Attribute] -> Text -> Bool -> Operation ItemID
- itemDelete :: Maybe KeyringName -> ItemID -> Operation ()
- data Attribute
- attributeName :: Attribute -> Text
- itemGetAttributes :: Maybe KeyringName -> ItemID -> Operation [Attribute]
- itemSetAttributes :: Maybe KeyringName -> ItemID -> [Attribute] -> Operation ()
- data ItemInfoFlag
- data ItemInfo = ItemInfo {}
- itemGetInfo :: Maybe KeyringName -> ItemID -> Operation ItemInfo
- itemGetInfoFull :: Maybe KeyringName -> ItemID -> Set ItemInfoFlag -> Operation ItemInfo
- itemSetInfo :: Maybe KeyringName -> ItemID -> ItemInfo -> Operation ()
- data AccessControl = AccessControl {}
- data AccessType
- itemGetACL :: Maybe KeyringName -> ItemID -> Operation [AccessControl]
- itemSetACL :: Maybe KeyringName -> ItemID -> [AccessControl] -> Operation ()
- itemGrantAccessRights :: Maybe KeyringName -> Text -> Text -> ItemID -> Set AccessType -> Operation ()
- data FoundItem = FoundItem {}
- findItems :: ItemType -> [Attribute] -> Operation [FoundItem]
Items
:: 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 ()Source
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.
attributeName :: Attribute -> TextSource
itemGetAttributes :: Maybe KeyringName -> ItemID -> Operation [Attribute]Source
Get all the attributes for an item.
itemSetAttributes :: Maybe KeyringName -> ItemID -> [Attribute] -> Operation ()Source
Set all the attributes for an item. These will replace any previous attributes set on the item.
Item info
Note: setting mtime and ctime will not affect the keyring
itemGetInfo :: Maybe KeyringName -> ItemID -> Operation ItemInfoSource
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 ItemInfoSource
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 ()Source
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 AccessType Source
itemGetACL :: Maybe KeyringName -> ItemID -> Operation [AccessControl]Source
Get the access control list for an item.
itemSetACL :: Maybe KeyringName -> ItemID -> [AccessControl] -> Operation ()Source
Set the full access control list on an item. This replaces any previous ACL set on the item.
:: 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.