Skip to content

Commit 0355db3

Browse files
seanbuddseanbudd
authored
Merge d51a839 into 1751403 
2 parents 1751403 + d51a839 commit 0355db3

1 file changed

Lines changed: 116 additions & 0 deletions

File tree

‎devDocs/selfSignedBuild.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Creating a self-signed build
2+
3+
These instructions are based on Microsoft documentation to [create a self-signed certificate](https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing).
4+
5+
### WARNING
6+
Copies of NVDA signed by a self-signed certificate will not function on systems where it is not installed as a trusted root certificate, so this is only suitable for personal use.
7+
8+
Following are instructions on how to generate and install a self-signed certificate.
9+
This is not supported and should only be attempted by developers who know what they are doing and are aware of the risks.
10+
If the private key is compromised, this poses a serious security risk to your system.
11+
12+
Do not forget to [remove the certificate](#remove-the-certificate) when you are done testing.
13+
14+
### Create a self-signed certificate
15+
16+
Using [PKI](https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing#prerequisite), create a self signed build with a custom name (`FriendlyName`) and publisher (`Subject`).
17+
Other parameters are determined by [MS docs](https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing#use-new-selfsignedcertificate-to-create-a-certificate).
18+
19+
From PowerShell:
20+
```ps1
21+
New-SelfSignedCertificate -FriendlyName "LocalNVDA" -Type Custom -Subject "CN=Test NVDA Build, O=NVDA Dev, C=US" -KeyUsage DigitalSignature -CertStoreLocation "Cert:\CurrentUser\My" -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}")
22+
```
23+
24+
This should output a thumbprint. Example Output:
25+
```ps1
26+
PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My
27+
28+
Thumbprint Subject
29+
---------- -------
30+
148CB69869B802A36B3D8D801BA8D9D0F3C1484F CN=Test NVDA Build, O=NVDA Dev, C=US
31+
```
32+
33+
### Export certificate as PFX
34+
35+
This [method uses a password](https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing#password-usage) to handle access.
36+
37+
Use PowerShell.
38+
Replace the following in this PowerShell script:
39+
- `<nvdaRepositoryRoot>`: the root of your NVDA repository.
40+
- `<Password>`: a password for the exported certificate file.
41+
- `<Certificate Thumbprint>`: The thumbprint from [creating the certificate](#create-a-self-signed-certificate).
42+
```ps1
43+
cd <nvdaRepositoryRoot>
44+
$password = ConvertTo-SecureString -String <Password> -Force -AsPlainText
45+
Export-PfxCertificate -cert "Cert:\CurrentUser\My\<Certificate Thumbprint>" -FilePath local.pfx -Password $password
46+
```
47+
48+
### Import the certificate
49+
50+
Import the certificate to the Local Machine in the "Trusted Root Certification Authorities" store.
51+
52+
Run PowerShell as Administrator, execute [Import-PfxCertificate
53+
](https://docs.microsoft.com/en-us/powershell/module/pki/import-pfxcertificate).
54+
55+
Replace the following in the PowerShell script:
56+
- `<nvdaRepositoryRoot>`: the root of your NVDA repository.
57+
- `<Password>`: your password for the exported certificate file.
58+
```ps1
59+
cd <nvdaRepositoryRoot>
60+
$password = ConvertTo-SecureString -String <Password> -Force -AsPlainText
61+
Import-PfxCertificate -Password $password -CertStoreLocation "Cert:\LocalMachine\Root" -FilePath local.pfx
62+
```
63+
64+
This should output the same thumbprint. Example Output:
65+
```ps1
66+
PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\TrustedPublisher
67+
68+
Thumbprint Subject
69+
---------- -------
70+
148CB69869B802A36B3D8D801BA8D9D0F3C1484F CN=Test NVDA Build, O=NV Access Dev, C=US
71+
```
72+
73+
For Windows 7, you will need to use an alternative method.
74+
On any supported version of Windows, you can manage certifications through the "Certificate Manager".
75+
76+
### Using the certificate
77+
78+
When running a scons command, append `certFile=local.pfx certPassword=<Password>`.
79+
80+
#### Example: building a self-signed installer
81+
82+
From Command Prompt in your NVDA source directory:
83+
```cmd
84+
scons launcher certFile=local.pfx certPassword=<Password>
85+
```
86+
87+
##### Confirming the certificate is installed correctly
88+
89+
View the certificate for the NVDA launcher:
90+
1. Open file properties on the launcher (`output/nvda_*.exe`)
91+
1. Navigate to Digital Signatures tab
92+
1. Open certificate signature
93+
1. Open View Certificate
94+
- If the certificate is not imported correctly:
95+
- **General tab:** "This CA Root certificate is not trusted because it is not in the Trusted Root Certification Authorities store."
96+
- **Certification Path tab, Certificate Status:** "This CA Root certificate is not trusted because it is not in the Trusted Root Certification Authorities store."
97+
- If the certificate is imported correctly:
98+
- **General tab:** "Ensures software came from software publisher. Protects software from alteration after publication"
99+
- **Certification Path tab, Certificate Status:** "This certificate is OK."
100+
101+
### Remove the certificate
102+
103+
After being finished with testing, remove the certificate from the Local Machine "Trusted Root Certification Authorities" store.
104+
Leaving the certificate installed is potentially a security risk.
105+
106+
The certificate will still be in `Cert:\CurrentUser\My\<Certificate Thumbprint>`.
107+
108+
Use PowerShell, running as administrator.
109+
Replace the following in this PowerShell script:
110+
- `<Certificate Thumbprint>`: The thumbprint from [creating the certificate](#create-a-self-signed-certificate).
111+
```ps1
112+
Remove-Item -Path "Cert:\LocalMachine\Root\<Certificate Thumbprint>" -DeleteKey
113+
```
114+
115+
For Windows 7, you will need to use an alternative method.
116+
On any supported version of Windows, you can manage certifications through the "Certificate Manager".

0 commit comments

Comments
 (0)