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