security(1) BSD General Commands Manual security(1)NAMEsecurity — Command line interface to keychains and Security.framework
SYNOPSISsecurity [-hilqv] [-p prompt] [command] [command_options] [command_args]
DESCRIPTION
A simple command line interface which lets you administer Keychains,
manipulate keys and certificates, and do just about anything the Security
framework is capable of from the command line. New commands are con‐
stantly being added over time.
By default security will execute the command supplied and report if any‐
thing went wrong.
If the -i or -p options are provided, security will enter interactive
mode and allow the user to enter multiple commands on stdin. When EOF is
read from stdin security will exit.
Here is a complete list of the options available:
-h If no arguments are specified show a list of all commands. If
arguments are provided show usage for each the specified com‐
mands. This options is basically the same as the help command.
-i Run security in interactive mode. A prompt (security> by
default) will be displayed and the user will be able to type
commands on stdin until an EOF is encountered.
-l Before security exits run
/usr/bin/leaks -nocontext
on itself to see if the command(s) you executed leaks.
-p prompt
This option implies the -i option but changes the default prompt
to the argument specified instead.
-q Will make security less verbose.
-v Will make security more verbose.
SECURITY COMMAND SUMMARYsecurity provides a rich variety of commands (command in the SYNOPSIS),
each of which often has a wealth of options, to allow access to the broad
functionality provided by the Security framework. However, you don't
have to master every detail for security to be useful to you.
Here are brief descriptions of all the security commands:
help Show all commands. Or show usage for a command.
list-keychains Display or manipulate the keychain search list.
default-keychain Display or set the default keychain.
login-keychain Display or set the login keychain.
create-keychain Create keychains and add them to the search list.
delete-keychain Delete keychains and remove them from the search
list.
lock-keychain Lock the specified keychain.
unlock-keychain Unlock the specified keychain.
set-keychain-settings Set Nm settings for a keychain.
show-keychain-info Show the settings for keychain.
dump-keychain Dump the contents of one or more keychains.
create-keypair Create an assymetric keypair.
add-internet-password Add an internet password item.
add-certificates Add certificates to a keychain.
find-internet-password Find an internet password item.
find-certificate Find a certificate item.
create-db Create an db using the DL.
leaks Run /usr/bin/leaks on this proccess.
COMMON COMMAND OPTIONS
This section describes the command_options that are available across all
security commands.
-h Show a usage message for the specified command. This option is
basically the same as the help command.
SECURITY COMMANDS
Here (finally) are details on all the security commands and the options
each accepts.
help [-h]
Show all commands. Or show usage for a command.
list-keychains [-h] [-d user|system|common] [-s [keychain...]]
Display or set the keychain search list.
Options:
-d user|system|common
Specify the preferences domain to be used.
-s Set the search list to the specified keychains
default-keychain [-h] [-d user|system|common] [-s [keychain]]
Display or set the default keychain.
Options:
-d user|system|common
Specify the preferences domain to be used.
-s Set the default keychain to the specified keychain.
Unset it if no keychain is specified.
login-keychain [-h] [-d user|system|common] [-s [keychain]]
Display or set the login keychain.
Options:
-d user|system|common
Specify the preferences domain to be used.
-s Set the login keychain to the specified keychain. Unset
it if no keychain is specified.
create-keychain [-hP] [-p password] [keychain...]
Create keychains and add them to the search list. if no keychains
are specified the user is prompted for one.
Options:
-P Prompt the user for a password using the Secu‐
rityAgent.
-p password Use password as the password for the keychains
being created.
If neither -P or -p password are specified the user is prompted
for a password.
delete-keychain [-h] [keychain...]
Delete keychains and remove them from the search list.
lock-keychain [-h] [-a|keychain]
Lock keychain. Or the default is none is specified. If the -a
options is specified all keychains are locked.
unlock-keychain [-hu] [-p password] [keychain]
Unlock keychain. Or the default is none is specified.
set-keychain-settings [-hlu] [-t timeout] [keychain]
Set settings for keychain. Or the default is none is specified.
-l Lock keychain when the system sleeps
-u Lock keychain after certain period of time speci‐
fied using -t.
-t timeout Automatically lock keychain after timeout seconds
of inactivity.
show-keychain-info [-h]
Show the settings for keychain.
dump-keychain [-dhr]
Dump the contents of one or more keychains.
-d Dump cleartext data of items.
-r Dump raw (possibly ciphertext) data of items.
create-keypair [-h] [-a alg] [-s size] [-f from_date] [-t to_date] [-v
days] [-k keychain] [-n name] [-A|-T app1:app2:...]
Create an assymetric keypair.
add-internet-password [-h] [-a account_name] [-d security_domain] [-p
path] [-P port] [-r protocol] [-s server_name] [-t authentication_type]
[-w password_data] [keychain]
Add an internet password item.
add-certificates [-h] [-k keychain] file...
Add certficates contained in the specified files to the default
keychain. The files must contain one DER encoded X509 certificate
each.
-k keychain Use keychain rather than the default keychain.
find-internet-password [-gh] [-a account_name] [-d security_domain] [-p
path] [-P port] [-r protocol] [-s server_name] [-t authentication_type]
[keychain...]
Find an internet password item.
find-certificate [-ahmp] [-e email_address] [keychain...]
Find a certificate item. If no keychain arguments are provided,
security will search the default search list.
Options:
-a Find all matching certificates, not just the first
one.
-g dl|cspdl Use the AppleDL (default) or AppleCspDL
-e email_address
Match on "email_address" when searching.
-m Show the email addresses in the certificate.
-p Output certificate in pem form. The default is to
dump the attributes and keychain the cert is in.
Examples
security> find-certificate -a -p > allcerts.pem
Exports all certificates from all keychains into a pem file called
allcerts.pem.
security> find-certificate -a -e me@foo.com -p > certs.pem
Exports all certificates from all keychains with the email address
mb@foo.com into a pem file called certs.pem.
create-db [-aho0] [-g dl|cspdl] [-m mode] [name]
Create an db using the DL. If name isn't provided security will prompt
the user to type a name.
Options:
-a Turn off autocommit
-g dl|cspdl Use the AppleDL (default) or AppleCspDL
-m mode Set the file permissions to mode.
-o Force using openparams argument
-0 Force using version 0 openparams
Examples
security> create-db -m 0644 test.db
security> create-db -g cspdl -a test2.db
leaks [-h] [-cycles] [-nocontext] [-nostacks] [-exclude symbol]
Run /usr/bin/leaks on this proccess. This is to help find memory leaks
after running certain commands.
Options:
-cycles Use a stricter algorithm (See leaks(1) for details).
-nocontext Withhold the hex dumps of the leaked memory.
-nostacks Don't show stack traces of leaked memory.
-exclude symbol
Ignore leaks called from symbol.
ENVIRONMENT
MallocStackLogging
When using the leaks command or the -l option it's probably a
good idea to set this environment variable before security is
started. Doing so will allow leaks to display symbolic back‐
traces.
FILES
~/Library/Preferences/com.apple.security.plist
Propertylist file containing the current users default keychain
and keychain search list.
/Library/Preferences/com.apple.security.plist
Propertylist file containing the system default keychain and
keychain search list. This is used by processes started at
boottime, or those requesting to use the system search domain,
such as system daemons.
/Library/Preferences/com.apple.security-common.plist
Propertylist file containing the a common keychain search list
which is appended to every users searchlist and to the system
search list as well.
SEE ALSOcerttool(1), leaks(1)HISTORYsecurity was first introduced in Mac OS X version 10.3
AUTHORS
Michael Brouwer
BUGSsecurity still needs a lot more commands before it can be considered com‐
plete. In paticular it should someday superceed both the certtool and
systemkeychain commands.
Darwin May 4, 2024 Darwin