Sign App File – part 2

Quite a while ago I wrote about signing your app file, which is a requirement for AppSource. It’s been a while since I had to do this, so I went back to my blog and found the article quite lacking. This post is an attempt to fill in the blanks and give you all the information that you need to sign your app, all in one place.

Your first stop to read about this is right here, the Learn page about signing the app file specifically for Business Central. Most of what I’m about to tell you is in there, I’ll just elaborate a little bit more.

Basically, signing an app file, or an executable file, is a way to tag that file with an attribute that certifies where the file came from. If Acme Rockets signs their rocket skate app, the file has an attribute that shows Acme indeed digitally signed it. Take a look at the properties for ‘explorer.exe’, the executable for Windows Explorer. You can check out the digital signature that verifies that this file was signed by Microsoft.

In a nutshell, you need the following:

  • A Code Signing Certificate, in ‘pfx’ format
  • A code signing tool (I’m using ‘signtool’ here)
  • The SIP from your BC container (don’t ask, I still don’t really know)
  • A script to actually sign

Code Signing Certificate

The first thing that you need is the Code Signing certificate. This is a particular type of certificate (NOT the same as an SSL certificate) that you must get from an Authenticode licensed certificate authority (there’s a link in the Docs article mentioned above) such as this one or this one or this one or this one. I’m not affiliated with either one, and GoDaddy doesn’t seem to provide code signing certificates anymore, but I’ve worked with certs from two of those companies and they both worked as advertised. For AppSource submissions, you need the regular “Code Signing”, not the extended one or the one for drivers. Go shopping, because I’ve seen prices range between $199 and $499 per year for the same thing.

In order for the signtool to be able to use the certificate, it must be in ‘pfx’ format. One of the providers that I mentioned has a page here that explains how you can create this file format. The actual file will have a password on it, and you can save it on the computer where you have NAV/BC installed, or where your container lives. I usually have a working folder right in the C root where I do this kind of thing.

The Signing Tool

You’ll need a tool to sign the app file – Microsoft recommends SignTool or SignCode. Since their sample script is for SignTool, that’s the one that I used. Now, the text in Docs describes that SignTool is automatically installed with Visual Studio, but that is only partially true. I actually downloaded Visual Studio to see if that works, but the installation configuration that I chose did not include SignTool.

Signtool is part of the Windows SDK, which probably comes in one of the standard Visual Studio configurations. I don’t know which one, so you’ll have to make sure that it is selected when you are installing it. Another way to get it installed is to install the Windows SDK directly, which you can download here. I installed the one for Windows 7 on a Windows Server 2019 Hyper-V VM, and it worked for me. I know, I should have looked a little longer and used the Windows 10 one, but by that time my app file was already signed and dinner smells were filling my office.

The SIP

If you try to sign your app file now, you will probably get an error message that the app file is not recognized. The SignTool program needs to be able to recognize the app file, and for that purpose it needs to have something called ‘the SIP’ registered on the machine where you run the SignTool command. Apparently this is some sort of hash/validation calculation package that is used to create digital signatures. Each program on your computer apparently has one of these.

One way to get ‘the SIP’ is to install NAV/BC on the computer. If you’re like me, and you use containers exclusively, you won’t want to do this. Luckily, the NavContainerHelper module has a Cmdlet to retrieve ‘the SIP’ out of the container.

 Install-NAVSipCryptoProviderFromBCContainer YourContainerName 

This Cmdlet gets ‘the SIP’ out of the container and registers it on the host. At this point, you should be all set to sign your app file.

Script to Sign

The last element is the command to actually create the digital signature. Not much to say about that, so here it is:

"C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\signtool.exe" sign 
    /f "C:\WorkFolder\CodeSignCert.pfx" 
    /p "Your Password" 
    /t http://timestamp.verisign.com/scripts/timestamp.dll "C:\YourRepo\Publisher_AppName_1.0.0.0.app"

As you can see, my SignTool is in the Windows 7 SDK folder, you may need to search around for it. Installing the SDK is supposed to register SignTool and you should be able to just use ‘signtool’ as a command. For some reason that did not work for me, which is why I specified the entire path. I split this up to make it look better in this post, the command needs to all be on one line.

One more thing – the timestamp specifies that the file was signed using a certificate that was valid at the time of signing, and the file itself will never expire. Of course if you want to submit a new file after the certificate has expires, you will need to get a new one. If you don’t specify the timestamp, your app file will expire on the same date as your certificate.

Update March 26, 2020 – The timestamping service was provided by Symantec and it looks like they are rebranding that to ‘digicert’. Here is an article that explains the situation. You will need to change the timestamp part in your script:

Replace:
/t http://timestamp.verisign.com/scripts/timestamp.dll 
With this:
/t http://timestamp.digicert.com?alg=sha1

All Set

