Query and manipulate the macOS Keychain
macos_item_* functions add, delete, update and search Keychain items.
macos_keychain_* functions create, delete, list, lock, unlock
keychains.
macos_item_classes() lists the supported Keychain item classes.
macos_item_attr() lists the supported attributes for these classes.
macos_item_match_options() lists the options supported by the
match argument of macos_item_search().
macos_item_classes()
macos_item(value, attributes = list(), class = "generic_password")
macos_item_add(item, keychain = NULL)
macos_item_search(
class = "generic_password",
attributes = list(),
match = list(),
return_data = FALSE,
keychain = NULL
)
macos_item_update(
class = "generic_password",
attributes = list(),
match = list(),
update = list(),
keychain = NULL
)
macos_item_delete(
class = "generic_password",
attributes = list(),
match = list(),
keychain = NULL
)
macos_keychain_create(keychain, password = NULL)
macos_keychain_list(domain = c("all", "user", "system", "common", "dynamic"))
macos_keychain_delete(keychain)
macos_keychain_lock(keychain = NULL)
macos_keychain_unlock(keychain = NULL, password = NULL)
macos_keychain_is_locked(keychain = NULL)
macos_item_attr()
macos_item_match_options()value |
Value of the item, a password, key or certificate. It must a raw vector or a string. If it is a string, then it is converted to UTF-8. |
attributes |
Narrow the search by indicating the attributes that the found item or items should have. |
class |
Type of items to search, see |
item |
Keychain item, creted via |
keychain |
Keychain to use. |
match |
Condition the search in a variety of ways. For example, you can limit the results to a specific number of items, control case sensitivity when matching string attributes, etc. See 'Search parameters' below. |
return_data |
Whether to include the secret data in the
search result. If this is set to |
update |
Named list specifying the new values of attributes. |
password |
Password to unlock the keychain, or new password to
set when creating a new keychain. May be |
domain |
The preference domain from which you wish to retrieve the keychain search list:
|
macos_item_classes() returns a character vector, the
names of the supported keychain item classes.
macos_item() returns a new oskeyring_macos_item
object.
macos_item_add() returns NULL, invisibly.
macos_item_search() returns a list of keychain items.
macos_item_update() returns NULL, invisibly.
macos_item_delete() returns NULL, invisibly.
macos_keychain_create() returns NULL, invisibly.
macos_keychain_list() returns a data frame with columns:
path: Path to the file of the keychain.
is_locked: Whether the keychain is locked.
is_readable: Whether the keychain is readable by the user.
is_writeable: Whether the keychain is writeable by the user.
macos_keychain_delete() returns NULL, invisibly.
macos_keychain_lock() returns NULL, invisibly.
macos_keychain_unlock() returns NULL, invisibly.
macos_keychain_is_locked() returns TRUE or FALSE.
macos_item_attr() returns a list of lists of character
scalars, the description of keychain item attributes, for each
keychain item class.
macos_item_match_options() returns a list of character
scalars, the description of the supported match options.
macos_item_classes() returns the currently supported Keychain item
classes.
macos_item_classes()
## [1] "generic_password" "internet_password"
macos_item() creates a new Keychain item. See the next section about
the attributes that are supported for the various item types.
it <- macos_item("secret", list(service = "My service", account = "Gabor"))
it
## <oskeyring_macos_item: generic_password> ## account: Gabor ## service: My service ## value: <-- hidden -->
macos_item_add() adds an item to the keychain. If there is already an
item with the same primary keys, then it will error.
macos_item_add(it)
macos_item_search() searches for Keychain items. If return_data is
TRUE then it also returns the secret data. Returning the secret data
might create a password entry dialog. If return_data is TRUE then
you need to set the limit match condition to a (small) finite number.
macos_item_search(attributes = list(service = "My service"))
## [[1]] ## <oskeyring_macos_item: generic_password> ## account: Gabor ## creation_date: 2020-09-23 09:58:29 ## label: My service ## modification_date: 2020-09-23 09:58:29 ## service: My service
macos_item_update() updates existing Keychain items.
macos_item_update( attributes = list(service = "My service", account = "Gabor"), update = list(account = "Gabor Csardi") ) macos_item_search(attributes = list(service = "My service"))
## [[1]] ## <oskeyring_macos_item: generic_password> ## account: Gabor Csardi ## creation_date: 2020-09-23 09:58:29 ## label: My service ## modification_date: 2020-09-23 09:58:29 ## service: My service
macos_item_delete() deletes one or more Keychain items. Note that
all matching items will be deleted.
macos_item_delete(attributes = list(service = "My service")) macos_item_search(attributes = list(service = "My service"))
## list()
The set of supported attributes depends on the class of the item.
oskeyring supports the following item classes currently: generic_password, internet_password.
A subset of the attributes form a primary key. It is not possible to add more than one item with the same primary key. See the primary keys for the various classes below.
oskeyring does not currently support all attributes that the Keychain Services AIP supports.
Some attributes are read-only. If you try to set them when adding or updating items, they will be ignored.
If an attribute is not included in the return value of
macos_item_search() then it is not set, and its default value is in
effect.
creation_date: [.POSIXct(1)][read-only] The date the item was created.
modification_date: [.POSIXct(1)][read-only] The last time the item was updated.
description: [character(1)] User-visible string describing this kind ofitem (for example, 'Disk image password').
comment: [character(1)] User-editable comment for this item.
label: [character(1)] User-visible label for this item.
is_invisible: [logical(1)] TRUE if the item is invisible (that is, should not be displayed).
is_negative: [logical(1)] Indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn't want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user.
account: [character(1)][key] Account name.
service: [character(1)][key] The service associated with this item.
generic: [character(1)] User-defined attribute.
synchronizable: [logical(1)] Indicates whether the item in question is synchronized to other devices through iCloud.
creation_date: [.POSIXct(1)][read-only] The date the item was created.
modification_date: [.POSIXct(1)][read-only] The last time the item was updated.
description: [character(1)] User-visible string describing this kind ofitem (for example, 'Disk image password').
comment: [character(1)] User-editable comment for this item.
label: [character(1)] User-visible label for this item.
is_invisible: [logical(1)] TRUE if the item is invisible (that is, should not be displayed).
is_negative: [logical(1)] Indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn't want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user.
account: [character(1)][key] Account name.
synchronizable: [logical(1)] Indicates whether the item in question is synchronized to other devices through iCloud.
security_domain: [character(1)][key] The item's security domain.
server: [character(1)][key] Contains the server's domain name or IP address.
protocol: [character(1)][key] The protocol for this item.
authentication_type: character[1][key] Authentication type.
port: [integer(1)][key] Internet port number.
path: [character(1)][key] A path, typically the path component of the URL
osxkeychain only supports a limited set of search parameters.
You can provide these for macos_item_search() as the match argument:
limit: [numeric(1)] This value specifies the maximum number of results to return or otherwise act upon. Use Inf to specify all matching items.
macOs supports multiple keychains.
There is always a default keychain, which is the user's login keychain,
unless configured differently.
There is also a keychain search list.
Keychains may belong into four non-exclusive categories, see the
domain argument of macos_keychain_list().
A keychain is stored in an encrypted file on the disk, see the first
column of the output of macos_keychain_list().
macos_item_*() functions have a keychain argument to direct or
restrict the operation to a single keychain only. These are the defaults:
macos_item_add() adds the item to the default keychain.
macos_item_search() searches all keychains in the search list.
macos_item_update() updates matching items on all keychains in the
search list.
macos_item_delete() deletes matching items from all keychains in the
search list.
macos_keychain_create() creates a new keychain.
macos_keychain_list() lists all keychains on the search list.
new <- "~/Library/Keychains/test.keychain-db" macos_keychain_create(new, password = "secret") macos_keychain_list()
## path is_unlocked ## 1 /Users/gaborcsardi/Library/Keychains/login.keychain-db TRUE ## 2 /Users/gaborcsardi/Library/Keychains/shiny.keychain-db FALSE ## 3 /Users/gaborcsardi/Library/Keychains/test.keychain-db TRUE ## 4 /Library/Keychains/System.keychain FALSE ## is_readable is_writeable ## 1 TRUE TRUE ## 2 TRUE FALSE ## 3 TRUE TRUE ## 4 TRUE FALSE
macos_keychain_lock() locks a keychain.
macos_keychain_unlock() unlocks a keychain.
macos_keychain_is_locked() checks if a keychain is locked.
macos_keychain_lock(new) macos_keychain_is_locked(new)
## [1] TRUE
macos_keychain_unlock(new, password = "secret") macos_keychain_is_locked(new)
## [1] FALSE
macos_keychain_delete() deletes a keychain: it removes it from the
search list and deletes the data from the disk. It currently refuses to
delete the user's login keychain and the system keychain. Use Keychain
Access instead if you want to delete these. (Only do this if you are
aware of the bad consequences.)
macos_keychain_delete(new) macos_keychain_list()
## path is_unlocked ## 1 /Users/gaborcsardi/Library/Keychains/login.keychain-db TRUE ## 2 /Users/gaborcsardi/Library/Keychains/shiny.keychain-db FALSE ## 3 /Library/Keychains/System.keychain FALSE ## is_readable is_writeable ## 1 TRUE TRUE ## 2 TRUE FALSE ## 3 TRUE FALSE
The Keychain Services API documentation at https://developer.apple.com/documentation/security/keychain_services.
# See above
Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.