Documentation
¶
Overview ¶
Package trustkit builds what the public trust portal hands to a person who wants to trust a root of this PKI: the configuration profile for iPhone, iPad and Mac and the per-platform steps and commands (v0.3.9).
Everything here is a pure function of data from the database: the root's DER, its name, its common name and the CA's public base URL. Nothing comes from a request (not the User-Agent, not a query value), and nothing here does I/O. The package uses the standard library only and is imported by internal/publish; the agent does not import it.
Safety rule for generated text: every variable part of a command is a hash, a CA name that matched ValidName, a generation number, or a base URL that passed ValidBaseURL. Anything else removes the command instead of being escaped, so there is never a half-quoted command.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ColonHex ¶
ColonHex formats a hex string the way certificate dialogs show a fingerprint: upper case, pairs separated by colons ("AB:CD:…"). A trailing odd digit stays a pair of its own.
func MobileConfig ¶
MobileConfig returns the unsigned Apple configuration profile for a root: one Configuration dict with a single com.apple.security.root payload that carries the certificate. iOS, iPadOS and macOS install it from a download.
The output is a pure function of the root's DER, name, generation and common name: no date, no host name, no serial, no private data. The identifiers and UUIDs derive from the certificate's SHA-256, so the same root always gives the same bytes and installing it again replaces the profile instead of adding one, while a renewed root (another certificate) gets other identifiers and can be installed next to the old one. PayloadRemovalDisallowed is false: the user can always remove it.
func ValidBaseURL ¶
ValidBaseURL applies the conservative pattern of the portal to a public base URL and returns it without a trailing slash: the scheme is http or https, the host consists of letters, digits, dots and hyphens, an optional port follows, and an optional path of letters, digits and "._~/-". There is no user name, query, fragment, space, quote, percent sign or non-ASCII character. Anything else gives false and the page shows no command.
Types ¶
type Block ¶
type Block struct {
Title string
Steps []string // sentences to follow, in order
Lines []string // the commands, one text line each; empty when no command is offered
Note string // the limit of the block or a caveat, one or two sentences
}
Block is one titled part of a guide: steps for a person, commands to paste, or both, and a note. It is plain data; the page escapes every field.
func Guide ¶
Guide returns the blocks of steps and commands that install root r on platform p, or nil for an unknown platform. Commands appear only when the root's name and base URL pass the pattern checks; otherwise the block says to compare by hand. The text depends on nothing but r: the commands carry the root's SHA-256, its download URL and its CA name, and nothing else variable.
type Detection ¶
type Detection struct {
// Platform is the detected platform, [Linux] when the string only says
// Linux or X11 (both families are shown), or "" when nothing matched.
Platform Platform
// Firefox is set when the browser is Firefox, which keeps its own store of
// certificate authorities on most systems.
Firefox bool
}
Detection is what the User-Agent says about the visitor's system. It is a guess, shown as a guess: the page lets the visitor choose another platform.
func Detect ¶
Detect reads a User-Agent header value. Only the first 512 bytes count, case is folded for ASCII only, and the result comes from a fixed table: the string selects a row and nothing else, and no part of it is kept. The work is linear in the (capped) length: strings.Contains on fixed needles, no regular expression, so there is no backtracking.
type Platform ¶
type Platform string
Platform names a family of devices; the page shows one block of steps per platform. The values are also the allow-list of the ?os= query value.
const ( Windows Platform = "windows" MacOS Platform = "macos" IOS Platform = "ios" Android Platform = "android" Debian Platform = "debian" Fedora Platform = "fedora" Firefox Platform = "firefox" Java Platform = "java" Linux Platform = "linux" )
The platforms with steps. Linux is a detection result only: both Linux families are shown, and it is not accepted from the query.
func ParsePlatform ¶
ParsePlatform maps a query value to a platform of Platforms. It is a lookup in the allow-list: the result is never the input, and anything else (unknown, empty, longer than 16 bytes) gives false.
type Root ¶
type Root struct {
Name string // the CA's name: part of every URL, [ValidName]
Generation int64 // from 1
Current bool // the current generation; older ones get a suffix in file names
DER []byte // the certificate
BaseURL string // the CA's public base URL, the one inside its certificates
CommonName string // the certificate's common name; only ever shown as escaped text
}
Root is one generation of a root CA as the portal knows it. All fields come from the database.
func (Root) CertURL ¶
CertURL is the DER download URL of the root (the AIA caIssuers URL of its certificates), or false when the CA's name or base URL does not pass the pattern checks. Commands are only generated when it is true.
func (Root) File ¶
File is the base name the page uses for downloads and the commands for the files they create: the CA's name, with the generation appended for an older generation, and always the first 8 hex digits of the certificate's SHA-256. The suffix keeps two certificates apart that would share a base name otherwise: the CA "root-2" at generation 1 and the CA "root" at an older generation 2 are both "root-2" without it. A name that passes ValidName stays valid, so the result holds letters, digits, '.', '_' and '-' only.
Source Files