That’s it, you should be all set to sign your app file. I have to be honest and confess that I wrote this mainly for myself, because I spent WAY too much time trying to re-trace my steps and figure out how this works again. It’s now in a single post, hope it helps you as much as it helped me.

Update – March 18, 2020

Turns out, there is a simple command for this….

$MyAppFile = "C:\ProgramData\NavContainerHelper\Extensions\Publisher_AppName_1.0.0.0.app"
$MyPfx = "C:\ProgramData\NavContainerHelper\Extensions\CodeSignCert.pfx"
$MyPassword = ConvertTo-SecureString "Your password" -AsPlainText -Force
$MyContainerName = "YourContainer"

Sign-NavContainerApp -appFile $MyAppFile -pfxFile $MyPfx -pfxPassword $MyPassword -containerName $MyContainerName

No need to install anything. All you need is the app file and your pfx file with a password, and everything else happens in the container (as Freddy puts it “without contaminating the host”). Just copy both files into a shared folder where NavContainerHelper can read the files.

Mark Down your Documentation

We all have great intentions when we start a new project that THIS TIME we are going to create the best awesomest documentation! Yet somehow, when we are knee deep in testing, when we are wrestling product owners and project management types about scope creep, documentation seems to always fall by the wayside. What if I told you that there was a relatively easy way to include documentation in your development workflow?

Over the past few months I have been working on a number of apps that one of my clients is planning to submit to AppSource. One of Microsoft’s requirements (which you can read here in the Technical Validation Checklist) is that each app submission has what they call ‘User Scenario Documents‘. Another requirement, this one from the Marketing Checklist is that the publisher provides online help. These sound awfully similar to the requirement that you must provide a test app that includes automated tests for the user scenarios that I mentioned just now. These three requirements result in an awful lot of writing, and they all essentially cover the same thing.

As I was organizing the apps that I am working on, I started looking around at how various companies have provided their documentation, with of course Microsoft as the shiny example. You see, I’ve been a big fan of the way that they have moved their documentation to docs.microsoft.com. Not only do they have away to provide direct feedback (which I’ve written about before here), as it turns out, their actual documents are in a public repository that we as members of the community can contribute to. The source documentation is written in what is called ‘Markdown’, and there is a build process that publishes the documents into the Docs website. These tools are often capable of outputting the content in multiple formats. You might be able to Generate your user documentation as well as your online help from the same source content.

Now before we get all fancy and automated, let’s go over the basics first.

Workflow

The documentation itself is done in so-called markdown files. Basically Markdown is a way to tag content with formatting. It is very similar in structure (not syntax) to HTML, which is not a coincidence because markdown was originally conceived as a text-to-HTML conversion tool.

You create *.md files with the text, plus image files for screenshots and such, and you structure the help content using the markdown formatting. It’s very simple and rudimentary, and this is totally by design. It takes a little effort to get used to it, but it’s actually quite simple to master, and it looks great very quickly.

Because you create separate *.md files for each topic, and you keep the images as separate files as well, markdown is absolutely PERFECT to be source controlled. At the moment I am simply including a ‘Documentation’ folder in my repository, so I am keeping my documentation inside my development repository. If you read my “Two Apps, One Repo” post, the documentation folder is at the same level as the other app root folders.

The Business Central documentation, for instance, is on a separate repository on its own, completely separate from the source code of the application itself. You could totally choose to track the documentation separately. There is no one way to do it, you can fit your process to your own needs.

I’ve been told that there are tools out there that will convert markdown to a number of different targets such as PDF, HTML, and even Word. I don’t really want to spend a bunch of time trying figure those out, so let me stop at covering markdown itself. As I move into creating the documentation targets, I will follow up here.

The important take-away here is that you can include documentation in source control. As such, you can make it part of your development process, and track it to work items.

Resources

Here are some useful resources for Markdown itself, and some tools that convert markdown to other formats like PDF and HTML:

  • Introduction to Markdown by the guy that invented it. Not very descriptive or a particularly good reference, but kudos to him for coming up with the simple and powerful concept
  • Since we’re working with Microsoft products, and because they have taken a lot of time to establish a good process, I must include their time to document their guide for authoring for Business Central. You will want to read the Style Guide, look for the link in that post
  • I asked the community how they create help files and documentation, and was referred to this guy that works for/with Microsoft (as far as I can tell he is an external resource who manages the Docs team). He’s put together a video about their process, included in this blog post. He is very responsive on Twitter, so ask him if you have any questions
  • I have to include this post by Eva Dupont, who is responsible for all Business Central content in Docs. I’ve mentioned this before, but it needs to be repeated as many times as I can. She also wrote a handy primer on migrating your help files.

You can also check out the many really good responses that I received when I asked the community:

I’m just collecting information at this point. There’s lots of good ideas, lots of tools to help get there, it’s just a matter of picking the ones that fit your process. For me I’ll try to keep it simple and effective, and I have a feeling that my clients will have strong opinions as well. I’ll keep you posted on what will happen.