View source for AMO/SigningService/API

== General Info ==

=== Abstract ===
This document describes how addons are signed to be automatically in Mozilla's Marketplace infrastructure.

=== Definitions ===
; endpoint-url : The full URI for the service including the <tt>version string</tt> for the API as defined below.
; version string : This revision of the protocol is 1.0 so the version string is "/1.0/".
; root certificate : The signing CA's root certificate in standard X.509 format.  This certificate will be included in each build of the user agent.
; generated key and certificate : An very short lived private and public key pair that are generated in an automated fashion, on demand.  The public key is then certified by the CA root certificate.
; unsigned archive : A JAR file that has been uploaded by a developer but not signed by the service yet.
; signed archive : A JAR file that has been created by Zamboni to include the contents of the unsigned archive and the generated manifest and signature files.
; manifest file : A file describing the contents of a JAR file.  Format detailed [http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#Manifest_Specification here].
; signature file : A file of the same format as the manifest file that contains a single entry for the manifest file. Official format detailed [http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#Signature_File here].  Note that XPI signing is an '''incompatible subset''' of JAR signing due to changes made in how XPIs are verified for improved security.
; app id : A unique identifier for the combination of addon name and version that will be used in the generated key and certificate.  A strong preference for human readable.

=== Related documentation ===
; JAR signing : [http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#Signed_JAR_File JDK documentation]
; JAR validation : [http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#Signature_Validation JDK documentation]
; PKCS#7 : [http://en.wikipedia.org/wiki/Cryptographic_Message_Syntax Cryptographic Message Syntax] is a brief intro with links

=== Data formats ===
The data formats are described in depth in the [http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#Signed_JAR_File JDK documentation].  There are three basic formats being dealt with:
* Zip archives
* An HTTP header like format for archive manifests and signatures
* PKCS#7 detached signature in DER format

=== Components ===
; Signing clients : https://github.com/mozilla/signing-clients/

signing-clients is just a simple library for generating, parsing, and formatting the manifest and signature file formats.

; Trunion : https://github.com/mozilla/trunion/

The actual signing service.  This is the same code base as the [[Apps/WebApplicationReceipt/SigningService|receipt signing service]] but runs in a separate process space to provide a degree of separation between app signing, receipt signing, and addon signing credentials.

; Zamboni, packaged app handling specifically : https://github.com/mozilla/zamboni/blob/master/lib/crypto/packaged.py

Zamboni is responsible for receiving and storing an uploaded application archive, generating manifest and signature files for it via the signing-clients library, requesting a signature from the trunion signing service, and creating a new signed application archive containing the additional three files.

== API ==
; POST http://<endpoint-url>/sign_addon OR http://<endpoint-url>/sign/addon : 

* This takes two arguments:
** the archive's signature file as multipart/form-data as an input with the name "file" with a filename included. 
** the app id for this XPI at this version.
* It then returns a PKCS#7 detached signature of the uploaded content in a JSON object with a single key and value pair.  The key is the uploaded content's specified filename with its extension(".sf") replaced with ".rsa".  The value is a base64 encoded representation of the PKCS#7 data.

=== Example request ===
 POST /1.0/sign_addon HTTP/1.1
 Host: localhost:5000
 Content-Length: 306
 Content-Type: multipart/form-data; boundary=df8e3fdaf425408e956aff8ca19d0263
 Accept-Encoding: gzip, deflate, compress
 Accept: */*
 User-Agent: python-requests/0.14.2 CPython/2.7.1 Darwin/11.4.2
 
 --df8e3fdaf425408e956aff8ca19d0263
 Content-Disposition: form-data; name="id"
 Content-Type: text/plain

 digital-doughnuts-addon-v1.0
 --df8e3fdaf425408e956aff8ca19d0263
 Content-Disposition: form-data; name="file"; filename="zigbert.sf"
 Content-Type: application/octet-stream
 
 Signature-Version: 1.0
 MD5-Digest-Manifest: PTUbaADVign9DDK3ntq9ww==
 SHA1-Digest-Manifest: FkVPRYqW9UT8kcbm8VS08TIWsH4=
 
 --df8e3fdaf425408e956aff8ca19d0263--

=== Example response ===
Response body truncated for brevity.

 HTTP/1.0 200 OK
 Server: PasteWSGIServer/0.5 Python/2.6.8
 Date: Wed, 01 Oct 2014 20:43:05 GMT
 Content-Type: application/json; charset=UTF-8
 Content-Length: 3607
 
 {"zigbert.rsa": "MIIKfQYJKoZIhvcNAQcCoIIKbjCCCmoCAQExCzAJBgUrDgMCGgUAMAsGCSq...=="}

== HTTP response codes ==
; 200 OK : The request was processed successfully and the server is returning a PKCS#7 signature
; 400 Bad request : The request body was incorrectly formatted
; 401 Unauthorized : The authentication credentials are invalid.  At the moment authorization consists of a simple whitelist of IPs.  In the future this may be used to indicate a BrowserID or other authentication mechanism has failed or the credentials are not authorized to use the service.
; 409 Conflict : A certificate has already been generated for the app id provided
; 503 Service Unavailable : Indicates that the server(s) are undergoing maintenance.