CertTool/certtool.1

   1 .de EX
   2 .nf
   3 .ft CW
   4 .RS
   5
   6 ..
   7 .de EE
   8 .br
   9 .fi
  10 .ft 1
  11 .RE
  12 .PP
  13 ..
  14 .de BL
  15 .TP
  16 \(bu
  17 ..
  18 .TH CERTTOOL 1 "March 19, 2003" "Apple Computer, Inc."
  19 .SH NAME
  20 certtool \- create key pairs, certificates and certificate signing requests for
  21 use with Keychains
  22 .SH SYNOPSIS
  23 .B certtool
  24 command [command-args] [options]
  25 .PP
  26 .B certtool
  27 c [options]
  28 .PP
  29 .B certtool
  30 r outFileName [options]
  31 .PP
  32 .B certtool
  33 v infileName [options]
  34 .PP
  35 .B certtool
  36 i inFileName [options]
  37 .PP
  38 .B certtool
  39 d inFileName [options]
  40 .PP
  41 .B certtool
  42 I inFileName [options]
  43 .PP
  44 .B certtool
  45 D inFileName [options]
  46 .PP
  47 .B certtool
  48 y [options]
  49 .SH CERTTOOL COMMAND SUMMARY
  50 .B c
  51 Create keypair and Certificate
  52 .PP
  53 .B r
  54 Create CSR
  55 .PP
  56 .B v
  57 Verify CSR
  58 .PP
  59 .B i
  60 Import Certificate
  61 .PP
  62 .B d
  63 Display Certificate
  64 .PP
  65 .B I
  66 Import CRL
  67 .PP
  68 .B D
  69 Display CRL
  70 .PP
  71 .B I
  72 Import a CRL
  73 .PP
  74 .B y
  75 Display all certs and CRLs in keychain
  76 .PP
  77 .SH "CERTTOOL OPTION SUMMARY"
  78 .TP
  79 .B c
  80 Create the keychain, if one is needed.
  81 .TP
  82 .B d
  83 Create a CSR in DER format; default is PEM
  84 .TP
  85 .B k=keychainName
  86 Specify the Keychain to use for the operation. If keychainName starts with a '/', an absolute path is assumed; otherwise, the specified filename is relative to the user's Library/Keychains directory.
  87 .TP
  88 .B p=passphrase
  89 Specify the keychain passphrase when creating
  90 .TP
  91 .B r=privateKeyFileName
  92 Optional private key, for Import Certificate only
  93 .TP
  94 .B f=[18f]
  95 Private Key Format = PKCS1/PKCS8/FIPS186; default is PKCS1 (openssl)
  96 .TP
  97 .B a
  98 Generate private key with default ACL
  99 .TP
 100 .B h
 101 Print usage message
 102 .TP
 103 .B v
 104 Execute in verbose mode.
 105 .SH "DESCRIPTION"
 106 .B Certtool
 107 is a UNIX command-line program which is used to create key pairs, certificates,
 108 and certificate signing requests; to import externally generated certificates
 109 and Certificate Revocation Lists (CRLs) into a Keychain, and to display the
 110 contents of certificates and CRLs. Currently, the primary use of CertTool is
 111 to perform the certificate-related administration required to configure an
 112 SSL server based on Mac OS X's SecureTransport library.
 113 .SH EXAMPLES
 114 .PP
 115 .B "Generating a Self-Signed Certificate"
 116 .PP
 117 This command generates a key pair and a self-signed (root) certificate
 118 and places them in a keychain. The root cert is signed by the private
 119 key generated during this command. The cert generated by this command
 120 is totally untrustworthy and cannot be used in the "real world"; the
 121 primary use of this command is to facilitate early development of SSL
 122 server applications based on SecureTransport. In particular,
 123 "real world" SSL clients (e.g., web browsers) will complain to
 124 varying degrees when they attempt to connect to an SSL server which
 125 presents a cert which is generated by this command. Some broswers,
 126 after a fair amount of handholding, will allow you to conditionally
 127 "trust" this cert.
 128 .EX
 129 # CertTool c [options]
 130 .EE
 131 The available options are:
 132 .TP
 133 k=keyChainName
 134 .PP
 135 Where "keyChainName" is the name of the keychain into which keys and the cert
 136 will be added. If no keychain is specified, keys and certs are added to the
 137 default keychain. The specified keychain must exist unless you specify the 'c'
 138 option.
 139 .TP
 140 c
 141 .PP
 142 Specifies that the designated keychain is to be created.
 143 .PP
 144 This an interactive command; you will be prompted for a number of different
 145 items which are used to generate the keypair and the cert. A sample session
 146 follows.
 147 .EX
 148 # CertTool k=certkc
 149 Enter key and certificate label: testCert
 150
 151 Please specify parameters for the key pair you will generate.
 152
 153         r RSA
 154         d DSA
 155         f FEE
 156
 157 Select key algorithm by letter: r
 158
 159 Valid key sizes for RSA are 512..2048; default is 512
 160 Enter key size in bits or CR for default: 512
 161
 162 You have selected algorithm RSA, key size 512 bits.
 163 OK (y/anything)? y
 164 Enter cert/key usage (s=signing, b=signing AND encrypting): b
 165  ...Generating key pair...
 166
 167 .EE
 168 Note: you will be prompted for the Keychain's passphrase by the Keychain
 169 system at this point if the specified keychain is not open and you have not specified the passphrase via the 'p' option.
 170 .EX
 171 Please specify the algorithm with which your certificate will be signed.
 172
 173         5 RSA with MD5
 174         s RSA with SHA1
 175
 176 Select signature algorithm by letter: s
 177
 178 You have selected algorithm RSA with SHA1.
 179 OK (y/anything)? y
 180 ...creating certificate...
 181 .EE
 182 You will now specify the various components of the certificate's
 183 Relative Distinguished Name (RDN). An RDN has a number of
 184 components, all of which are optional, but at least one of
 185 which must be present.
 186 .PP
 187 Note that if you are creating a certificate for use in an
 188 SSL/TLS server, the Common Name component of the RDN must match
 189 exactly the host name of the server. This must not be an IP
 190 address, but the actual domain name, e.g. www.apple.com.
 191 Entering a CR for a given RDN component results in no value for
 192 that component.
 193 .EX
 194 Common Name     (e.g, www.apple.com) : 10.0.61.5
 195 Country         (e.g, US) :
 196 Organization (e.g, Apple Computer, Inc.) : Apple
 197 Organization Unit (e.g, Apple Data Security) :
 198 State/Province (e.g., California) : California
 199
 200 You have specified:
 201  Common Name    : 10.0.61.5
 202  Organization   : Apple
 203  State/Province : California
 204 Is this OK (y/anything)? y
 205 ..cert stored in Keychain.
 206 #
 207 .EE
 208 The "Common Name" portion of the RDN - in the above case, "10.0.61.5" - MUST
 209 match the host name of the machine you'll running sslServer on. (In this case
 210 the test machine doesn't have an actual hostname; it's DHCP'd behind a firewall
 211 which is why "10.0.61.5" was specified for Common Name.) This is part of SSL's
 212 certificate verification; it prevents an attack using DNS spoofing.
 213 .PP
 214 A brief note about cert/key usage: the normal configuration of SecureTransport
 215 is that the server cert specified in SSLSetCertificate() is capable of both
 216 signing and encryption. If this cert is only capable of signing, then you must
 217 create a second keychain ontaining a cert which is capable of encryption, and
 218 pass that to SSLSetEncryptionCertificate().
 219 .PP
 220 .B "Generating a Certificate Signing Request (CSR)"
 221 .PP
 222 A CSR is the standard means by which an administrator of a web server provides
 223 information to a Certificate Authority (CA) in order to obtain a valid
 224 certificate which is signed by the CA. This type of cert is used in the real
 225 world; certs signed by CAs such as Verisign or Thawte are recognized by all web
 226 browsers when performing SSL transactions.
 227 .PP
 228 The general procedure for obtaining a "real" cert is:
 229 .BL
 230 Generate a key pair
 231 .BL
 232 Generate a CSR
 233 .BL
 234 Provide the CSR and some other information and/or documentation to the CA
 235 .BL
 236 CA sends you a certificate which is signed by the CA.
 237 .BL
 238 You import that certificate, obtained from the CA, into your keychain.
 239 .PP
 240 The
 241 items in that keychain can now be used in SecureTransport's SSLSetCertificate()
 242 call.
 243 .PP
 244 This command performs the first two steps in the above procedure. See the
 245 section below entitled "Importing a Certificate" for information on
 246 importing the resulting certificate into your keychain. The format of
 247 this command is
 248 .EX
 249 # CertTool r outFileName [options]
 250 .EE
 251 The resulting CSR will be written to "outFileName".
 252 The available options are:
 253 .EX
 254 k=keyChainName
 255 .EE
 256 Where "KeyChainName" is the name of the keychain into which keys and the cert
 257 will be added. If no keychain is specified, keys and certs are added to the
 258 default keychain. The specified keychain must exist unless you specify the 'c'
 259 option.
 260 .EX
 261  d
 262 .EE
 263 The 'd' option tells CertTool to create the CSR in DER-encoded format. The
 264 default is PEM-encoded, which is what most CAs expect. PEM encoded data consists
 265 of printable ASCII text which can, for example, be pasted into an email message.
 266 DER-encoded data is nonprintable binary data.
 267 .EX
 268  c
 269 .EE
 270 Specifies that the designated keychain is to be created.
 271 .PP
 272 This an interactive command; you will be prompted for a number of different
 273 items which are used to generate the keypair and the CSR. The prompts given, and
 274 the format of the data you must supply, are identical to the data shown in the
 275 sample session in Section 2.
 276 .PP
 277 .B "Verifying a CSR"
 278 .PP
 279 A CSR contains, among other things, the public key which was generated in
 280 as described above. The CSR is signed with the associated private key. Thus the
 281 integrity of a CSR can be verified by extracting its public key and verifying the signature of the CSR. This command performs this integrity check. The format of this command is
 282 .EX
 283 # CertTool v inFileName [options]
 284 .EE
 285 The only available option is the 'd' flag, which as described above in the
 286 section entitled "Generating a Certificate Signing Request", indiciates
 287 that the CSR is in DER format rather than the default PEM format.
 288 A typical (successful) run of this command is like so:
 289 .EX
 290 # CertTool v myCsr.pem
 291  ...CSR verified successfully.
 292 .EE
 293 A large number of things can go wrong if the verification fails; suffice it to
 294 say that if you see anything other than the above success message, you have a
 295 bad or corrupted CSR.
 296 .PP
 297 .B "Importing a Certificate from a Certificate Authority"
 298 .PP
 299 Once you have negotiated with your CA, and provided them with the CSR generated
 300 as described above as well as any other information, documentation, and payment they
 301 require, the CA will provide you with a certificate. Use this command to add
 302 that certificate to the keychain containing the keypair you generated previously.
 303 .PP
 304 The format of this command is
 305 .EX
 306 # CertTool i inFileName [options]
 307 .EE
 308 The cert to import is obtained from "inFileName". The available options are:
 309 .EX
 310 k=keyChainName
 311 .EE
 312 Where "keyChainName" is the name of the keychain to which the cert will be
 313 added. If no keychain is specified, the cert is added to the default keychain.
 314 The specified keychain typically contains the keypair you generated previously.
 315 (Note you can import a certificate into a keychain which does not contain keys
 316 you generated but there will be no linkage between the imported certificate and
 317 a private key if you do this.) If the keychain is not open when this command is
 318 executed, you will be prompted by the Keychain system for its passphrase.
 319 .EX
 320 r=privateKeyFileName
 321 .EE
 322 Where "privateKeyFileName" is the name of the optional private key file to imported along with the certificate. This option is used to import cert/key pairs which are generated by other means, such as OpenSSL.
 323 .EX
 324 f=privateKeyFormat
 325 .EE
 326 Where "privateKeyFormat" is the format of the private key specified with the 'r' option. The formats are: '1' for PKCS1 (OpenSSL format), '8' (PKCS8), and 'f' (FIPS186, BSAFE format). The default is OpenSSL format for both RSA and DSA keys.
 327 .EX
 328  d
 329 .EE
 330 Specifies DER format as described above. The default is PEM format.
 331 .EX
 332  c
 333 .EE
 334 Specifies that the designated keychain is to be created.
 335 .PP
 336 .B "Displaying a Certificate"
 337 .PP
 338 This displays the contents of an existing certificate, obtained from a file.
 339 The format of this command is
 340 .EX
 341 # CertTool d inFileName [options]
 342 .EE
 343 The cert to display is obtained from "inFileName".
 344 The only available option is the 'd' flag, specifying DER format as described above. The default is PEM format. Actually, in the absence of this option, certtool will correctly determine the format of the certificate (PEM or DER).
 345 .PP
 346 .B "Importing a CRL"
 347 .PP
 348 This command is used to add a Certificate Revocation List (CRL) to a keychain.
 349 The format of this command is
 350 .EX
 351 # CertTool I inFileName [options]
 352 .EE
 353 The CRL to import is obtained from "inFileName".  The available options are:
 354 .EX
 355 k=keyChainName
 356 .EE
 357 Where "KeyChainName" is the name of the keychain to which the CRL will be added.
 358 If no keychain is specified, the cert is added to the default keychain.  If the
 359 keychain is not open when this command is executed, you will be prompted by the
 360 Keychain system for its passphrase.
 361 .EX
 362  d
 363 .EE
 364 Specifies DER format as described above. The default is PEM format.
 365 .EX
 366  c
 367 .EE
 368 Specifies that the designated keychain is to be created.
 369 .PP
 370 .B "Displaying a CRL"
 371 .PP
 372 This displays the contents of an existing Certificate Revocation List (CRL),
 373 obtained from a file. The format of this command is
 374 .EX
 375 # CertTool D inFileName [options]
 376 .EE
 377 The cert to display is obtained from "inFileName".
 378 The only available option is the 'd' flag, specifying DER format as described
 379 above. The default is PEM format.
 380 .PP
 381 .B "Displaying Certificates and CRLs in a keychain"
 382 .PP
 383 This displays the contents of all certificates and CRLs in a keychain. The format of this command is
 384 .EX
 385 # CertTool y [options]
 386 .EE
 387 The available options are:
 388 .EX
 389 k=keyChainName
 390 .EE
 391 Where "KeyChainName" is the name of the keychain to display.
 392 .EX
 393 v
 394 .EE
 395 Specifies verbose mode.
 396 .PP
 397 .B "Certificate Authorities and CSRs"
 398 .PP
 399 As mentioned above, the general procedure for obtaining a "real" cert is:
 400 .BL
 401 Generate a key pair
 402 .BL
 403 Generate a CSR
 404 .BL
 405 Provide the CSR and some other information and/or documentation to the CA
 406 .BL
 407 CA sends you a certificate which is signed by the CA.
 408 .BL
 409 You import that certificate, obtained from the CA, into your keychain.
 410 .PP
 411 The items in that keychain can now be used in SecureTranspoert's SSLSetCertificate()
 412 call.
 413 .PP
 414 One CA with an excellent web-based interface for obtaining a cert is Verisign
 415 (http://www.verisign.com/products/site/index.html). You can get a free 14-day
 416 trial certificate using nothing but CertTool, Verisign's web site, and email.
 417 You need to provide some personal information; then you paste in the CSR
 418 generated as described in the section entitled "Generating a Certificate
 419 Signing Request" into a form on the web site. A few minutes later Verisign
 420 emails you a certificate, which you import into your keychain.
 421 The whole process takes less than 10 minutes. The free certificate obtained in
 422 this manner is signed by a temporary root cert which is not recognized by any
 423 browsers, but Verisign also provides a means of installing this temporary root
 424 cert into your browser, directly from their web site. Typically one would use
 425 the free, temporary cert to perform initial configuration of a server and to
 426 ring out the general SSL infrastructure. Once you feel comfortable with the
 427 operation of the server, then it's time to buy a "real" certificate which will
 428 allow your web server to be recognized by any browser.
 429 .PP
 430 Thawte has a similar, very friendly service at http://www.thawte.com/.
 431 Note that, for early web server development and/or testing, you can skip the entire procedure described above and just generate your own self-signed root cert as described above. No CA is involved; no CSR is generated; no cert needs to be imported - CertTool generates a cert for you and immediately adds it to your keychain. Bear in mind that this option requires tolerance of the various SSL clients you'll be testing with, none of whom recognize your root cert.
 432 .SH FILES
 433 .B /System/Library/Keychains/X509Anchors
 434 System root certificate database
 435 .SH SEE ALSO
 436 .BR openssl ( 1 )