Deploying Signing Service

Created On
Last Updated On
byTimothy Perfitt
You are here:

Download Signing Manager App

Signing Manager for macOS provides an ideal system for securing code and package signing identities. Implement secure access to the identities with API keys, access controls, and auditing. Gain full control over iOS, macOS, watchOS, and iPadOS signing operations without disrupting the current workflow. Signing Manager works great for developers, CI/CD servers, or for any size team that releases software on Apple hardware.

Signing Service is a web app for managing identities for signing. It is a Rails app and a MySQL database. The certificates are stored in the database and the private keys are either stored in the database or in a Hardware Security Module (HSM). All traffic is encrypted by TLS and all signing requests require a valid API key.

This document provides instructions for setting up Signing Service. It includes a web app, MySQL database, and a web server (NGINX) for TLS. The included database and web server can be replaced by your own infrastructure. However, this document covers how to deploy a functioning Docker deployment of Signing Service.

Requirements

  1. See current OS requirements.
  2. Signing Manager macOS app (provided by Twocanoes). 

Deployment Options

  1. Deploying with Docker Compose Script (recommended)
  2. Deploying with Docker Compose manual
  3. Deploying with a Kubernetes Helm Chart

Preparation for All Deployment Methods

Prep

  1. Install Docker Desktop from https://www.docker.com/products/docker-desktop/. Launch Docker at least once to install the tools.
  2. Allow privileges and secrets and the accept license agreement.
  3. Open Docker and wait for it to start. Note: This may take a few minutes.
  4. Clone repository or download the repository at https://bitbucket.org/twocanoes/signing-service-docker.git. This has this README and a template for docker-compose.yml.
  5. Set the hostname of the docker server. On a Mac, this is done by setting the Sharing name to “sign” to make the Bonjour name “sign.local”.

Post Deploy Testing

Connect to app and test signing

Deploying with Docker Compose Script (recommended)

Hardware Setup:

See current OS requirements.

Script Setup

Make sure you performed the prep setup.

For easy setup, a script called docker_setup.sh is included. If you are deploying on Windows or a cloud service, please see the manual setup. The script will prompt you for a hostname and then generate the required database and app secrets. A docker-compose.yml file will be created. If you want to manually set up the SSL certificate and secrets, see the Manual Setup at the end of this document.

To run the script, cd to the downloaded repository directory and run the script:

bash docker_setup.sh

You will be prompted for the server name. This will be the common name for the SSL server certificate.

Start App

  1. Log in to docker by running this command in terminal:
    docker login
    provide these credentials:
    username: twocanoessoftware
    readonly repo password: e21d3b32-b731-47b1-a16d-b99c4e685486
    successful result: Login Succeeded.
  2. Deploy the app, webserver and database by running: bash docker_deploy.sh  -y
  3. The app is now deployed. You can open it at https://127.0.0.1 on the local machine. The SSL certificate has a host name of “sign.local” by default.
  4. Go to Testing section for testing the deployed app.

Manual setup for docker-compose.yml

If you do not want to use the script to setup the docker-compose.yml, manual instructions are provided below.

Manual Setup

Only do these instructions if you did not run the script. If you ran the script, skip this section and proceed to the Start App section.

  1. Make sure you performed the prep setup.
  2. Copy docker-compose-template.yml to docker-compose.yml and open in a text editor.
  3. Open Terminal and cd to the downloaded repository folder.
  4. Two passwords must be generated for the MySQL database (one for root and one for a MySQL user). The MySQL user password must be specified for the app. A Secret Key Base must be specified for the app as well. Replace the @CHANGEME in the file with the generated passwords following the instructions in the comments in the file. Save the changes.
  5. Generate an SSL certificate and private key in PEM format, convert to hex, and put in environment variables in docker-compose.yml:
  6. Copy docker-compose-template.yml to docker-compose.yml and open in a text editor.
  7. Open Terminal and cd to the downloaded repository folder.
  8. Two passwords must be generated for the MySQL database (one for root and one for a MySQL user). The MySQL user password must be specified for the app. A Secret Key Base must be specified for the app as well. Replace the @CHANGEME in the file with the generated passwords following the instructions in the comments in the file. Save the changes.
  9. Generate an SSL certificate and private key in PEM format, convert to hex, and put in environment variables in docker-compose.yml:

