Skip to content

Commit 52e6f54

Browse files
seanbuddseanbudd
authored
Merge 3077650 into a103ef1 
2 parents a103ef1 + 3077650 commit 52e6f54

1 file changed

Lines changed: 108 additions & 0 deletions

File tree

‎devDocs/selfSignedBuild.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
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+
Run PowerShell as Administrator, execute [Import-PfxCertificate
51+
](https://docs.microsoft.com/en-us/powershell/module/pki/import-pfxcertificate).
52+
53+
Replace the following in the PowerShell script:
54+
- `<nvdaRepositoryRoot>`: the root of your NVDA repository.
55+
- `<Password>`: your password for the exported certificate file.
56+
```ps1
57+
cd <nvdaRepositoryRoot>
58+
$password = ConvertTo-SecureString -String <Password> -Force -AsPlainText
59+
Import-PfxCertificate -Password $password -CertStoreLocation "Cert:\LocalMachine\Root" -FilePath local.pfx
60+
```
61+
62+
This should output the same thumbprint. Example Output:
63+
```ps1
64+
PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\TrustedPublisher
65+
66+
Thumbprint Subject
67+
---------- -------
68+
148CB69869B802A36B3D8D801BA8D9D0F3C1484F CN=Test NVDA Build, O=NV Access Dev, C=US
69+
```
70+
71+
### Using the certificate
72+
73+
When running a scons command, append `certFile=local.pfx certPassword=<Password>`.
74+
75+
#### Example: building a self-signed installer
76+
77+
From Command Prompt in your NVDA source directory:
78+
```cmd
79+
scons launcher certFile=local.pfx certPassword=<Password>
80+
```
81+
82+
##### Confirming the certificate is installed correctly
83+
84+
View the certificate for the NVDA launcher:
85+
1. Open file properties on the launcher (`output/nvda_*.exe`)
86+
1. Navigate to Digital Signatures tab
87+
1. Open certificate signature
88+
1. Open View Certificate
89+
- If the certificate is not imported correctly:
90+
- **General tab:** "This CA Root certificate is not trusted because it is not in the Trusted Root Certification Authorities store."
91+
- **Certification Path tab, Certificate Status:** "This CA Root certificate is not trusted because it is not in the Trusted Root Certification Authorities store."
92+
- If the certificate is imported correctly:
93+
- **General tab:** "Ensures software came from software publisher. Protects software from alteration after publication"
94+
- **Certification Path tab, Certificate Status:** "This certificate is OK."
95+
96+
### Remove the certificate
97+
98+
After being finished with testing, remove the certificate from being in the Trusted Root Authorities.
99+
Leaving the certificate installed is potentially a security risk.
100+
101+
The certificate will still be in `Cert:\CurrentUser\My\<Certificate Thumbprint>`.
102+
103+
Use PowerShell, running as administrator.
104+
Replace the following in this PowerShell script:
105+
- `<Certificate Thumbprint>`: The thumbprint from [creating the certificate](#create-a-self-signed-certificate).
106+
```ps1
107+
Remove-Item -Path "Cert:\LocalMachine\Root\<Certificate Thumbprint>" -DeleteKey
108+
```

0 commit comments

Comments
 (0)