mar

README

MAR Signing

MAR is Firefox's update file format. For a full description, see go.mozilla.org/mar.

Configuration

The only thing needed to configure a MAR signer is a private key, either RSA or ECDSA P256/P384.

signers:
- id: testmar
  type: mar
  privatekey: |
      -----BEGIN PRIVATE KEY-----
      MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQDHV+bKFLr1p5FR
      ...
      -----END PRIVATE KEY-----

Signature request

This signer supports /sign/hash, /sign/data and /sign/file endpoints. They all use the same request format:

[
    {
        "input": "Y2FyaWJvdW1hdXJpY2UK",
        "keyid": "testmar"
    }
]

The /sign/file endpoint takes a whole MAR encoded in base64. It will parse the mar, sign it and return the signed file.

The /sign/data and /sign/hash endpoint only does the signing step. They takes a MAR block already prepared for signature, calculate its digest (if /sign/data) and return the signature bytes to be inserted in the signature field. Because the signer needs to know which algorithm to use for signature, the signature algorithm can be specified in the signing request options. The acceptable value of the sigalg field can be found in the constants of the MAR package.

[
    {
        "input": "Y2FyaWJvdW1hdXJpY2UK",
        "keyid": "testmar",
        "options": {
            "sigalg": 1
        }
    }
]

Signature response

Data & Hash Signing

The response to a data or hash signing request contains the base64 of the signature in the signature field of the JSON response. You should decode this base64 and insert it into the MAR's signature entry.

[
  {
    "ref": "7khgpu4gcfdv30w8joqxjy1cc",
    "type": "mar",
    "signer_id": "testmar",
    "signature": "MIIGPQYJKoZIhvcN..."
  }
]

File Signing

The response to a file signing request contains the base64 of the signed MAR in the signed_file field of the json response. You should base64 decode that field and write the output as a file.

[
  {
    "ref": "7khgpu4gcfdv30w8joqxjy1cc",
    "type": "mar",
    "signer_id": "testmar",
    "signed_file": "MIIGPQYJKoZIhvcN..."
  }
]

Verifying signatures

Firefox has a signmar tool that can be used to verify MAR signatures. Refer to MAR Signing and Verification for more details.

Documentation

Index

• Constants
• type MARSigner
  • func New(conf signer.Configuration) (s *MARSigner, err error)
  • func (s *MARSigner) Config() signer.Configuration
  • func (s *MARSigner) GetDefaultOptions() interface{}
  • func (s *MARSigner) SignData(data []byte, options interface{}) (signer.Signature, error)
  • func (s *MARSigner) SignFile(input []byte, options interface{}) (signer.SignedFile, error)
  • func (s *MARSigner) SignHash(hashed []byte, options interface{}) (signer.Signature, error)
• type Options
  • func GetOptions(input interface{}) (options Options, err error)
• type Signature
  • func (sig *Signature) Marshal() (string, error)

Constants

const (
	// Type of this signer is "mar"
	Type = "mar"
)

Types

type MARSigner

type MARSigner struct {
	signer.Configuration
	// contains filtered or unexported fields
}

MARSigner holds the configuration of the signer

func New

func New(conf signer.Configuration) (s *MARSigner, err error)

New initializes a mar signer using a configuration

func (*MARSigner) Config

func (s *MARSigner) Config() signer.Configuration

Config returns the configuration of the current signer

func (*MARSigner) GetDefaultOptions

func (s *MARSigner) GetDefaultOptions() interface{}

GetDefaultOptions returns default options of the signer

func (*MARSigner) SignData

func (s *MARSigner) SignData(data []byte, options interface{}) (signer.Signature, error)

SignData takes a MAR file already marshalled for signature and returns a base64 encoded signature.

This function expects the caller to handle parsing of the MAR file, which can be really tricky because the signature headers need to be placed in the file prior to marshalling it for signature. You should consider calling the SignFile interface instead, which will handle all that magic for you.

func (*MARSigner) SignFile

func (s *MARSigner) SignFile(input []byte, options interface{}) (signer.SignedFile, error)

SignFile takes a MAR file and returns a signed MAR file

func (*MARSigner) SignHash

func (s *MARSigner) SignHash(hashed []byte, options interface{}) (signer.Signature, error)

SignHash takes the hash of the signable data of a MAR file, signs it and returns a base64 encoded signature

type Options

type Options struct {
	// SigAlg is an integer that represents the type of signature requested.
	// It must map the SigAlg constants from the MAR package
	SigAlg uint32 `json:"sigalg"`
}

Options accepts the name of the signature algorithm used by the SignData interface to decide which algorithm to sign the data with

func GetOptions

func GetOptions(input interface{}) (options Options, err error)

GetOptions takes a input interface and reflects it into a struct of options

type Signature

type Signature struct {
	Data []byte
}

Signature is a MAR signature

func (*Signature) Marshal

func (sig *Signature) Marshal() (string, error)

Marshal returns the base64 representation of a signature