diff --git a/custom-words.txt b/custom-words.txt index efaa81957..3beb75913 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -44,18 +44,23 @@ LDIF libmagic LLDB Mailcatcher +makemsix minio +msix +MSVC MVVM NGRX OIDCS Omnisharp onboarded opid +osslsigncode OTLP owasp passcode passwordless pinentry +PKCS12 PNSs POSIX precompiler @@ -93,6 +98,7 @@ WCAG Xcodes.app xcworkspace xmldoc +xwin Yellowpages Yubico YubiKey diff --git a/docs/getting-started/clients/desktop/index.mdx b/docs/getting-started/clients/desktop/index.mdx index 91dc2f666..6782cfe5b 100644 --- a/docs/getting-started/clients/desktop/index.mdx +++ b/docs/getting-started/clients/desktop/index.mdx @@ -68,7 +68,7 @@ npm run build #### Windows on ARM If you're building in Windows on ARM, you might need to run `build.js` with the `cross-platform` -argument: +argument to build both arm64 and x64 native binaries: ```bash node desktop_native/build.js cross-platform @@ -91,6 +91,74 @@ export PKG_CONFIG_ALLOW_CROSS=1 npm run build -- --target x86_64-unknown-linux-musl # Replace with relevant target ``` +#### Targeting Windows Appx from macOS + +The Windows Appx can be built from macOS[^1]. This can be helpful if you have a macOS development +machine and an underpowered Windows test machine, like a VM or test laptop. + +(Note: If you are using a Windows VM on macOS with Apple Silicon, we recommend using [UTM][utm] with +a [Windows 11 arm64][win11-arm64] build for the best performance.) + +##### Prerequisites + +- PowerShell 7.x: Build scripts +- makemsix from [microsoft/msix-packaging][msix-packaging]: Packages the file in an Appx +- [osslsigncode][]: Produces signatures in the Appx format using OpenSSL. +- [cargo-xwin][]: Used to cross-compile native binaries for the Windows MSVC target. + +You can install these with the following script: + +```shell +brew install powershell iinuwa/msix-packaging-tap/msix-packaging osslsigncode +cargo install --version 0.20.2 --locked cargo-xwin +``` + +Our build scripts will also automatically attempt to install these utilities when cross-compiling to +Windows from macOS. + +Before building the first time, you must generate a signing certificate and set up your test machine +to trust it. See the setup instructions in the [Microsoft Store docs][ms-store-docs] for more +information. + +After that, you can build the Appx from macOS using the steps below. + +##### Cross-compiling Appx + +```sh +cd apps/desktop +export CERTIFICATE_PASSWORD="" +./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath ".pfx" +``` + +Once complete, you can copy the Appx file from `apps/desktop/dist/Bitwarden-.appx` to your +Windows test machine and install it there. + +Use PowerShell's help system to get more information about the script arguments: + +```powershell +Get-Help ./scripts/appx-cross-build.ps1 -Full +``` + +[^1]: +

+ Linux is not currently supported for cross-compilation of the Appx. It could work by using the + same instructions as for macOS listed above, but we are not aware of a packaged version of + `msix-packaging` tools required for building the Appx. +

+

+ Contributions to the documentation on how to build this package for Linux are welcome. + Alternatively, you can consider contributing to the third party Homebrew tap to add Linux + support at [`iinuwa/msix-packaging-tap/msix-packaging`][msix-packaging-tap]. +

