CINXE.COM
Using the Digicert code signing service - Apache Infrastructure Website
<!doctype html> <html class="no-js" lang="en" dir="ltr"> <head> <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Using the Digicert code signing service - Apache Infrastructure Website</title> <link href="/css/bootstrap.min.css" rel="stylesheet"> <link href="/css/fontawesome.all.min.css" rel="stylesheet"> <link href="/css/headerlink.css" rel="stylesheet"> <script src="/highlight/highlight.min.js"></script> </head> <body class="d-flex flex-column h-100"> <main class="flex-shrink-0"> <div> <!-- nav bar --> <nav class="navbar navbar-expand-lg navbar-dark bg-dark" aria-label="Fifth navbar example"> <div class="container-fluid"> <a class="navbar-brand" href="/"><img src="/images/feather.png" style="height: 32px;"/> Apache Infrastructure</a> <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarADP" aria-controls="navbarADP" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <div class="collapse navbar-collapse" id="navbarADP"> <ul class="navbar-nav me-auto mb-2 mb-lg-0"> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">About</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/infra-news.html">News</a></li> <li><a class="dropdown-item" href="/blog/">The Infrastructure Blog</a></li> <li><a class="dropdown-item" href="/roundtable.html">The Infrastructure Roundtable</a></li> <li><a class="dropdown-item" href="/team.html">About the team</a></li> </ul> </li> <li class="nav-item"> <a class="nav-link" href="/policies.html">Policies</a> </li> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Services and Tools</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/services.html">Services and Tools</a></li> <li><a class="dropdown-item" href="https://blocky.apache.org/">Blocky</a></li> <li><a class="dropdown-item" href="https://app.datadoghq.com/account/login?next=%2Finfrastructure">DataDog</a></li> <li><a class="dropdown-item" href="https://whimsy.apache.org/roster/committer/" target="_blank">Committer Search</a></li> </ul> </li> <li class="nav-item dropdown"> <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> <ul class="dropdown-menu"> <li><a class="dropdown-item" href="/doc.html">Contribute</a></li> <li><a class="dropdown-item" href="/infra-volunteer.html">Volunteer with Infra</a></li> <li><a class="dropdown-item" href="/how-to-mirror.html">Become an ASF download mirror</a></li> <li><a class="dropdown-item" href="/hosting-external-agent.html">Host a Jenkins or Buildbot agent</a></li> </ul> </li> <li class="nav-item"> <a class="nav-link" href="/stats.html">Status</a> </li> <li class="nav-item"> <a class="nav-link" href="/contact.html">Contact Us</a> </li> </ul> </div> </div> </nav> <!-- page contents --> <div id="contents"> <div class="bg-white p-5 rounded"> <div class="col-sm-8 mx-auto"> <h1> Using the Digicert code signing service </h1> <h2>Transition to DigiCert</h2> <p>The ASF used Symantec's Secure App Service to provide Windows and JAR code signing functionality from 2014 to 2019. In 2019 the ASF moved from the Symantec service to DigiCert ONE. All new signing must be via the DigiCert service.</p> <p>If you require assistance migrating to the DigiCert service, please open an <a href="https://issues.apache.org/jira/browse/INFRA">INFRA Jira ticket</a> and select code signing as the component.</p> <h2>DigiCert Secure Software</h2> <p>DigiCert Secure Software supports a range of signing tools and formats. For the full list see the <a href="https://digicert.github.io/snowbird-doc/#/administration-guides/secure-software-manager/index">client user guide</a>. Whichever signing option you choose, you will need to complete four steps:</p> <ol> <li>Obtain a DigiCert ONE account</li> <li>Obtain credentials for code signing</li> <li>Install the OS integration for your chosen OS (Windows or Linux)</li> <li>Configure your chosen signing tool</li> </ol> <p><strong>Note</strong>: The ASF has to pay for each signature using a signing certificate. Using Jenkins to build and sign <strong>releases</strong> using DigiCert ONE is fine. Signing every single <strong>CI build</strong> is not necessary and can become expensive for the Foundation. Please make sure your build process only involves signing certificates for release candidates.</p> <h3>Step 1: Obtaining a DigiCert ONE account</h3> <p>Adding a new PMC or a new user to an existing PMC needs to be performed by the infrastructure team. Please open an <a href="https://issues.apache.org/jira/browse/INFRA">INFRA Jira ticket</a> and select code signing as the component.</p> <p>When the infrastructure team creates your account you will receive a password reset email. The link in that email is only valid for 12 hours. If you are unable to complete the creation of your account in that time you can request a new password reset email by going to <a href="https://one.digicert.com/" target="_blank">DigiCert ONE</a> and clicking the password reset link. Your username is your ASF email address. You should then receive a new password reset email you can use to set your password.</p> <p>You also need to configure your OTP token. Officially, only Google authenticator is supported but any similar tool should also work.</p> <h3>Step 2: Obtaining credentials for code signing</h3> <p>Whatever you need to sign and however you choose to sign it, you need to create credentials to use the signing API. You create these via the DigiCert ONE web interface.</p> <ol> <li>Log on to <a href="https://one.digicert.com/">DigiCert ONE</a>.</li> <li>Select "Account" from the menu in the top right-hand corner.</li> <li>Select "Access" in the left-hand menu.</li> <li>Select "API token" and create a new API token with a unique name (e.g. ASF ID + year) as the name and an expiry date ~1 year in the future.</li> <li>Keep a record of the token value</li> <li>Select "Client Auth" and create a new client certificate with a unique name (e.g. ASF ID + year) as the name and an expiry date ~1 year in the future.</li> <li>Download the certificate and keep a record of the password</li> </ol> <h3>Step 3: Install the OS integration</h3> <h4>None</h4> <p>If you use JSign 4.0, you can skip this step.</p> <h4>Windows integration</h4> <ol> <li>Log on to DigiCert ONE and select "Secure Software" from the menu in the top right-hand corner.</li> <li>Select "Resources" in the left-hand menu.</li> <li>Download and install the "Secure Software Manager Windows Clients Installer".</li> <li>As per the <a href="https://docs.digicert.com/en/digicert-one/software-trust-manager/general/secure-credentials/set-up-secure-credentials-for-windows.html" target="_blank">Windows Configuration</a> section of the client user guide, create the four system environment variables. These <strong>must</strong> always be set to use the DigiCert signing service.</li> <li>Test with <code>smctl.exe keypair ls</code>. You should see at least one certificate listed. (smctl.exe is installed as part of the DigiCert client and won't be on your path.)</li> <li>Test with <code>certutil.exe -csp "DigiCert Signing Manager KSP" -key -user</code>. You should see at least one key listed. (certutil.exe will be on your path.)</li> <li>Synchronise certificates with <code>smksp_cert_sync.exe</code>.</li> <li>Open <code>certmgr.msc</code> (it will be on your path) and you should see your code signing certificate(s) listed under personal certificates. If a new certificate is issued to your PMC you will need to repeat this step.</li> </ol> <h4>Linux integration</h4> <ol> <li>Log on to DigiCert ONE and select "Secure Software" from the menu in the top right-hand corner.</li> <li>Select "Resources" in the left-hand menu.</li> <li>Download and install the "Secure Software Manager Linux Clients (Portable tar.gz)".</li> <li>Unpack the tar.gz. Infra recommends, and this guide assumes, it is unpacked to <code>/opt</code></li> <li>As per the DigiCert ONE documentation, create the four required environment variables. These <strong>must</strong> always be set to use the DigiCert signing service. Infra recommends you store your certificate in <code>~/.digicertone/</code>.</li> <li>Test with <code>/opt/smtools-linux-x64/smctl keypair ls</code>. You should see at least one certificate listed.</li> </ol> <h4>MacOS</h4> <p>The DigiCert ONE client tools are not available for MacOS. Use JSign 4.0 so you can skip this step.</p> <h3>Step 4: Configure your chosen signing tool</h3> <h4>Signing Windows binaries on Windows using signtool.exe</h4> <p>To sign Windows binaries you need a copy of SignTool.exe. This utility is in both Visual Studio and the Windows SDK. Very old versions only support SHA-1 signing. Version 6.1.7600.16385 (2009-07-14) supports newer hashes for signing.</p> <p>You need the fingerprint of the certificate you want to use for signing (view via <code>certmgr.msc</code>). You can then sign a file with <code>signtool.exe sign /sha1 <cert-fingerprint> /td sha1 /fd sha512 /tr http://timestamp.digicert.com <file-to-be-signed></code>.</p> <p>To sign a file with SHA-256 rather than SHA-512 use <code>... /fd sha256...</code> rather than <code>... /fd sha512 ...</code>.</p> <h4>Signing on Windows binaries on Windows or Linux with JSign 4.0+ Ant task</h4> <ol> <li> <p>Make the JSign JAR from <a href="https://search.maven.org/artifact/net.jsign/jsign">Maven Central</a> available to Ant.</p> </li> <li> <p>The DigiCert ONE specific properties for the JSign task in Antshould be as follows:</p> <pre><code> storetype="DIGICERTONE" storepass="<api-key>|<path-to-client-certificate>|<client-certificate-passphrase>" alias="<name-of-signing-certificate>" tsaurl="http://timestamp.digicert.com" </code></pre> </li> </ol> <h4>Signing Windows binaries on Linux with JSign 4.0+</h4> <ol> <li> <p>Download jsign <code>wget https://github.com/ebourg/jsign/releases/download/4.0/jsign_4.0_all.deb</code>.</p> </li> <li> <p>Install jsign <code>sudo dpkg --install jsign_4.0_all.deb</code>.</p> </li> <li> <p>You should then be able to sign with:</p> <pre><code> jsign --storetype DIGICERTONE --alias <name-of-signing-certificate> --storepass "<api-key>|<path-to-client-certificate>|<client-certificate-passphrase>" --tsaurl="http://timestamp.digicert.com" application.exe </code></pre> </li> </ol> <h4>Other signing formats, tools and operating systems</h4> <p>See the client user guide.</p> </div> </div> </div> <!-- footer --> <div class="row"> <div class="large-12 medium-12 columns"> <p style="font-style: italic; font-size: 0.8rem; text-align: center;"> Copyright 2024, <a href="https://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> Apache® and the Apache feather logo are trademarks of The Apache Software Foundation. </p> </div> </div> <script type="application/ecmascript" src="/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"></script> </div> </main> <script>hljs.initHighlightingOnLoad();</script> </body> </html>