Smart Card Utility for macOS User Guide

Thank you for using Smart Card Utility for macOS! Whether you’ve purchased Smart Card Utility directly from Twocanoes Software or from the Mac App Store, this User Guide should familiarize you with how to use our application.

PIV smart cards are used to authenticate into a computer and other services. A smart card contains certificates and private keys, unextractable from the card, making authentication via PIN secure.

Smart Card Utility makes using a smart card easy with your Mac. With Smart Card Utility, users can:

• View and Export X.509 Certificates
• Change Smart Card PINs and see remaining PIN attempts
• Sign macOS Packages and Apps
• Enable Smart Card Logging
• Set Identity Preferences
• Use your existing PIV smart card and reader

System Requirements

• A supported version of macOS
• PIV Smart Card (and reader if necessary)

Installation

As mentioned above, Smart Card Utility can be purchased in two ways: through the Mac App Store or directly through the Twocanoes Software website. The installation process is slightly different for each purchase method, Both installation processes are explained here:

Installation for Direct Purchase:

• Your installer and license key profile will be sent via email and added to assets at profile.twocanoes.com after your purchase has been processed
• Install the Smart Card Utility license key profile by double-clicking on the download 
• Go to the Apple Menu > System Preferences, then select Profiles to verify your profile has been installed successfully
• Install the standard macOS package by double-clicking on the installer or deploy it via normal procedures

Installation through Mac App Store:

• Search for “Smart Card Utility” using the search bar
• Download “Smart Card Utility” from Twocanoes Software 

Setup:

When you first open Smart Card Utility, you may see a signup screen. If you’d like to stay informed about updates, feel free to click “Sign Up”. If not, you can click “Ask Later” or “Don’t Show Again”:

(Through App Store Only): You may see an additional Trial screen following the Signup screen. If you’d like to start a 15-day free trial, click “Continue”. Otherwise, click “Buy” to purchase the app via in-app purchase or “Restore Purchase” if you’ve done so already and are looking to apply the purchase to this download.

Navigating Smart Card Utility

Main Screen

When you arrive on the main screen, Smart Card Utility will prompt you to insert a smart card. If one is already inserted before opening Smart Card Utility, it will appear here. Otherwise, insert your smart card to use it within Smart Card Utility.

However, there is some functionality available before inserting a smart card:

• To find additional information about Smart Card Utility, including details on setup, logging, and troubleshooting, click the “More Info” button in the toolbar
• To begin smart card logging before (or after) inserting your smart card, click the “Logging” button in the toolbar
• The toolbar may also be customized by selecting “Customize Toolbar” in the View dropdown or hidden altogether by selecting “Hide Toolbar” under View (also ⌥⌘T)
• Standard window size commands also appear under the Window dropdown (see Keyboard Shortcuts section for associated keyboard shortcuts)

After inserting a smart card, the “Insert Card” symbol is replaced with the smart card’s certificates. For this User Guide, we’ll be using a Yubico YubiKey, but feel free to use any PIV Smart Card and reader combination you may be using.

Before viewing the certificates of the card, you can also view the number of PIN attempts remaining next to the name of the smart card. In our case, we have only three, but smart cards typically begin with ten PIN attempts.

Viewing Certificates

There are two ways to view Certificates using Smart Card Utility. To view the Certificates on the smart card, click the right arrow to the left of the smart card’s name:

In our case, the smart card has certificates in slots 9a, 9c, and 9d, three in total. Smart cards have up to four primary certificate slots. To view a certificate in a slot, open the smart card’s contents by clicking the arrow to the left of its name. Then, click a certificate to select it. The certificate will be highlighted:

Then, select the “View Certificate” button in the toolbar:

Above is the condensed view that appears once you view a certificate. To learn more about certificates in general, feel free to click the “?” icon to be redirected to the macOS User Guide’s explanation of certificates. To stop viewing the certificate and return to the main screen, click OK. 

To view and change Certificate Trust Policies, click the arrow next to the bold “Trust” and scroll down to the now expanded Trust section:

Again, if you’d like more information on what Certificate Trust Policies are, feel free to click the “?” icon to be redirected to the macOS User Guide’s explanation. Using the dropdowns, you can change the trust policies when using the certificate, as well as the X.509 Basic Policy:

Changing a smart card PIN

To change the current PIN, click the “Change PIN” button in the toolbar.

In order to do so, first select the device you’d like to change the PIN for; in this case, we’ll be selecting the YubiKey, but feel free to select any PIV smart card you have inserted into the Mac.

Once the device is selected, you can change the PIN by entering the current PIN in the “Current PIN” field, entering your desired PIN in the “New PIN” field, and confirming the desired PIN in the “New PIN Verification” field:

For security, your PIN is not shown.

An incorrectly typed PIN in the “Current PIN” field shows the above error message; this lets you know that the entered PIN is invalid, as well as the remaining PIN attempts. Removing and reinserting the smart card will update the remaining PIN attempts within the main window of the app. Once you remove and reinsert your smart card, you should see an updated number of remaining PIN attempts:

The above image shows only two attempts remaining. A successful change of the PIN will display this message:

Once your PIN is successfully changed, you may now use the new PIN; your PIN attempts should reset to the maximum number of attempts.

Setting Identity Preferences

To set identity preferences on a certificate, select a certificate in the Main Window:

Then, select the “Identity Preference” button in the Toolbar:

You should see this sheet:

In the text field, add an email, URI, DNS name, or other identifier in order to finish setting up the Identity Preference:

After clicking OK, the Identity Preference is set. The identity preference appears in Keychain Access:

The Identity Preference will now associate the certificate with the specified resource (email, URI, DNS name, etc.).

Saving Certificates

To save a certificate, first select the certificate you wish to save:

Then, click the “Save Certificate” button in the Toolbar with a certificate highlighted:

Here, you can change the name of the certificate, add tags, and select a location to save it to. We’ll change the name to “Certificate 1”, add the Red tag, and change the location to a subfolder within Documents titled “Certificates”:

Once “Save” is selected, the certificate is saved with the name, tag, and location entered. 

In this example, the certificate was saved inside of the “Certificates” subfolder of the Documents folder:

In the “Certificates” subfolder, the certificate from earlier in this example has been saved, with the name, tags, and location specified.

Troubleshooting

If your smart card does not appear in the Main Window when inserted, there are a few ways to attempt to fix the issue:

• Try quitting Smart Card Utility and opening it again
• Go to System Information in your Utilities folder, look at “SmartCards” under Software and verify that your computer recognizes your smart card. If not, you may need to troubleshoot with the smart card itself for your computer and Smart Card Utility to recognize it
• If Date & Time Preferences (under System Preferences) are manually set to an earlier date or time, your smart card may not appear in the Main Window. Set the correct date and time, quit Smart Card Utility, and reopen. This may resolve the issue

If you have questions that weren’t answered by this guide, our product page, our knowledge base pages, or our Smart Card Utility YouTube videos, feel free to reach out at https://twocanoes.com/contact.

Smart Card Utility Keyboard Shortcuts:

• ⌘W: Close
• ⌥⌘T: Hide Toolbar