Code Signing != Strong Name Signing

Note: This post was updated on 9/16/2017 with some corrections. In addition, a much easier way was discovered and that's been written about in Part 2. You'll still want to read this part since there's a lot here that isn't covered in the follow-up, but skip the Visual Studio related steps.

First things first, strong naming and Code Signing and Strong Naming serve two different purposes. Code Signing (referred to by the trademarked “Authenticode” in the Microsoft world) verifies a library or executable originated from a person or organization.

A Code Signing key validates identity. Code Signing keys are most similar to EV certificates (and, in fact, require the same kind of validation involving a notary, lawyer or CPA and a bunch of documentation proving your name, address, phone and other things).

A Strong Name in .NET adds a signature to a library or executable that ensures that when a program references that library or executable, that it’s getting the right one. When the .Net Framework validates a library’s strong name, it doesn’t care what the origin of the signature is, or its trust chain. It simply cares that the key is right. So for all practical purposes, there’s really no great reason to use your code signing certificate to generate the strong name.

So … why do it then?

My reasons boiled down to a few things. First, I like to strong name my libraries if they’re going to be put out on a NuGet server (either the public one or the one I use internally at work or at home). The main reason is that I use some of these libraries in projects that require strong names, so it’s an added convenience not to have to ildasm/ilasm sign them on a one-off basis. It’s also helpful to others who might use those libraries.

The problem is that I can be a little absent-minded and on at least one occasion, I published a strong name key to a public git repo. Whoops! I know and follow best practices with certificates that I use, but for whatever reason, I treated this “generated on-the-fly” keypair with reckless abandon.

When I acquired my code signing key, I understood the value of what I was getting. My key would serve as a positive identity of me when anyone used an executable signed with it. I purchased a Yubikey to store the key. The Yubikey is basically a USB Smart Card device. Smart Cards work by storing the private key in non-exportable storage and performing all cryptographic operations on-device.

I generated the CSR on a Linux live CD and ensured I made a backup only to an encrypted storage medium protected by a different password than the PIN on my Yubikey. In theory, at least, that private key has never seen the Internet, and will never exist in storage or memory of any machine I sign software on.

All of that trouble also means that if I use that same key for strong name signing, I can never accidentally publish the private key in a repo. Like any good security process, the best way to prevent a leak is to make it impossible to leak.

Strong Name Signing with a Yubikey

To strong-name sign, you use the sn.exe tool. Unfortunately, it’s not exactly straight-forward to use this tool with a certificate installed to a Smart Card. It’s, apparently, done so infrequently, that the documentation gives very few hints as to how to actually accomplish it.

Step 1 - Get the Smart Card Crypto Provider

The first thing you need to do is point sn.exe at the right crypto provider. By default, the sn tool uses the Microsoft Base Cryptography Provider, which won’t find the key on your Smart Card. By default, Windows 8+ uses the Microsoft Base Smart Card Crypto Provider for smart cards, but if you’ve installed other smart card providers (OpenSC), this may be different, so we’ll verify that.

Launch an Administrator PowerShell prompt – keep it open because we’ll use it later – but for now, run the following:

CD HKLM:\SOFTWARE\Microsoft\Cryptography\SmartCards
gci *yubikey*

Look for Crypto Provider. That’s the provider for your yubikey. Open up a (non-administrator) Developer Command Prompt and cd to the folder that has the library you want to sign. Run the following command:

$ sn.exe -c "Microsoft Base Smart Card Crypto Provider"

Replace Microsoft Base Smart Card Crypto Provider if the Crypto Provider, above, was different.

Step 2 - Get the Key Container Name

This switches the default provider to your Smart Card. Now for the tricky part. We need to find the Key Container name for your code signing key. I’ve written a script (signed, of course) that will print the key container for your code signing key, provided it’s stored within your user’s Personal key store (which, AFAIK, it needs to be there, so if you don’t have it stored there you’ll need to figure that bit out).

Download the gist for the script here. Save the file and run it.

.\Get-CodeSigningKeyContainer.ps1

It’ll output something along the lines of:

