first build

docs/profile-signing.md

@@ -0,0 +1,42 @@
+# Signing the `.mobileconfig`
+
+The portal **always signs** the profile after the PKCS#12 payload is embedded. Unsigned profiles install with a warning; a signature that the device trusts shows as verified.
+
+## Signing identity
+
+`PROFILE_SIGNING_P12_PATH` is a PKCS#12 (`.p12` / `.pfx`) containing:
+
+- The signer private key
+- The signer certificate
+- Optional intermediates (included in the CMS)
+
+The **device must already trust** this certificate (or its issuer). Typical sources:
+
+- An internal TLS/code-signing/profile-signing CA already deployed by MDM or a root payload
+- A dedicated “configuration profile signing” cert from that CA
+
+This file is **not** the per-user identity P12. It is long-lived and stored on disk. Protect it like any other service credential (`chmod` / secret mount).
+
+## What the portal does
+
+After building the XML plist it creates an **attached** CMS `SignedData` (DER):
+
+```
+openssl smime -sign \
+  -signer cert.pem -inkey key.pem -certfile chain.pem \
+  -nodetach -outform der \
+  -in unsigned.mobileconfig -out signed.mobileconfig
+```
+
+Implementation: `cryptography` `PKCS7SignatureBuilder`, SHA-256, `Encoding.DER`, `PKCS7Options.Binary` (so the XML is not canonicalized). Detached signatures are not used; Apple needs the profile bytes inside the CMS.
+
+## Trust on the device
+
+- If the signer chains to a root already on the iPhone/Mac, Settings shows the profile as signed/verified.
+- If not, the user can still install it (with a warning) unless an MDM policy forbids unsigned/untrusted profiles.
+
+Deploy the signing CA with MDM or an earlier profile before you depend on a “verified” badge.
+
+## Rotation
+
+Replace the P12 on disk and restart the process. Old profiles remain valid; new downloads use the new signer. Keep the old CA trusted until you do not care about old profiles.