OSX/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 .It Nm verify-cert
 140 Verify certificate(s).
 141 .El
 142 .Sh "COMMON COMMAND OPTIONS"
 143 This section describes the
 144 .Ar command_options
 145 that are available across all
 146 .Nm
 147 commands.
 148 .Bl -tag -width -indent
 149 .It Fl h
 150 Show a usage message for the specified command.  This option is
 151 basically the same as the
 152 .Ar help
 153 command.
 154 .El
 155 .Sh "SECURITY COMMANDS"
 156 Here (finally) are details on all the
 157 .Nm
 158 commands and the options each accepts.
 159 .Bl -item
 160 .It
 161 .Nm help
 162 .Op Fl h
 163 .Bl -item -offset -indent
 164 Show all commands. Or show usage for a command.
 165 .El
 166 .It
 167 .Nm list-keychains
 168 .Op Fl h
 169 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 170 .Op Fl s Op Ar keychain...
 171 .Bl -item -offset -indent
 172 Display or set the keychain search list.
 173 .It
 174 Options:
 175 .Bl -tag -compact -width -indent
 176 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 177 Specify the preferences domain to be used.
 178 .It Fl s
 179 Set the search list to the specified keychains
 180 .El
 181 .El
 182 .It
 183 .Nm default-keychain
 184 .Op Fl h
 185 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 186 .Op Fl s Op Ar keychain
 187 .Bl -item -offset -indent
 188 Display or set the default keychain.
 189 .It
 190 Options:
 191 .Bl -tag -compact -width -indent
 192 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 193 Specify the preferences domain to be used.
 194 .It Fl s
 195 Set the default keychain to the specified
 196 .Ar keychain Ns .
 197 Unset it if no keychain is specified.
 198 .El
 199 .El
 200 .It
 201 .Nm login-keychain
 202 .Op Fl h
 203 .Op Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 204 .Op Fl s Op Ar keychain
 205 .Bl -item -offset -indent
 206 Display or set the login keychain.
 207 .It
 208 Options:
 209 .Bl -tag -compact -width -indent
 210 .It Fl d Ar user Ns | Ns Ar system Ns | Ns Ar common
 211 Specify the preferences domain to be used.
 212 .It Fl s
 213 Set the login keychain to the specified
 214 .Ar keychain Ns .
 215 Unset it if no keychain is specified.
 216 .El
 217 .El
 218 .It
 219 .Nm create-keychain
 220 .Op Fl hP
 221 .Op Fl p Ar password
 222 .Op Ar keychain...
 223 .Bl -item -offset -indent
 224 Create keychains and add them to the search list.  If no keychains are specified the user is prompted for one.
 225 .It
 226 Options:
 227 .Bl -tag -compact -width -indent-indent
 228 .It Fl P
 229 Prompt the user for a password using the SecurityAgent.
 230 .It Fl p Ar password
 231 Use
 232 .Ar password
 233 as the password for the keychains being created.
 234 .El
 235 .It
 236 If neither
 237 .Fl P
 238 or
 239 .Fl p Ar password
 240 are specified the user is prompted for a password.
 241 .El
 242 .It
 243 .Nm delete-keychain
 244 .Op Fl h
 245 .Op Ar keychain...
 246 .Bl -item -offset -indent
 247 Delete keychains and remove them from the search list.
 248 .El
 249 .It
 250 .Nm lock-keychain
 251 .Op Fl h
 252 .Op Fl a Ns | Ns Ar keychain
 253 .Bl -item -offset -indent
 254 Lock
 255 .Ar keychain Ns
 256 \&. Or the default is none is specified.  If the
 257 .Fl a
 258 options is specified all keychains are locked.
 259 .El
 260 .It
 261 .Nm unlock-keychain
 262 .Op Fl hu
 263 .Op Fl p Ar password
 264 .Op Ar keychain
 265 .Bl -item -offset -indent
 266 Unlock
 267 .Ar keychain Ns
 268 \&. Or the default is none is specified.
 269 .El
 270 .It
 271 .Nm set-keychain-settings
 272 .Op Fl hlu
 273 .Op Fl t Ar timeout
 274 .Op Ar keychain
 275 .Bl -item -offset -indent
 276 Set settings for
 277 .Ar keychain Ns
 278 \&. Or the default is none is specified.
 279 .Bl -tag -compact -width -indent-indent
 280 .It Fl l
 281 Lock keychain when the system sleeps
 282 .It Fl u
 283 Lock keychain after certain period of time specified using
 284 .Fl t Ns
 285 \&.
 286 .It Fl t Ar timeout
 287 Automatically lock keychain after
 288 .Ar timeout
 289 seconds of inactivity.
 290 .El
 291 .El
 292 .It
 293 .Nm show-keychain-info
 294 .Op Fl h
 295 .Bl -item -offset -indent
 296 Show the settings for keychain.
 297 .El
 298 .It
 299 .Nm dump-keychain
 300 .Op Fl adhir
 301 .Bl -item -offset -indent
 302 Dump the contents of one or more keychains.
 303 .Bl -tag -compact -width -indent-indent
 304 .It Fl a
 305 Dump acl of items.
 306 .It Fl d
 307 Dump cleartext data of items.
 308 .It Fl i
 309 Interactive acl editing mode.
 310 .It Fl r
 311 Dump raw (possibly ciphertext) data of items.
 312 .El
 313 .El
 314 .It
 315 .Nm create-keypair
 316 .Op Fl h
 317 .Op Fl a Ar alg
 318 .Op Fl s Ar size
 319 .Op Fl f Ar from_date
 320 .Op Fl t Ar to_date
 321 .Op Fl v Ar days
 322 .Op Fl k Ar keychain
 323 .Op Fl n Ar name
 324 .Op Fl A Ns | Ns Fl T Ar app1:app2:...
 325 .Bl -item -offset -indent
 326 Create an asymmetric keypair.
 327 .El
 328 .It
 329 .Nm add-internet-password
 330 .Op Fl h
 331 .Op Fl a Ar account_name
 332 .Op Fl d Ar security_domain
 333 .Op Fl p Ar path
 334 .Op Fl P Ar port
 335 .Op Fl r Ar protocol
 336 .Op Fl s Ar server_name
 337 .Op Fl t Ar authentication_type
 338 .Op Fl w Ar password_data
 339 .Op Ar keychain
 340 .Bl -item -offset -indent
 341 Add an internet password item.
 342 .El
 343 .It
 344 .Nm add-certificates
 345 .Op Fl h
 346 .Op Fl k Ar keychain
 347 .Ar file...
 348 .Bl -item -offset -indent
 349 Add certficates contained in the specified
 350 .Ar files
 351 to the default keychain.  The files must contain one DER encoded X509 certificate each.
 352 .Bl -tag -compact -width -indent-indent
 353 .It Fl k Ar keychain
 354 Use
 355 .Ar keychain
 356 rather than the default keychain.
 357 .El
 358 .El
 359 .It
 360 .Nm find-internet-password
 361 .Op Fl gh
 362 .Op Fl a Ar account_name
 363 .Op Fl d Ar security_domain
 364 .Op Fl p Ar path
 365 .Op Fl P Ar port
 366 .Op Fl r Ar protocol
 367 .Op Fl s Ar server_name
 368 .Op Fl t Ar authentication_type
 369 .Op Ar keychain...
 370 .Bl -item -offset -indent
 371 Find an internet password item.
 372 .El
 373 .It
 374 .Nm find-certificate
 375 .Op Fl ahmp
 376 .Op Fl e Ar email_address
 377 .Op Ar keychain...
 378 .Bl -item -offset -indent
 379 Find a certificate item.  If no
 380 .Ar keychain
 381 arguments are provided,
 382 .Nm
 383 will search the default search list.
 384 .It
 385 Options:
 386 .Bl -tag -compact -width -indent
 387 .It Fl a
 388 Find all matching certificates, not just the first one.
 389 .It Fl g Ar dl Ns | Ns Ar cspdl
 390 Use the AppleDL (default) or AppleCspDL
 391 .It Fl e Ar email_address
 392 Match on "email_address" when searching.
 393 .It Fl m
 394 Show the email addresses in the certificate.
 395 .It Fl p
 396 Output certificate in pem form.  The default is to dump the attributes and keychain the cert is in.
 397 .El
 398 .It
 399 .Sy Examples
 400 .Bl -tag -width -indent
 401 .Dl security> find-certificate -a -p > allcerts.pem
 402 Exports all certificates from all keychains into a pem file called allcerts.pem.
 403 .Dl security> find-certificate -a -e me@foo.com -p > certs.pem
 404 Exports all certificates from all keychains with the email address
 405 mb@foo.com into a pem file called certs.pem.
 406 .El
 407 .El
 408 .It
 409 .Nm create-db
 410 .Op Fl aho0
 411 .Op Fl g Ar dl Ns | Ns Ar cspdl
 412 .Op Fl m Ar mode
 413 .Op Ar name
 414 .Bl -item -offset -indent
 415 Create an db using the DL.  If
 416 .Ar name
 417 isn't provided
 418 .Nm
 419 will prompt the user to type a name.
 420 .It
 421 Options:
 422 .Bl -tag -compact -width -indent-indent
 423 .It Fl a
 424 Turn off autocommit
 425 .It Fl g Ar dl Ns | Ns Ar cspdl
 426 Use the AppleDL (default) or AppleCspDL
 427 .It Fl m Ar mode
 428 Set the file permissions to
 429 .Ar mode Ns
 430 \&.
 431 .It Fl o
 432 Force using openparams argument
 433 .It Fl 0
 434 Force using version 0 openparams
 435 .El
 436 .It
 437 .Sy Examples
 438 .Bl -tag -width -indent
 439 .Dl security> create-db -m 0644 test.db
 440 .Dl security> create-db -g cspdl -a test2.db
 441 .El
 442 .\"new import/export commands.
 443 .El
 444 .It
 445 .Nm export
 446 .Op Fl k Ar keychain
 447 .Op Fl t Ar item_type
 448 .Op Fl f Ar item_format
 449 .Op Fl w
 450 .Op Fl p Ar item_format
 451 .Op Fl P Ar passphrase
 452 .Op Fl o Ar outfile
 453 .Bl -item -offset -indent
 454 Export one or more items from a keychain to one of a number of external representations.  If
 455 .Ar keychain
 456 isn't provided, items will be exported from the user's default keychain.
 457 .It
 458 Options:
 459 .Bl -tag -compact -width -indent-indent
 460 .It Fl k Ar keychain
 461 Specify keychain from which item(s) will be exported.
 462 .It Fl t Ar item_type
 463 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.
 464 .It Fl f Ar item_format
 465 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.
 466 .It Fl w
 467 Specifies that private keys are to be wrapped on export.
 468 .It Fl p
 469 Specifies that PEM armour is to be applied to the output data.
 470 .It Fl P Ar passphrase
 471 Specify the wrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.
 472 .It Fl o Ar outfile
 473 Write the output data to
 474 .Ar outfile Ns
 475 \&. Default is to write data to stdout.
 476 .El
 477 .It
 478 .Sy Examples
 479 .Bl -tag -width -indent
 480 .Dl security> export -k login.keychain -t certs -o /tmp/certs.pem
 481 .Dl security> export -k newcert.keychain -t identities -f pkcs12 -o /tmp/mycerts.p12
 482 .El
 483 .\"marker.
 484 .El
 485 .It
 486 .Nm import
 487 inputfile
 488 .Op Fl k Ar keychain
 489 .Op Fl t Ar item_type
 490 .Op Fl f Ar item_format
 491 .Op Fl w
 492 .Op Fl P Ar passphrase
 493 .Bl -item -offset -indent
 494 Import one or more items from
 495 .Ar inputfile Ns
 496 \& into a keychain. If
 497 .Ar keychain
 498 isn't provided, items will be imported into the user's default keychain.
 499 .It
 500 Options:
 501 .Bl -tag -compact -width -indent-indent
 502 .It Fl k Ar keychain
 503 Specify keychain into which item(s) will be imported.
 504 .It Fl t Ar item_type
 505 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.
 506 .It Fl f Ar item_format
 507 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.
 508 .It Fl w
 509 Specifies that private keys are wrapped and must be unwrapped on import.
 510 .It Fl P Ar passphrase
 511 Specify the unwrapping passphrase immediately. The default is to obtain a secure passphrase via GUI.
 512 .El
 513 .It
 514 .Sy Examples
 515 .Bl -tag -width -indent
 516 .Dl security> import /tmp/certs.pem -k
 517 .Dl security> import /tmp/mycerts.p12 -t agg -k newcert.keychain
 518 .Dl security> import /tmp/mycerts.p12 -f pkcs12 -k newcert.keychain
 519 .El
 520 .\"end of new import/export commands.
 521 .It
 522 .Nm install-mds
 523 .Bl -item -offset -indent
 524 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.
 525 .El
 526 .It
 527 .Nm leaks
 528 .Op Fl h
 529 .Op Fl cycles
 530 .Op Fl nocontext
 531 .Op Fl nostacks
 532 .Op Fl exclude Ar symbol
 533 .Bl -item -offset -indent
 534 Run
 535 .Li /usr/bin/leaks
 536 on this proccess.  This is to help find memory leaks after running
 537 certain commands.
 538 .It
 539 Options:
 540 .Bl -tag -compact -width -indent-indent
 541 .It Fl cycles
 542 Use a stricter algorithm (See
 543 .Xr leaks 1
 544 for details).
 545 .It Fl nocontext
 546 Withhold the hex dumps of the leaked memory.
 547 .It Fl nostacks
 548 Don't show stack traces of leaked memory.
 549 .It Fl exclude Ar symbol
 550 Ignore leaks called from
 551 .Ar symbol Ns .
 552 .El
 553 .El
 554 .It
 555 .Nm verify-cert
 556 .Op Fl c Ar certFile
 557 .Op Fl r Ar rootCertFile
 558 .Op Fl p Ar policy
 559 .Op Fl d Ar date
 560 .Op Fl n Ar name
 561 .Op Fl L
 562 .Op Fl q
 563 .Op Fl C
 564 .Bl -item -offset -indent
 565 Verify one or more certificates.
 566 .It
 567 Options:
 568 .Bl -tag -compact -width -indent-indent
 569 .It Fl c Ar certFile
 570 Certificate to verify, in DER or PEM format. Can be specified more than once; leaf certificate has to be specified first.
 571 .It Fl r Ar rootCertFile
 572 Root certificate, in DER or PEM format. Can be specified more than once. If not specified, the system anchor certificates are used.
 573 .It Fl p Ar policy
 574 Specify verification policy (ssl, smime, codeSign, IPSec, basic, eap, appleID, timestamping, revocation). Default is basic.
 575 .It Fl d Ar date
 576 Date to set for verification. Specified in the format of YYYY-MM-DD-hh:mm:ss (time optional). e.g: 2016-04-25-15:59:59 for April 25, 2016 at 3:59:59 pm in GMT
 577 .It Fl n Ar name
 578 Specify name for the policy (ssl, IPSec, smime).
 579 .It Fl L
 580 Use local certificates only. If an issuing CA certificate is missing, this option will avoid accessing the network to fetch it.
 581 .It Fl q
 582 Quiet, no stdout or stderr.
 583 .It Fl C
 584 Set to client-side. Otherwise, defaults to server.
 585 .El
 586 .It
 587 .Sy Examples
 588 .Bl -tag -width -indent
 589 .Dl security> verify-cert -r serverbasic.crt
 590 .El
 591 .Sh ENVIRONMENT      \" May not be needed
 592 .Bl -tag -width -indent
 593 .It Ev MallocStackLogging
 594 When using the
 595 .Nm leaks
 596 command or the
 597 .Fl l
 598 option it's probably a good idea to set this environment variable before
 599 .Nm
 600 is started.  Doing so will allow leaks to display symbolic backtraces.
 601 .El
 602 .Sh FILES
 603 .Bl -tag -width -indent
 604 .It Pa ~/Library/Preferences/com.apple.security.plist
 605 .Pp
 606 Propertylist file containing the current users default keychain and keychain search list.
 607 .It Pa /Library/Preferences/com.apple.security.plist
 608 .Pp
 609 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.
 610 .It Pa /Library/Preferences/com.apple.security-common.plist
 611 .Pp
 612 Propertylist file containing the a common keychain search list which is appended to every users searchlist and to the system search list as well.
 613 .El
 614 .Sh SEE ALSO
 615 .\" List links in ascending order by section, alphabetically within a section.
 616 .\" Please do not reference files that do not exist without filing a bug report
 617 .Xr certtool 1 ,
 618 .Xr leaks 1
 619 .\" .Xr systemkeychain 8
 620 .Sh HISTORY
 621 .Nm
 622 was first introduced in Mac OS X version 10.3
 623 .Sh AUTHORS
 624 .An "Michael Brouwer"
 625 .Sh BUGS
 626 .Nm
 627 still needs a lot more commands before it can be considered complete.
 628 In particular it should someday supersede both the
 629 .Li certtool
 630 and
 631 .Li systemkeychain
 632 commands.