security(1)

NAME
security - Command line interface to keychains and Security.framework

SYNOPSIS
security [-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 constantly being added over time.

By default security will execute the command supplied and report if anything 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 commands. 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 SUMMARY
security 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.
import
    Import item(s) into a keychain.
export
    Export item(s) from a keychain.
install-mds
    Install (or re-install) the MDS database.
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 SecurityAgent.
-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 specified using -t .
-t timeout
    Automatically lock keychain after timeout seconds of inactivity.

show-keychain-info [-h]
Show the settings for keychain.

dump-keychain [-adhir]
Dump the contents of one or more keychains.
-a  Dump acl of items.
-d  Dump cleartext data of items.
-i  Interactive acl editing mode.
-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

export [-k keychain] [-t item_type] [-f item_format] [-w] [-p item_format] [-P passphrase] [-o outfile]
Export one or more items from a keychain to one of a number of external representations. If keychain isn't provided, items will be exported from the user's default keychain.

Options:
-k keychain
    Specify keychain from which item(s) will be exported.
-t item_type
    Specify the type of items to export. Possible types are certs, allKeys, pubKeys, privKeys, identities, and all. The default is all. An identity consists of both a certificate and the corresponding provate key.
-f item_format
    Specify the format of the exported data. Possible formats are openssl, bsafe, pkcs7, pkcs8, pkcs12, x509, and pemseq. The default is pemseq if more than one item is being exported. The default is openssl if one key is being exported. The default is x509 if one certificate is being exported.
-w  Specifies that private keys are to be wrapped on export.
-p  Specifies that PEM armour is to be applied to the output data.
-P passphrase
    Specify the wrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.
-o outfile
    Write the output data to outfile . Default is to write data to stdout.

Examples
    security> export -k login.keychain -t certs -o /tmp/certs.pem
    security> export -k newcert.keychain -t identities -f pkcs12 -o /tmp/mycerts.p12

import inputfile [-k keychain] [-t item_type] [-f item_format] [-w] [-P passphrase]
Import one or more items from inputfile into a keychain. If keychain isn't provided, items will be imported into the user's default keychain.

Options:
-k keychain
    Specify keychain into which item(s) will be imported.
-t item_type
    Specify the type of items to import. Possible types are cert, pub, priv, session, cert, and agg. Pub, priv, and session refer to keys; agg is one of the aggregate types (pkcs12 and PEM sequence). The command can often figure out what item_type an item contains based in the filename and/or item_format.
-f item_format
    Specify the format of the exported data. Possible formats are openssl, bsafe, raw, pkcs7, pkcs8, pkcs12, x509, and pemseq. The command can often figure out what format an item is in based in the filename and/or item_type.
-w  Specifies that private keys are wrapped and must be unwrapped on import.
-P passphrase
    Specify the unwrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.

Examples
    security> import /tmp/certs.pem -k
    security> import /tmp/mycerts.p12 -t agg -k newcert.keychain
    security> import /tmp/mycerts.p12 -f pkcs12 -k newcert.keychain

install-mds
Install (or re-install) the Module Directory Services (MDS) database. This is a system tool which is not normally used by users. There are no options.

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

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 ALSO
certtool(1), leaks(1)

HISTORY
security was first introduced in Mac OS X version 10.3

AUTHORS
Michael Brouwer

BUGS
security still needs a lot more commands before it can be considered complete. In particular it should someday supersede both the certtool and systemkeychain commands.