Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(guides): add more detail to code-signing #25794

Merged
merged 7 commits into from
Feb 14, 2023
+27 −10
Merged

docs(guides): add more detail to code-signing #25794

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b44043a
docs(guides): add more detail to code-signing
flotwig Feb 13, 2023
e7b52b4
fix numbering
flotwig Feb 13, 2023
d59b152
Update guides/code-signing.md
flotwig Feb 14, 2023
444adb2
Update guides/code-signing.md
flotwig Feb 14, 2023
9296776
Update code-signing.md
flotwig Feb 14, 2023
c6cee6d
Update guides/code-signing.md
flotwig Feb 14, 2023
6df9f23
Update guides/code-signing.md
flotwig Feb 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 26 additions & 10 deletions guides/code-signing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,36 @@ Code signing is done for the Windows and Mac distributions of Cypress when they

`electron-builder` handles code signing during the `create-build-artifacts` jobs. This guide assumes that the reader is already familiar with [`electron-builder`'s Code Signing documentation](https://www.electron.build/code-signing).

## Installing a new Mac code signing key
## Rotating the Mac code signing key

Follow the directions supplied by `electron-builder`: https://www.electron.build/code-signing#travis-appveyor-and-other-ci-servers
1. On a Mac, log in to Xcode using Cypress's Apple developer program identity.
2. Follow Apple's [Create, export, and delete signing certificates](https://help.apple.com/xcode/mac/current/#/dev154b28f09) instructions:
1. Follow "View signing certificates".
2. Follow "Create a signing certificate", and choose the type of "Developer ID Application" when prompted.
3. Follow "Export a signing certificate". Set a strong passphrase when prompted, which will later become `CSC_KEY_PASSWORD`.
3. Upload the exported, encrypted `.p12` file to the Cypress App Google Drive and obtain a public [direct download link][direct-download].
flotwig marked this conversation as resolved.
Show resolved Hide resolved
4. Within the `test-runner:sign-mac-binary` CircleCI context, set `CSC_LINK` to that direct download URL and set `CSC_KEY_PASSWORD` to the passphrase used to encrypt the `p12` file.

Set the environment variables `CSC_LINK` and `CSC_KEY_PASSWORD` in the `test-runner:sign-mac-binary` CircleCI context.
## Rotating the Windows code signing key

## Installing a new Windows code signing key

1. Obtain the private key and full certificate chain in ASCII-armored PEM format and store each in a file (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN CERTIFICATE-----`)
2. Using `openssl`, convert the plaintext PEM public and private key to binary PKCS#12/PFX format and encrypt it with a real strong password.
1. Generate a certificate signing request (CSR) file using `openssl`. For example:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there a specific openssl version needed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK no, this should work on any modern openssl version. Feel free to validate locally, I checked on Linux.

```shell
# generate a new private key
openssl genrsa -out win-code-signing.key 4096
# create a CSR using the private key
openssl req -new -key win-code-signing.key -out win-code-signing.csr
```
2. Obtain a certificate by submitting the CSR to SSL.com using the Cypress SSL.com account.
* If renewing, follow the [renewal instructions](https://www.ssl.com/how-to/renewing-ev-ov-and-iv-certificates/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When would one renew vs rotate? Only renew if it expired? ideally we don't get to this point right? ALso how long are these certs good for? 6 months? Do we update these in the shared password vault as well with the expiration dates?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rotate if leaked, renew if it's about to expire. Ideally yeah... I can add something to the team calendar to try and act as a reminder. Windows code signing certs last for 3 years max, but we have a 10 year plan with SSL.com so we can renew it a few times without buying again. I'll have to dig deeper into the Apple cert expiry time.

* If rotating, contact SSL.com's support to request certificate re-issuance.
3. Obtain the full certificate chain from SSL.com's dashboard in ASCII-armored PEM format and save it as `win-code-signing.crt`. (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN CERTIFICATE-----`)
4. Using `openssl`, convert the plaintext PEM public and private key to binary PKCS#12/PFX format and encrypt it with a strong passphrase, which will later become `CSC_KEY_PASSWORD`.
```shell
➜ openssl pkcs12 -export -inkey key.pem -in cert.pem -out encrypted.pfx
➜ openssl pkcs12 -export -inkey win-code-signing.key -in win-code-signing.crt -out encrypted-win-code-signing.pfx
Enter Export Password: <password>
flotwig marked this conversation as resolved.
Show resolved Hide resolved
Verifying - Enter Export Password: <password>
```
3. Upload the `encrypted.pfx` file to the Cypress App Google Drive and obtain a [direct download link](http://www.syncwithtech.org/p/direct-download-link-generator.html).
4. Within the `test-runner:sign-windows-binary` CircleCI context, set `CSC_LINK` to that URL and `CSC_KEY_PASSWORD` to the password.
5. Upload the `encrypted-win-code-signing.pfx` file to the Cypress App Google Drive and obtain a public [direct download link][direct-download].
6. Within the `test-runner:sign-windows-binary` CircleCI context, set `CSC_LINK` to that direct download URL and set `CSC_KEY_PASSWORD` to the passphrase used to encrypt the `pfx` file.

[direct-download]: https://www.syncwithtech.org/p/direct-download-link-generator.html