Code Signing Key Located
Subject: CN=Matthew S. Dippel, ...
Thumbprint: 983894AA3EB7BEA35D01248F6F01C3A64117FA66
Container Name: 'c0f031c2-0b5e-171b-d552-fab7345fc10a'

Do a sanity check on the Subject/Thumbprint to make sure you’ve got the right key and if you’re happy with it, grab the text between the apostrophes on the last line. In the future (or if you want to use it as part of a script), you can run it with the -Quiet parameter and it’ll just spit out that value.

Step 3 - Generate a Signing Key that Contains Only the Public Key

Strictly speaking, I’m not sure if this is actually required, but it’s the only way I could get it to work. I’d like to find a workaround, and I’m guessing one exists possibly related to the AssemblyKeyContainerName attribute, but much like this whole process, it’s poorly documented and I couldn’t make it work. If I figure it out, I’ll update this post accordingly.

In your protect folder (or solution directory – really, the location doesn’t matter much), run the following command in the Developer Command Prompt:

sn.exe -pc "c0f031c2-0b5e-171b-d552-fab7345fc10a" key.snk sha256

Replace the c0f031c2-0b5e-171b-d552-fab7345fc10a with your container name from the PowerShell script above.

What we’re doing here is asking the Strong Name tool to produce the file key.snk with only the public key (after all, we’re using a Smart Card that has no way of providing sn.exe with the private key). We’ve told it to use SHA-256, explicitly since (I think) it defaults to SHA-1 which is considerably weaker.

Step 4 - Tell Visual Studio to Use The Key and Delay Sign

This is the lousy part. We have to delay-sign, which is supposed to kill the debugger. We’ll update the project to finish the signing process once the build is finished, but I’m not sure if that will add some steps to debugging (I just figured this out this evening and haven’t gotten that far in testing, yet). Right-click the library project and choose Properties. Go to the Signing tab. At the bottom, check the box that says Sign the assembly. In the drop-down box, pick <browse> and select the key.snk you generated, above. Then, check the box that says Delay sign only.

Build the project. You may notice a small hang after build starts, followed by your PIN entry prompt. Provide your smart card’s PIN and build will continue.

If you see it sitting there for more than a few seconds, hit ALT+SHIFT+TAB and you’ll see your PIN entry prompt pop up (ALT-TAB works, too, but every time this has happened to me, the PIN entry dialog has been the last item in the window list).

Step 5 - Signing the Library Manually

We’ll automate this as part of the build, shortly, but it’s helpful to do it by hand, once, since you’ll see the output for the signing operation in the command prompt and won’t have to hunt through build output. Go back to that Developer Command Prompt and cd to the output folder that has the .dll or .exe file that was generated from the build.

Run the following command:

sn.exe -Rc MyLibrary.dll "c0f031c2-0b5e-171b-d552-fab7345fc10a"

Note the change in order between the -pc and the -rc commands. This one does the file first. What you’ve done here is Re-signed the file with the signature. If everything worked, you should have had a window pop up asking for the PIN from your smart card.

Step 6 - Bonus - Code Sign the Library/Executable

As I mentioned, above, strong name signing isn’t Code Signing. If you want your library to be Authenticode signed, you’ll need to do that separately. If you’ve got a Comodo certificate, you can use the following command in the Developer Command Prompt. There’s a few ways to do this, but I use the following command:

SignTool sign /fd sha256 /tr http://timestamp.comodoca.com/?td=sha256 /td sha256 /as /v MyLibrary.dll

When you’re using a Code Signing certificate on a Yubikey, provided there’s only one code signing certificate in your certificate store, there’s no need to point it at the specific certificate. You’ll see output indicating that the library/executable was signed properly.

There’s one thing worth noting here, though. If you need compatibility with Windows Vista or Windows XP, you need to sign the executable twice. The above method will only work for Windows 7 and above. To sign in a manner that is compatible with Windows XP and above, yet still includes the more secure signature for Windows 7 and above, use the following commands:

SignTool sign /t http://timestamp.comodoca.com /v MyLibrary.dll
SignTool sign /fd sha256 /tr http://timestamp.comodoca.com/?td=sha256 /td sha256 /as /v MyLibrary.dll

