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