+ +[cargo-xwin]: https://github.com/rust-cross/cargo-xwin +[ms-store-docs]: /getting-started/clients/desktop/microsoft-store#macos +[msix-packaging]: https://github.com/microsoft/msix-packaging +[msix-packaging-tap]: https://github.com/iinuwa/homebrew-msix-packaging-tap/ +[osslsigncode]: https://github.com/mtrojnar/osslsigncode +[utm]: https://getutm.app/ +[win11-arm64]: https://www.microsoft.com/en-us/software-download/windows11arm64 + ## Build instructions Build and run: diff --git a/docs/getting-started/clients/desktop/microsoft-store.md b/docs/getting-started/clients/desktop/microsoft-store.md index 2e2a23132..55cafa863 100644 --- a/docs/getting-started/clients/desktop/microsoft-store.md +++ b/docs/getting-started/clients/desktop/microsoft-store.md @@ -5,29 +5,149 @@ sidebar_custom_props: # Microsoft Store -To debug the Microsoft Store application you need to generate a Code Signing certificate which can -be done using the following powershell command: +The Microsoft Store application is packaged as an Appx file. To test the Appx, you must have a +Windows 10+ machine, but you may have a separate development machine with a different OS. + +## Development Machine Setup + +The instructions differ based on the OS of your development machine. Regardless of OS, you must +generate a PKCS12 signing certificate whose subject matches the publisher in the Electron Builder +configuration, found in `./apps/desktop/electron-builder.json`. + +### Windows + +#### Prerequisites + +- [Windows SDK][sdk]: includes the required `signtool` binary for signing the Appx. + +[sdk]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/ + +#### Generating Certificate + +On Windows, you can generate the signing certificate using PowerShell. ```powershell -New-SelfSignedCertificate -Type Custom ` - -Subject "CN=ElectronSign, 0=Your Corporation, C=US" ` - -TextExtension @("2.5.29.19={text}false") ` +$certPath = ".pfx" + +$publisher = "CN=Bitwarden Inc., O=Bitwarden Inc., L=Santa Barbara, S=California, C=US, SERIALNUMBER=7654941, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Delaware, OID.1.3.6.1.4.1.311.60.2.1.3=US" +$certificate = New-SelfSignedCertificate -Type Custom ` + -Subject $publisher ` -KeyUsage DigitalSignature ` -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}") ` - -FriendlyName ElectronSign ` + -FriendlyName "Bitwarden Local Developer Signing Certificate" ` -CertStoreLocation "Cert:\CurrentUser\My" +# Export this certificate to a file so you can configure the machine to trust +# Appx applications signed with it, and optionally sign the Appx on another +# machine. +$password = Read-Host -AsSecureString +Export-PfxCertificate -cert "Cert:\CurrentUser\My\${$cert.Thumbprint}" -FilePath $certPath -Password $password ``` -The generated certificate needs to be copied into to `Cert:\CurrentUser\Trusted People`, which tells -the OS to trust the certificate. This is easiest done using the `certmgr` tool. +See [Microsoft's documentation][ms-appx-cert-docs] for more information. + +After generating the signing certificate, make sure you follow the [steps below to trust the +certificate][trust-docs] on your test machine. + +[ms-appx-cert-docs]: + https://learn.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing +[trust-docs]: #trusting-the-certificate -The [Windows SDK][sdk] is required in order to access the signtool. +#### Signing Appx + +On Windows, our build scripts will automatically sign the Appx file when packaging the appx if you +set the following environment variables: + +```powershell +$env:ELECTRON_BUILDER_SIGN_CERT = ".pfx" +$env:ELECTRON_BUILDER_SIGN_CERT_PW = "" +cd apps/desktop/ +npm run dist:win +``` + +You can also manually sign the Appx using `signtool` directly. ```powershell npm run dist:win cd dist -"C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /v /fd sha256 /n "14D52771-DE3C-4886-B8BF-825BA7690418" .\Bitwarden-2022..appx +"C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /v /fd sha256 /n "CN=Bitwarden Inc., O=Bitwarden Inc., L=Santa Barbara, S=California, C=US, SERIALNUMBER=7654941, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Delaware, OID.1.3.6.1.4.1.311.60.2.1.3=US" .\Bitwarden-.appx ``` -[sdk]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/ +### macOS + +#### Prerequisites + +See the prerequisites for [cross-compiling][cross-compile-docs] the Windows Appx. + +[cross-compile-docs]: /getting-started/clients/desktop/#cross-compile + +#### Generating a Signing Certificate + +If you are building the Appx using a non-Windows machine, you can generate a certificate on Windows +and copy it to your development machine, or you can use OpenSSL to generate the signing certificate: + +```shell +pkcs=".pfx" + +publisher="/jurisdictionCountryName=US/jurisdictionStateOrProvinceName=Delaware/businessCategory=Private Organization/serialNumber=7654941/C=US/ST=California/L=Santa Barbara/O=Bitwarden Inc./CN=Bitwarden Inc." +key=$(mktemp) +cert=$(mktemp) +openssl req -x509 -newkey rsa:2048 -days 3650 -nodes \ + -addext 'keyUsage=critical,digitalSignature' \ + -addext 'extendedKeyUsage=critical,codeSigning' \ + -addext 'basicConstraints=critical,CA:FALSE' \ + -subj "$publisher" -keyout $key -out $cert +openssl pkcs12 -inkey $key -in $cert -export -out $pkcs +# clean up temp files +rm "$key" "$cert" +``` + +After generating the signing certificate, make sure you follow the [steps below to trust the +certificate][trust-docs] on your test machine. + +#### Signing the Appx + +On macOS, the `apps/desktop/scripts/appx-cross-build.ps1` script will sign the Appx when the +`-CertificatePath` and `-CertificatePassword` arguments are passed: + +```powershell +cd apps/desktop +./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath ~/Development/code-signing.pfx -CertificatePassword (Read-Host -AsSecureString) +``` + +You can alternatively specify the certificate password using the `CERTIFICATE_PASSWORD` environment +variable, which allows using a shell besides PowerShell to invoke the request: + +```sh +cd apps/desktop +export CERTIFICATE_PASSWORD="" +./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath ".pfx" +``` + +### Linux + +Linux is not currently supported for cross-platform Appx signing. See the [footnote in the +cross-compiling docs][cross-compile-footnotes] for how we can support this in the future. + +[cross-compile-footnotes]: /getting-started/clients/desktop/#footnote-label +[msix-packaging-tap]: https://github.com/iinuwa/homebrew-msix-packaging-tap/ + +## Test Machine Setup + +### Prerequisites + +The only requirement for running the Microsoft Store application on the test machine is Windows 10+, +although Windows 11 is recommended for testing all features. + +### Trusting the certificate + +The generated certificate needs to be copied onto the test machine and imported into to +`Cert:\CurrentUser\Trusted People`, which tells the OS to trust the certificate. You can do this +with a PowerShell command: + +```powershell +$password = Read-Host -AsSecureString +Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" -Password $password -FilePath .pfx +``` + +You only need to do this the first time you use a certificate.