Generate SSL server certificate, accept all default values except Common Name. Make Common Name match the DNS name that you are going to be using for the service. For this example, we will use “sign.local”:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes

    Example Output:

    Generating a 4096 bit RSA private key
    ......................................................................................++
    .................................................++
    writing new private key to 'key.pem'
    -----
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) []:
    State or Province Name (full name) []:
    Locality Name (eg, city) []:
    Organization Name (eg, company) []:
    Organizational Unit Name (eg, section) []:
    Common Name (eg, fully qualified host name) []:sign.local
    Email Address []:

Copy SSLServerCertificate to hex with:

cat cert.pem |xxd -p -c 0

Copy SSLServerKey to hex with:

cat key.pem |xxd -p -c 0

Replace hex for generated values of SSLServerCertificate and SSLServerKey in docker-compose.yml

Start App

  1. Log in to docker by running this command in terminal:
  2. docker login
    provide these credentials:
    username: twocanoessoftware
    readonly repo password: e21d3b32-b731-47b1-a16d-b99c4e685486
  3. Deploy the app, webserver and database by running:
    bash docker_deploy.sh  -y
  4. The app is now deployed.

Go to Testing section for testing the deployed app.

Deploying With Kubernetes Helm Chart

Setup

  1. Make sure you performed the prep setup.
  2. Open Docker Desktop preferences, Under Kubernetes, Enable Kubernetes and click Apply & Restart. Click Install on the presented dialog.
  3. cd to kubernetes/helm_chart/signing-service in the signing-service folder.
  4. Generate an SSL certificate by running:
    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes
  5. Install the ssl certificate by running:
    kubectl create secret tls tls-secret --cert=cert.pem --key=key.pem
  6. log into docker by running this command in Terminal:
    docker login
    provide these credentials:
    username: twocanoessoftware
    readonly repo password: e21d3b32-b731-47b1-a16d-b99c4e685486
  7. Pull the docker image by running:
    docker pull twocanoessoftware/signing-service:LATEST
  8. Install helm:
    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
    chmod 700 get_helm.sh
    ./get_helm.sh
  9. Install Signing Service web app by running:
    helm install sign
  10. Wait until apps are running by checking:
    kubectl get pods
  11. Setup database:
    kubectl exec $(kubectl get pods |grep signing-service|awk '{print $1}') -- bash -c '/var/www/app/bin/rake db:migrate'
  12. Install SSL for service:
    helm repo add nginx-stable https://helm.nginx.com/stable
    helm repo update
    helm install my-release nginx-stable/nginx-ingress
  13. Wait until apps are running by checking:
    kubectl get pod
  14. edit the ingress.yaml file and update the hosts value to match your hostname. Then apply the ingress file to route traffic to the app:
    kubectl apply -f ingress.yaml
  15. Go to Testing section for testing the deployed app.

Testing

Signing into Signing Service

  1. Go to https://127.0.0.1 or https://sign.local and sign in using the following credentials:
    Username: admin
    Password: change_password
  2. Change the password to a new password known only to you. Sign in with the password when prompted.
  3. When prompted, accept the User Agreement.
  4. Click Signing Certificates in the top menu and click Import Signing Certificates.
  5. Upload a p12 that contains a signing certificate and private key. You can export the p12 from your macOS Keychain. When uploading, specify the same password you used when exporting from the Keychain.
  6. Click on API Keys in the top menu, then click on the button to Show Value for the API key. You will need this API key for the macOS client.

Test Signing

  1. Download Signing Manager for macOS from the link on the main page of Signing Service and install on a test Mac.
  2. When the app is initially launched, preferences will automatically be installed. Provide the URL of Signing Service (for example https://sign.local)
  3. Provide the API key copied earlier.
  4. Provide a client name such as “sign_client01”.
  5. Click “Trust Self Signed Certificates”. It is recommended that you use a certificate from a trusted certificate authority during deployment. For testing, select Trust Self Signed Certificate.
  6. Click OK and the certificate loaded from Signing Service will be shown.
  7. Select the signing certificate and click Copy Codesign command.
  8. Sign the app by opening Terminal and pasting in the copied command and then specifying the path to the app. For example:
    codesign -fs "203EA136BA862A5CC9A06AAEB0ABF18A5D939F2B" ~/Desktop/TextEdit.app
  9. Verify the signature using the codesign –verify command. For example:
    codesign -v --verify ~/Desktop/TextEdit.app
  10. Display the signature using codesign -dvvv command. For example:
    codesign -dvvv ~/Desktop/TextEdit.app

Optional Features

Hardware Security Module and PKCS11

Signing Service can optionally store certificates in an HSM (Hardware Security Module) instead of in the local database. This can provide an additional layer of security and management for the certificate content. More info

For all features and more information, see the Signing Manager Administrator Guide