You are here: Front pagePMC documentationUsing the code signing service

Download as PDF

Using the code signing service

The code signing service permits both test signing and production signing.

Production signing costs the ASF real money. The production signing service must only be used once the release process is working using test signing.

Once you are granted access to the siging service, you will be issued with a personal certificate by Symantec. You need this to access the code signing GUI.

The producion system is available at: https://securesigning.websecurity.symantec.com/csportal/

When you submit a signing request, you have an option the option to perform a production signing or a test signing.

GUI

Signing files

This is a quick guide to creating a new signing set. It assumes you have a file or set of files. It uses the Tomcat Windows installer as an example.

  1. Start at the dashboard
  2. Select signing sets
  3. Click "Add Signing set"
  4. Provide a name e.g "Apache Tomcat 8.5"
  5. Provide a version e.g. "8.5.4"
  6. Select the signing service e.g. "Microsoft Windows Signing"
  7. Upload the file(s) to be signed
  8. Click "Sign Now"
  9. Select Test or Production
  10. Click Sign
  11. You can then download the signed files

Adding users

This is a quick guide to adding new users to the PMC's signing organisation

  1. Start at the dashboard
  2. Click "Users"
  3. Click "Add user"
  4. Fill in the form using details (name, asf email etc) as shown in Whimsy
  5. Choose a random enrollment password and send that to the new user
  6. Normally, set all users as admins

SOAP API

The SOAP API documentation is under an NDA. Please do not share it outside your PMC and if you do share it with other PMC members make sure they are aware of the NDA. Note: The previous link is accessible only to ASF members. If you need a copy of the API docs request it via a PMC member who is also an ASF member. If that is not possible, infra can provide a copy.

Ant task

The Apache Tomcat project has written an Ant task that uses the SOAP interface to sign release artefacts as part of the build process.

In order to use the SOAP interface, your PMC account needs to be enabled for API accessed. Please open an INFRA Jira ticket against the code signing component to request this. Once this is approved you will be given:

  1. user name
  2. password
  3. partner code

You will need all three to access the API.

Note that this Ant task currently uses a fixed buffer of 16MB to store the zipped artefacts for signing. If yoru artefacts are larger than that, you will need to use a larger buffer. Patches to switch to streaming the artefacts rather than buffering them welcome.

Maven plug-in

This is a work in progress.

Signing services

You will also need to specify the name of the signing service to use. The names are shown in the table below:

Arftefact typeTest signing service nameProduction signing service name
Windows binary (.exe, .dll, .cab, etc.)Microsoft TEST SigningMicrosoft Windows Signing
Java Signing (*.jar)Java TEST SigningJava Signing

Both SHA1 and SHA256 versions of the Java Signing service are available. Generally the SHA256 service is recommended. However, if you are re-signing JARs that have already been signed you'll need to ensure you use the same hash algorithm as the original signature else you will break the original signature.

Java signing is not intended to replace the current requirement for releases to be OpenPGP signed. Neither is it intended to replace the process of providing OpenPGP signatures for JARs uploaded to Maven central. It is intended for those use cases that require individual JAR files to be signed using the standard Java JAR signing process where the signature is contained within the JAR. Such us cases include Java Web Start, Eclipse plug-ins, etc.

Signing events

A signing event is the process of signing one or more files. Whether you use the web GUI or the SOAP API, the files must have unique names. This might require files to be renamed prior to signing and renamed back afterwards. Note that this does not affect the signature of the file.

We have discovered that the signing service is particular about file extensions. If you do rename the file, ensure that you retain the correct file extension.

Each signing event can be reverted individually.

It is possible to request production or test signing on both the production and test systems. Note only a production signing event on the production system costs the ASF a code signing credit.

It is recommended that projects start testing with production signing on the test environment and get their process working there before moving to the production environment.