The first command signs in a Windows XP/Windows Vista compatible manner, the second is identical to what we did, above.

What About Non-Comodo Certificates? A note about Timestamp

I’m really not sure; I don’t have one. The issue is with that /t http://timestamp.comodoca.com switch. You can leave it off but it’s an exceptionally bad idea. Your code-signing certificate expires at some point, or you may lose the private key and need to get another one issued, which will revoke the current one. The certificate you’re using isn’t all that much different than one that is used for EV domains. When those expire, you replace the certificate on the server and everything’s fine. You can’t, however, replace the signatures on all of the things you’ve signed that have been copied onto other peoples’ machines. To address this situation, a timestamp service is used – that’s what this URL points to.

I assume the COMODO timestamp service is meant to be used with COMODO certificates. Chances are good that the company that you purchased yours from operates their own. Consult their site to see what the appropriate values are for that (bearing in mind that there are two kinds of timestamp services that require slightly altered parameters regarding /tr and /td).

There is also one out there that allows for its use provided you make very few requests. Whatever timestamp service you use, make sure you consult the support area to determine what the request limits are.

Finally - Automating it All

Having to do all of these steps every build is a bit much. Let’s add some post-build steps to automate it all. Go back to the project properties and choose Build Events.

Put the following into the Post Build (see the note below to make sure you change the right things):

"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.2 Tools\x64\sn.exe" -c "Microsoft Base Smart Card Crypto Provider"
"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.2 Tools\x64\sn.exe" -Rc "$(TargetPath)" "c0f031c2-0b5e-171b-d552-fab7345fc10a"
"C:\Program Files (x86)\Windows Kits\10\bin\x64\signtool.exe" sign /fd sha256 /tr http://timestamp.comodoca.com/?td=sha256 /td sha256 /as /v "$(TargetPath)"

IMPORTANT: Those are the paths to the files on my system. Check the path to sn.exe and signtool.exe and make sure to replace the Crypto Provider and put in your key container. Mine isn’t going to work for you.

Save everything.

The good news is that for every other project, all that’s required is running the sn.exe -c and sn.exe -pc (Step 1 and 2) once for each project and pasting whatever you ended up with above in the project properties. It’ll make repeating this for anything else you’ve got very easy. It’s also portable between machines (provided the paths are the same, though you can replace those with environment variables for Program Files and such). The key container name will be the same on other machines (there’s some caveats here that relate to having more than one copy of the key or having more than one smart card which I ran into, however, you could use the Key Container script above to get the container name on every build, too).

There’s a bit of bad news, though:

• You’re going to get prompted for your pin not once, not twice, but three times on every build. I’m not aware of any functionality that allows the OS to cache this operation, but if I find it, it’ll be the first thing I fix since that’s obnoxious.
• Your project will not build without your Yubikey or Smart Card. This also means that if your project is open source, people downloading your code will get build errors. Obviously, you don’t want strangers to be able to sign your code with your key, but you do want them to be able to build an unsigned version. Make sure you add a note on how to work around this issue to your readme.md file.

Once you’re all done, build the project and type that PIN three times.

Troubleshooting

I’ve had a pretty terrible time getting this to work, and ran into a few gotchas. These are from memory and may not be correct, but I’m leaving them here as things to try if you get stuck

It probably matters if you’re running elevated

I had a few projects in the past that couldn’t be debugged unless Visual Studio was launched as an administrator. I’m fairly certain that the act of elevation will cause problems in locating the certificate in your personal user store, which is why I specified “A non-administrator Developer Command Prompt” above. If you can’t get the project to build and it complains about not being able to find the key, make sure you’re running without UAC elevation as the user who has the key in their personal certificate store.

More Than One Smart Card

My laptop has a TPM and for convenience, I created a Virtual Smart Card from the TPM module (it’s a cool feature that makes your TPM emulate a Smart Card and it basically negates the need for having a Yubikey). The problem is that the Virtural Smart Card will be the one that’s selected, not the Yubikey, when you set sn.exe to use the Smart Card Provider if the two smart cards share the same provider. I’m sure there’s a better workaround, but since I have a Yubikey, I simply deleted the TPM Smart Card.