Creating Certificates for TLS Testing
When developing secure network software using Transport Layer Security (TLS), it's sometimes necessary to create server and client digital identities for testing. This document shows how to do that using the Certificate Assistant that's built in to OS X.
While this document focuses on TLS, it's also relevant if you're using HTTPS (HTTP over TLS) or TLS's older cousin, Secure Sockets Layer (SSL).
You should read this document if you're creating an OS X or iOS program that uses TLS, SSL or HTTPS, and you need to set up a test server or create a test client digital identity.
Introduction
Transport Layer Security (TLS), along with the older Secure Sockets Layer (SSL), are the most important secure networking protocols on both OS X and iOS. When developing a client program that uses TLS, sometimes it's necessary to set up a server to test against, and that requires you to have a TLS server digital identity. In other cases it's necessary to have a TLS client digital identity for testing purposes. This document shows how to create both of these things using the Certificate Assistant that's built in to OS X.
The basic approach described in this document is:
create a certificate authority
use that to issue digital identities
export the resulting digital certificates and digital identities as necessary
The remaining sections of this document contain detailed instructions for each of these steps. Creating a Certificate Authority shows how to a create a certificate authority using Certificate Assistant. Issuing a Digital Identity shows how to use that certificate authority to issue a TLS digital identity. Exporting the Certificate Authority's Root Certificate shows how to export the certificate authority root certificate; typically you do this so that you can import the root certificate into a client machine so that it trusts certificates issued by your certificate authority. Exporting a Digital Identity shows how to export one of the digital identities issued by the certificate authority.
This document was written and tested on OS X 10.9 Mavericks. Certificate Assistant has changed a little over the years, so some things will be slightly different on older systems. However, the core concepts described here are valid for all versions of OS X.
You can also use the openssl tool (specifically its ca subcommand) to manage a certificate authority. This has a lot more features than Certificate Assistant, although it's also a lot harder to use. If you're just running a test certificate authority, Certificate Assistant is your best bet. If you're running a production certificate authority, you should evaluate other options, including the openssl tool.
Creating a Certificate Authority
The first step in this process is to create a certificate authority. Certificate Assistant makes this remarkably simple. This section describes the process step-by-step.
A. Launch Keychain Access
In Finder, choose Go > Utilities, then find Keychain Access and launch it.
B. Launch Certificate Assistant
In Keychain Access, make sure nothing is selected in the panel on the right and then choose Keychain Access > Certificate Assistant > Create a Certificate Authority. This will launch Certificate Assistant.
C. Certificate Authority Basics
In Certificate Assistant, fill out the Create Your Certificate Authority panel as shown in Figure 1 and then click Continue.
Set this to the name of your certificate authority; in this example, we're using "MouseCA".
This should default to Self Signed Root CA; leave it at that.
The value you use here doesn't really matter because you override it whenever you issue a digital identity. However, it's best to set this to the type of identity that this certificate authority will issue in most cases. So, if you're setting up a certificate authority solely to issue TLS server digital identities, select SSL Server here. Likewise, if your focus is on TLS client digital identities, select SSL Client.
Check this.
This should be checked by default.
Enter an appropriate email address here. This email address is baked into the certificate authority's root certificate, so if you plan to pass that root certificate around, make sure you use an address that you don't mind being spammed.
D. Certificate Information (1)
Fill out the Certificate Information panel as shown in Figure 2 and then click Continue.
Don't modify this item; see the discussion of serial numbers below.
The default value here is 365 days. You generally want to increase this so that your certificate authority's root certificate stays valid for a long time. The easiest thing to do is add a zero to the end, which keeps your certificate authority's root certificate valid for roughly 10 years.
This should not be checked; leave it that way.
Uncheck this.
E. Certificate Information (2)
The second Certificate Information panel should default to reasonable values, as shown in Figure 3, so just click Continue.
F. Accept Lots of Defaults
The next 10 panels all default to reasonable values. Keep clicking Continue until the Continue button turns into a Create button (on the Specify a Location For The Certificate panel).
G. Specify a Location
The last panel you see before creating the certificate authority is the Specify a Location For The Certificate panel, as shown in Figure 4. Consider the items below and then, when you're ready, click Create.
This defaults to your default keychain. If you want to use a different keychain to keep your certificate authority keychain items separate from your day-to-day keychain items, you can select it here.
This should not be checked; leave it that way.
H. Conclusion
After Certificate Assistant has created your certificate authority, you'll see the Conclusion panel shown in Figure 5. Now close the Certificate Assistant window.
I. Confirm Keychain Items
After closing the Certificate Assistant window you should be back in Keychain Access. You should confirm that your certificate authority's root certificate, public key and private key are present in the keychain, as shown in Figure 6.
Issuing a Digital Identity
Once you've created your certificate authority, you can use it to issue a digital identity. This section describes the process for issuing a TLS server digital identity, calling out things that are different for a TLS client digital identity.
A. Launch Keychain Access
In Finder, choose Go > Utilities, then find Keychain Access and launch it.
B. Launch Certificate Assistant
In Keychain Access, make sure nothing is selected in the panel on the right and then choose Keychain Access > Certificate Assistant > Create a Certificate. This will launch Certificate Assistant.
C. Certificate Basics
In Certificate Assistant, fill out the Create Your Certificate panel as shown in Figure 7 and then click Continue.
Set this to a human readable name for the server.
Set this to Leaf.
Set this to SSL Server.
Check this.
If you are creating a TLS client digital identity, set item 1 to a name that identities the client and item 3 to SSL Client, as shown in Figure 8.
D. Certificate Information (1)
Fill out the Certificate Information panel as shown in Figure 9 and then click Continue.
Don't modify this item; see the comments below.
The default value here is 365 days, which is a reasonable choice for an issued certificate. If the certificate expires, you can always re-issue it.
In theory, you should be able to manually enter the serial number for the certificate to be issued (some folks use serial numbers with a specific format, for example, a certificate issued on 4 Oct 2013 at 23:58 might have a serial number like 201310042358) but this does not work (r. 15157073) .
If you want to force Certificate Assistant to use a specific serial number, you can set the LastSerialNumberUsed property in the certificate authority configuration file to a value of one less than the serial number you want.
E. Certificate Information (2)
Fill out the second Certificate Information panel as shown in Figure 10 and then click Continue.
Enter the same name you used in step C. Certificate Basics.
The other fields here are informational and you can fill them out, or not, as you see fit. For example, for a TLS client digital identity you might fill out the fields as shown in Figure 11.
F. Choose an Issuer
In the Choose An Issuer panel, select the certificate authority that you want to issue the certificate—in Figure 12, we only have one, the "MouseCA" certificate authority that we created in Creating a Certificate Authority—and click Continue.
G. Accept Some Defaults
The next four panels all default to reasonable values. Click Continue until you get to the Subject Alternate Name Extension panel.
H. Subject Alternate Name Extension
Fill out the Subject Alternate Name Extension panel as shown in Figure 13 and then click Continue.
This should be checked; leave it that way.
This should not be checked; leave it that way.
Leave this blank.
Leave this blank.
Enter the DNS name of the server here, if it has one.
If the server doesn't have a DNS name, enter its IP address here.
If you are issuing a client identity, you can either not include the Subject Alternate Name Extension (by unchecking item 1) or you can include one with an email address (item 3) or URL (item 4), leaving the other fields blank.
I. Specify a Location
The last panel you see before issuing the certificate is the Specify a Location For The Certificate panel, as shown in Figure 14. Consider the item below and then, when you're ready, click Create.
This defaults to your default keychain. If you want to use a different keychain to keep your issued keychain items separate from your day-to-day keychain items, you can select it here.
J. Conclusion
After Certificate Assistant has issued the certificate, you'll see the Conclusion panel shown in Figure 15. Now close the Certificate Assistant window.
K. Confirm Keychain Items
After closing the Certificate Assistant window you should be back in Keychain Access. You should confirm that the issued certificate and its associated public and private keys are present in the keychain, as shown in Figure 16.
Exporting Digital Certificates and Identities
Once you have these digital certificates and identities in your keychain, you can export them for use in your tests. This section describes various export scenarios.
Exporting the Certificate Authority's Root Certificate
Exporting the certificate authority's root certificate is quite simple. This section describes the process step-by-step.
A. Launch Keychain Access
In Finder, choose Go > Utilities, then find Keychain Access and launch it.
B. Select the Root Certificate
In Keychain Access, select the certificate authority's root certificate, as shown by Figure 17.
Select the correct keychain in the Keychains list. This will be your login keychain unless you've created a separate keychain for your certificate authority keychain items.
Select the All Items category.
Select the certificate authority's root certificate in the keychain item list.
C. Export
Choose File > Export Items. This brings up the sheet shown in Figure 18. Setup your export options and then click Save.
Enter the name of file to export to. In the case the default name is taken from the certificate name and is quite appropriate.
You should always select Certificate (.cer) here, regardless of the final format you need.
D. Convert If Necessary
Some cryptographic toolkits, like the Security framework on OS X and iOS, work best with certificates in their binary form. Other toolkits, most notably OpenSSL, prefer certificates in a textual form. Step B always exports the certificate in binary form. If you want it in the textual form, use the openssl command line tool to convert it. Listing 1 shows how to do this, assuming you exported the certificate as MouseCA.cer.
Listing 1 Convert a certificate from binary to text
$ openssl x509 -inform DER -in MouseCA.cer -out MouseCA.pem |
The textual form of a certificate is known as PEM. The standard file extension is .pem. PEM files can hold more than just certificates. A PEM file that holds just a certificate commonly has the extension .crt (and yes, that means .crt can be used for both binary and textual forms!).
Exporting a Digital Identity
This section describes the steps needed to export a digital identity that was issued by your certificate authority.
A. Launch Keychain Access
In Finder, choose Go > Utilities, then find Keychain Access and launch it.
B. Select the Digital Identity
In Keychain Access, select the digital identity to export, as shown by Figure 19.
Select the correct keychain in the Keychains list. This will be your login keychain unless you've created a separate keychain for your certificate authority keychain items.
Select the My Certificates category.
Select the digital identity to export in the keychain item list.
C. Export
Choose File > Export Items. This brings up the sheet shown in Figure 20. Setup your export options and then click Save.
Enter the name of the file to export to. The default name here is the unhelpfully-generic "Certificates", so it's a good idea to type in the name of the digital identity you're exporting.
You should always select Personal Information Exchange (.p12) here, regardless of the final format you need. This creates a PKCS#12 file which you can convert to the appropriate format later on.
D. PKCS#12 Password
The next step, as shown by Figure 21, is to enter a password to protect the private key embedded in the PKCS#12 file. You should choose a password that's appropriate for the level of security you need. If the private key has limited value (for example, you're only using this digital identity for testing), it's OK to enter a very simple password (in Figure 21, the password was "test").
Enter this PKCS#12 password once into each of the fields and then click OK.
E. Keychain Password
Finally, you must enter the keychain password for the keychain containing the digital identity, as shown by Figure 22. This authorizes the export of the digital identity from the keychain. Once you've entered the password, click Allow.
F. Convert If Necessary
If the cryptographic toolkit you're using works with PKCS#12 files directly, you're done. If you need the digital identity in some other format, you'll have to convert it. For example, if you want to use the digital identity to set up Apache, you have to extract the certificate and the private key as separate PEM files (the certificate typically goes in /etc/apache2/server.crt and the private key goes in /etc/apache2/server.key). Listing 2 shows how to use the openssl tool to do this conversion.
Listing 2 Extracting a digital identity for use with Apache
$ # First extract the server certificate. |
$ |
$ openssl pkcs12 -in "Deep Thought.p12" -nokeys -out server.crt |
Enter Import Password: **** |
MAC verified OK |
$ |
$ # Next extract the server private key. |
$ |
$ openssl pkcs12 -in "Deep Thought.p12" -nocerts -nodes -out server.key |
Enter Import Password: **** |
MAC verified OK |
In both cases you must enter the PKCS#12 password from step D. PKCS#12 Password.
Document Revision History
| Date | Notes |
|---|---|
| 2014-02-13 | New document that describes how to use Certificate Assistant to create certificates for TLS (or SSL) testing. |
Copyright © 2014 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2014-02-13