sec/SecurityTool/security.1

   1 .\"Modified from man(1) of FreeBSD, the NetBSD mdoc.template, and mdoc.samples.
   2 .\"See Also:
   3 .\"man mdoc.samples for a complete listing of options
   4 .\"man mdoc for the short list of editing options
   5 .Dd Tue May 06 2003               \" DATE
   6 .Dt security 1      \" Program name and manual section number
   7 .Os Darwin
   8 .Sh NAME                 \" Section Header - required - don't modify
   9 .Nm security
  10 .\" The following lines are read in generating the apropos(man -k) database. Use only key
  11 .\" words here as the database is built based on the words here and in the .ND line.
  12 .\" Use .Nm macro to designate other names for the documented program.
  13 .Nd Command line interface to keychains and Security.framework
  14 .Sh SYNOPSIS             \" Section Header - required - don't modify
  15 .Nm
  16 .Op Fl hilqv             \" [-hilqv]
  17 .Op Fl p Ar prompt       \" [-p prompt]
  18 .Op Ar command           \" [command]
  19 .Op Ar command_options   \" [command_options]
  20 .Op Ar command_args      \" [command_args]
  21 .Sh DESCRIPTION          \" Section Header - required - don't modify
  22 A simple command line interface which lets you administer Keychains,
  23 manipulate keys and certificates, and do just about anything the
  24 Security framework is capable of from the command line.  New commands
  25 are constantly being added over time.
  26 .Pp
  27 By default
  28 .Nm
  29 will execute the
  30 .Ar command
  31 supplied and report if anything went wrong.
  32 .Pp
  33 If the
  34 .Fl i
  35 or
  36 .Fl p
  37 options are provided,
  38 .Nm
  39 will enter interactive mode and allow the user to enter multiple commands on stdin.  When EOF is read from stdin
  40 .Nm
  41 will exit.
  42 .Pp
  43 Here is a complete list of the options available:
  44 .Bl -tag -width -indent
  45 .It Fl h
  46 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
  47 .Nm help
  48 command.
  49 .It Fl i
  50 Run
  51 .Nm
  52 in interactive mode.  A prompt
  53 .Po
  54 .Li security>
  55 by default
  56 .Pc
  57 will be displayed and the user will be able to type commands on stdin until an EOF is encountered.
  58 .It Fl l
  59 Before
  60 .Nm
  61 exits run
  62 .Dl "/usr/bin/leaks -nocontext"
  63 on itself to see if the command(s) you executed leaks.
  64 .It Fl p Ar prompt
  65 This option implies the
  66 .Fl i
  67 option but changes the default prompt to the argument specified instead.
  68 .It Fl q
  69 Will make
  70 .Nm
  71 less verbose.
  72 .It Fl v
  73 Will make
  74 .Nm
  75 more verbose.
  76 .El                      \" Ends the list
  77 .Pp
  78 .Sh "SECURITY COMMAND SUMMARY"
  79 .Nm
  80 provides a rich variety of commands
  81 .Po Ar command
  82 in the
  83 .Sx SYNOPSIS Pc Ns
  84 , each of which often has a wealth of options, to allow access to
  85 the broad functionality provided by the Security framework.  However,
  86 you don't have to master every detail for
  87 .Nm
  88 to be useful to you.
  89 .Pp
  90 Here are brief descriptions of all the
  91 .Nm
  92 commands:
  93 .Pp
  94 .Bl -tag -width find-internet-password -compact
  95 .It Nm help
  96 Show all commands. Or show usage for a command.
  97 .It Nm list-keychains
  98 Display or manipulate the keychain search list.
  99 .It Nm default-keychain
 100 Display or set the default keychain.
 101 .It Nm login-keychain
 102 Display or set the login keychain.
 103 .It Nm create-keychain
 104 Create keychains and add them to the search list.
 105 .It Nm delete-keychain
 106 Delete keychains and remove them from the search list.
 107 .It Nm lock-keychain
 108 Lock the specified keychain.
 109 .It Nm unlock-keychain
 110 Unlock the specified keychain.
 111 .It Nm set-keychain-settings
 112 Set Nm settings for a keychain.
 113 .It Nm show-keychain-info
 114 Show the settings for keychain.
 115 .It Nm dump-keychain
 116 Dump the contents of one or more keychains.
 117 .It Nm create-keypair
 118 Create an assymetric keypair.
 119 .It Nm add-internet-password
 120 Add an internet password item.
 121 .It Nm add-certificates
 122 Add certificates to a keychain.
 123 .It Nm find-internet-password
 124 Find an internet password item.
 125 .It Nm find-certificate
 126 Find a certificate item.
 127 .It Nm create-db
 128 Create an db using the DL.
 129 .It Nm import
 130 Import item(s) into a keychain.
 131 .It Nm export
 132 Export item(s) from a keychain.
 133 .It Nm install-mds
 134 Install (or re-install) the MDS database.
 135 .It Nm leaks
 136 Run
 137 .Pa /usr/bin/leaks
 138 on this proccess.
 139 .El
 140 .Sh "COMMON COMMAND OPTIONS"
 141 This section describes the
 142 .Ar command_options
 143 that are available across all
 144 .Nm
 145 commands.
 146 .Bl -tag -width -indent
 147 .It Fl h
 148 Show a usage message for the specified command.  This option is
 149 basically the same as the
 150 .Ar help
 151 command.
 152 .El
 153 .Sh "SECURITY COMMANDS"
 154 Here (finally) are details on all the
 155 .Nm
 156 commands and the options each accepts.
 157 .Bl -item
 158 .It
 159 .Nm help
 160 .Op Fl h
 161 .Bl -item -offset -indent
 162 Show all commands. Or show usage for a command.
 163 .El
 164 .It
 165 .Nm list-keychains
 166 .Op Fl h
 167 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 168 .Op Fl s Op Ar keychain...
 169 .Bl -item -offset -indent
 170 Display or set the keychain search list.
 171 .It
 172 Options:
 173 .Bl -tag -compact -width -indent
 174 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 175 Specify the preferences domain to be used.
 176 .It Fl s
 177 Set the search list to the specified keychains
 178 .El
 179 .El
 180 .It
 181 .Nm default-keychain
 182 .Op Fl h
 183 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 184 .Op Fl s Op Ar keychain
 185 .Bl -item -offset -indent
 186 Display or set the default keychain.
 187 .It
 188 Options:
 189 .Bl -tag -compact -width -indent
 190 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 191 Specify the preferences domain to be used.
 192 .It Fl s
 193 Set the default keychain to the specified
 194 .Ar keychain Ns .
 195 Unset it if no keychain is specified.
 196 .El
 197 .El
 198 .It
 199 .Nm login-keychain
 200 .Op Fl h
 201 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 202 .Op Fl s Op Ar keychain
 203 .Bl -item -offset -indent
 204 Display or set the login keychain.
 205 .It
 206 Options:
 207 .Bl -tag -compact -width -indent
 208 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 209 Specify the preferences domain to be used.
 210 .It Fl s
 211 Set the login keychain to the specified
 212 .Ar keychain Ns .
 213 Unset it if no keychain is specified.
 214 .El
 215 .El
 216 .It
 217 .Nm create-keychain
 218 .Op Fl hP
 219 .Op Fl p Ar password
 220 .Op Ar keychain...
 221 .Bl -item -offset -indent
 222 Create keychains and add them to the search list.  if no keychains are specified the user is prompted for one.
 223 .It
 224 Options:
 225 .Bl -tag -compact -width -indent-indent
 226 .It Fl P
 227 Prompt the user for a password using the SecurityAgent.
 228 .It Fl p Ar password
 229 Use
 230 .Ar password
 231 as the password for the keychains being created.
 232 .El
 233 .It
 234 If neither
 235 .Fl P
 236 or
 237 .Fl p Ar password
 238 are specified the user is prompted for a password.
 239 .El
 240 .It
 241 .Nm delete-keychain
 242 .Op Fl h
 243 .Op Ar keychain...
 244 .Bl -item -offset -indent
 245 Delete keychains and remove them from the search list.
 246 .El
 247 .It
 248 .Nm lock-keychain
 249 .Op Fl h
 250 .Op Fl a Ns | Ns Ar keychain
 251 .Bl -item -offset -indent
 252 Lock
 253 .Ar keychain Ns
 254 \&. Or the default is none is specified.  If the
 255 .Fl a
 256 options is specified all keychains are locked.
 257 .El
 258 .It
 259 .Nm unlock-keychain
 260 .Op Fl hu
 261 .Op Fl p Ar password
 262 .Op Ar keychain
 263 .Bl -item -offset -indent
 264 Unlock
 265 .Ar keychain Ns
 266 \&. Or the default is none is specified.
 267 .El
 268 .It
 269 .Nm set-keychain-settings
 270 .Op Fl hlu
 271 .Op Fl t Ar timeout
 272 .Op Ar keychain
 273 .Bl -item -offset -indent
 274 Set settings for
 275 .Ar keychain Ns
 276 \&. Or the default is none is specified.
 277 .Bl -tag -compact -width -indent-indent
 278 .It Fl l
 279 Lock keychain when the system sleeps
 280 .It Fl u
 281 Lock keychain after certain period of time specified using
 282 .Fl t Ns
 283 \&.
 284 .It Fl t Ar timeout
 285 Automatically lock keychain after
 286 .Ar timeout
 287 seconds of inactivity.
 288 .El
 289 .El
 290 .It
 291 .Nm show-keychain-info
 292 .Op Fl h
 293 .Bl -item -offset -indent
 294 Show the settings for keychain.
 295 .El
 296 .It
 297 .Nm dump-keychain
 298 .Op Fl adhir
 299 .Bl -item -offset -indent
 300 Dump the contents of one or more keychains.
 301 .Bl -tag -compact -width -indent-indent
 302 .It Fl a
 303 Dump acl of items.
 304 .It Fl d
 305 Dump cleartext data of items.
 306 .It Fl i
 307 Interactive acl editing mode.
 308 .It Fl r
 309 Dump raw (possibly ciphertext) data of items.
 310 .El
 311 .El
 312 .It
 313 .Nm create-keypair
 314 .Op Fl h
 315 .Op Fl a Ar alg
 316 .Op Fl s Ar size
 317 .Op Fl f Ar from_date
 318 .Op Fl t Ar to_date
 319 .Op Fl v Ar days
 320 .Op Fl k Ar keychain
 321 .Op Fl n Ar name
 322 .Op Fl A Ns | Ns Fl T Ar app1:app2:...
 323 .Bl -item -offset -indent
 324 Create an assymetric keypair.
 325 .El
 326 .It
 327 .Nm add-internet-password
 328 .Op Fl h
 329 .Op Fl a Ar account_name
 330 .Op Fl d Ar security_domain
 331 .Op Fl p Ar path
 332 .Op Fl P Ar port
 333 .Op Fl r Ar protocol
 334 .Op Fl s Ar server_name
 335 .Op Fl t Ar authentication_type
 336 .Op Fl w Ar password_data
 337 .Op Ar keychain
 338 .Bl -item -offset -indent
 339 Add an internet password item.
 340 .El
 341 .It
 342 .Nm add-certificates
 343 .Op Fl h
 344 .Op Fl k Ar keychain
 345 .Ar file...
 346 .Bl -item -offset -indent
 347 Add certficates contained in the specified
 348 .Ar files
 349 to the default keychain.  The files must contain one DER encoded X509 certificate each.
 350 .Bl -tag -compact -width -indent-indent
 351 .It Fl k Ar keychain
 352 Use
 353 .Ar keychain
 354 rather than the default keychain.
 355 .El
 356 .El
 357 .It
 358 .Nm find-internet-password
 359 .Op Fl gh
 360 .Op Fl a Ar account_name
 361 .Op Fl d Ar security_domain
 362 .Op Fl p Ar path
 363 .Op Fl P Ar port
 364 .Op Fl r Ar protocol
 365 .Op Fl s Ar server_name
 366 .Op Fl t Ar authentication_type
 367 .Op Ar keychain...
 368 .Bl -item -offset -indent
 369 Find an internet password item.
 370 .El
 371 .It
 372 .Nm find-certificate
 373 .Op Fl ahmp
 374 .Op Fl e Ar email_address
 375 .Op Ar keychain...
 376 .Bl -item -offset -indent
 377 Find a certificate item.  If no
 378 .Ar keychain
 379 arguments are provided,
 380 .Nm
 381 will search the default search list.
 382 .It
 383 Options:
 384 .Bl -tag -compact -width -indent-indent
 385 .It Fl a
 386 Find all matching certificates, not just the first one.
 387 .It Fl g Ar dl Ns | Ns Ar cspdl
 388 Use the AppleDL (default) or AppleCspDL
 389 .It Fl e Ar email_address
 390 Match on "email_address" when searching.
 391 .It Fl m
 392 Show the email addresses in the certificate.
 393 .It Fl p
 394 Output certificate in pem form.  The default is to dump the attributes and keychain the cert is in.
 395 .El
 396 .It
 397 .Sy Examples
 398 .Bl -tag -width -indent
 399 .Dl security> find-certificate -a -p > allcerts.pem
 400 Exports all certificates from all keychains into a pem file called allcerts.pem.
 401 .Dl security> find-certificate -a -e me@foo.com -p > certs.pem
 402 Exports all certificates from all keychains with the email address
 403 mb@foo.com into a pem file called certs.pem.
 404 .El
 405 .El
 406 .It
 407 .Nm create-db
 408 .Op Fl aho0
 409 .Op Fl g Ar dl Ns | Ns Ar cspdl
 410 .Op Fl m Ar mode
 411 .Op Ar name
 412 .Bl -item -offset -indent
 413 Create an db using the DL.  If
 414 .Ar name
 415 isn't provided
 416 .Nm
 417 will prompt the user to type a name.
 418 .It
 419 Options:
 420 .Bl -tag -compact -width -indent-indent
 421 .It Fl a
 422 Turn off autocommit
 423 .It Fl g Ar dl Ns | Ns Ar cspdl
 424 Use the AppleDL (default) or AppleCspDL
 425 .It Fl m Ar mode
 426 Set the file permissions to
 427 .Ar mode Ns
 428 \&.
 429 .It Fl o
 430 Force using openparams argument
 431 .It Fl 0
 432 Force using version 0 openparams
 433 .El
 434 .It
 435 .Sy Examples
 436 .Bl -tag -width -indent
 437 .Dl security> create-db -m 0644 test.db
 438 .Dl security> create-db -g cspdl -a test2.db
 439 .El
 440 .\"new import/export commands.
 441 .El
 442 .It
 443 .Nm export
 444 .Op Fl k Ar keychain
 445 .Op Fl t Ar item_type
 446 .Op Fl f Ar item_format
 447 .Op Fl w
 448 .Op Fl p Ar item_format
 449 .Op Fl P Ar passphrase
 450 .Op Fl o Ar outfile
 451 .Bl -item -offset -indent
 452 Export one or more items from a keychain to one of a number of external representations.  If
 453 .Ar keychain
 454 isn't provided, items will be exported from the user's default keychain.
 455 .It
 456 Options:
 457 .Bl -tag -compact -width -indent-indent
 458 .It Fl k Ar keychain
 459 Specify keychain from which item(s) will be exported.
 460 .It Fl t Ar item_type
 461 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.
 462 .It Fl f Ar item_format
 463 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.
 464 .It Fl w
 465 Specifies that private keys are to be wrapped on export.
 466 .It Fl p
 467 Specifies that PEM armour is to be applied to the output data.
 468 .It Fl P Ar passphrase
 469 Specify the wrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.
 470 .It Fl o Ar outfile
 471 Write the output data to
 472 .Ar outfile Ns
 473 \&. Default is to write data to stdout.
 474 .El
 475 .It
 476 .Sy Examples
 477 .Bl -tag -width -indent
 478 .Dl security> export -k login.keychain -t certs -o /tmp/certs.pem
 479 .Dl security> export -k newcert.keychain -t identities -f pkcs12 -o /tmp/mycerts.p12
 480 .El
 481 .\"marker.
 482 .El
 483 .It
 484 .Nm import
 485 inputfile
 486 .Op Fl k Ar keychain
 487 .Op Fl t Ar item_type
 488 .Op Fl f Ar item_format
 489 .Op Fl w
 490 .Op Fl P Ar passphrase
 491 .Bl -item -offset -indent
 492 Import one or more items from
 493 .Ar inputfile Ns
 494 \& into a keychain. If
 495 .Ar keychain
 496 isn't provided, items will be imported into the user's default keychain.
 497 .It
 498 Options:
 499 .Bl -tag -compact -width -indent-indent
 500 .It Fl k Ar keychain
 501 Specify keychain into which item(s) will be imported.
 502 .It Fl t Ar item_type
 503 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.
 504 .It Fl f Ar item_format
 505 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.
 506 .It Fl w
 507 Specifies that private keys are wrapped and must be unwrapped on import.
 508 .It Fl P Ar passphrase
 509 Specify the unwrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.
 510 .El
 511 .It
 512 .Sy Examples
 513 .Bl -tag -width -indent
 514 .Dl security> import /tmp/certs.pem -k
 515 .Dl security> import /tmp/mycerts.p12 -t agg -k newcert.keychain
 516 .Dl security> import /tmp/mycerts.p12 -f pkcs12 -k newcert.keychain
 517 .El
 518 .\"end of new import/export commands.
 519 .It
 520 .Nm install-mds
 521 .Bl -item -offset -indent
 522 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.
 523 .El
 524 .It
 525 .Nm leaks
 526 .Op Fl h
 527 .Op Fl cycles
 528 .Op Fl nocontext
 529 .Op Fl nostacks
 530 .Op Fl exclude Ar symbol
 531 .Bl -item -offset -indent
 532 Run
 533 .Li /usr/bin/leaks
 534 on this proccess.  This is to help find memory leaks after running
 535 certain commands.
 536 .It
 537 Options:
 538 .Bl -tag -compact -width -indent-indent
 539 .It Fl cycles
 540 Use a stricter algorithm (See
 541 .Xr leaks 1
 542 for details).
 543 .It Fl nocontext
 544 Withhold the hex dumps of the leaked memory.
 545 .It Fl nostacks
 546 Don't show stack traces of leaked memory.
 547 .It Fl exclude Ar symbol
 548 Ignore leaks called from
 549 .Ar symbol Ns .
 550 .El
 551 .El
 552 .El
 553 .El
 554 .Sh ENVIRONMENT      \" May not be needed
 555 .Bl -tag -width -indent
 556 .It Ev MallocStackLogging
 557 When using the
 558 .Nm leaks
 559 command or the
 560 .Fl l
 561 option it's probably a good idea to set this environment variable before
 562 .Nm
 563 is started.  Doing so will allow leaks to display symbolic backtraces.
 564 .El
 565 .Sh FILES
 566 .Bl -tag -width -indent
 567 .It Pa ~/Library/Preferences/com.apple.security.plist
 568 .Pp
 569 Propertylist file containing the current users default keychain and keychain search list.
 570 .It Pa /Library/Preferences/com.apple.security.plist
 571 .Pp
 572 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.
 573 .It Pa /Library/Preferences/com.apple.security-common.plist
 574 .Pp
 575 Propertylist file containing the a common keychain search list which is appended to every users searchlist and to the system search list as well.
 576 .El
 577 .Sh SEE ALSO
 578 .\" List links in ascending order by section, alphabetically within a section.
 579 .\" Please do not reference files that do not exist without filing a bug report
 580 .Xr certtool 1 ,
 581 .Xr leaks 1
 582 .\" .Xr systemkeychain 8
 583 .Sh HISTORY
 584 .Nm
 585 was first introduced in Mac OS X version 10.3
 586 .Sh AUTHORS
 587 .An "Michael Brouwer"
 588 .Sh BUGS
 589 .Nm
 590 still needs a lot more commands before it can be considered complete.
 591 In particular it should someday supersede both the
 592 .Li certtool
 593 and
 594 .Li systemkeychain
 595 commands.