User:Homunq/Activity bundles v2
Signatures
An activity bundle consists of a file whose nominal extension is .xo, but whose real structure corresponds to .zip, OR .tgz (interchangeable). The difference between these two structures is auto-detected.
Zip is for backward compatibility, .tgz is a better format for differential version control because, while it is compressed for sending over a network connection, it is also easily expanded to a form that is friendly to binary diffs.
The internal structure looks something like the following:
Helloworld.activity/ helloworld.py locale/ de_DE/ activity.linfo zh_CN/ activity.linfo activity/ activity.info icons/ helloworld.svg STRUCTURE/ MANIFEST TRANSLATABLES HASHES TRANSLATABLE_HASHES/ zh_de de es SIGNATURES/ masterkey (OPTIONAL symlink to deadbeef/) deadbeef/ deadbeef.pub cafeb0ef.pub.sig 12345678.pub.sig 12345678/ 12345678.pub A1A1A1A1/ a1a1a1a1.pub de.sig cafeb0ef/ cafeb0ef.sig HASHES.sig
All special files are assumed to be in UTF-8. All linefeeds are unix-style.
- MANIFEST
- Mandatory
- list of realative paths of all files and directories (with trailing dash) in bundle, except:
- non-empty directories (only empty directories should be in MANIFEST)
- MANIFEST
- TRANSLATABLES
- HASHES
- any files in SIGNATURES
- any files matched by a pattern in TRANSLATABLES (see below)
- Ends with a newline
- Order is significant, and should be maintained
- When renaming a file, the renamed file should appear on the same line
- When deleting a file, leaving a blank line is OPTIONAL and ENCOURAGED. Blank lines are DISCOURAGED but ALLOWED in other cases.
- Other whitespace not part of file names is NOT ALLOWED
maintaining order makes merges, diffs, and import to source control tools easier
For the example above, MANIFEST would be exactly:
helloworld.py icons/helloworld.svg
- TRANSLATABLES
- optional file
- uses the same format as .gitignore
- indicates what files from MANIFEST should *not* be included in HASHES
Obviously, this does introduce a security risk, as an unsigned TRANSLATABLES file could theoretically cause a buffer overflow (or, indeed, be deliberately run by malicious signed code). The first case is considered avoidable with good tools, and the second is considered to be no additional risk (malicious code is malicious code)
L10n should not require bugging the original activity author - imagine having to sign multiple versions of dozens of languages for every activity version, besides the inconvenience it is a security risk because the underlying code could change between "pure-l10n" versions without the author realizing.
- HASHES
- auto-generated file
- first line '#HASH-VERSION: 1.0; HASH-FUNCTION:sha256'.
- No additional whitespace
- The further lines of HASHES alternate
- one line with a path as in MANIFEST
- the sha1sum hash of the binary contents of the file on the line which follows.
- There is no limit to line length.
- order:
- [The first two lines are TRANSLATABLES and its hash, if it exists]
- The rest of HASHES follows MANIFEST, in the same order, excluding blank lines or any lines that match patterns in TRANSLATABLES.
- SIGNATURES/
- optional directory
- Contents
- activity.key
- public DSA key, as generated by ssh
- VALIDKEYS/
- contains pairs of files
- a public key, filename does not end in ".sig"
- a separate signature, format specified below, of that file. filename is the same with ".sig" appended.
- meaningful metadata:
- "requiredmetadata":{JSON object}. At least one key:value pair from the requiredmetadata must be in the metadata object of signatures using this key.
- all signatures here should be verifiable with activity.key
- invalid signatures are deleted on installation
- meaningful metadata:
- contains pairs of files
- GENSIGS/
- Signatures of HASHES
- iff any of these are verifiable with a key from VALIDKEYS, the bundle is considered to be "signed"
- additional signatures are allowed, and may be respected if recognized by Sugar. (ie, a control panel for "valid global activity signers"
- meaningful metadata:
- "status":
- "favorite" means signor claims that this activity should be favoritted. Equivalent to "latest" unless this signature recognized by sugar.
- "latest" means signor claims that this version supercedes previous versions.
- "development" means signor claims that this version does NOT supercede previous versions
- any other status attribute, or none, is interpreted as "development"
- anything from requiredmetadata of signing key.
- "status":
- Signatures of HASHES
- TRANSSIGS/
- signatures of translation files
- hashes
- same format as HASHES, contain any subset of files which match TRANSLATABLES
- may contain files not in (purged for space from) bundle, as long as at least 1 of the files is still present
- sigs
- signatures on hashes
- any signer - this information to be used by sugar.
- activity.key