android

README

Package playground/android

This package contains code for signing Android APKs and OTA images (notably, boot images.) It has been successfully used to sign system images for the (original) Google Pixel, in yellow mode (i.e. verified boot with locked bootloader, but using non-factory keys.)

Special thanks to Playground Global, LLC for open-sourcing this software. See LICENSE for details.

Package playground/android/apksign

This API can sign Android APK files using both the legacy v1 signing scheme (i.e. Java jarsigner scheme) and the modern v2 signing scheme (which is actually a general ZIP file signing scheme.)

Package playground/android/otasign

This API can sign Android system images. It can sign both bootable images and Android verified boot images. The latest versions of Android may or may not work with this code; it hasn't been recently tested.

Documentation

Overview

Package android is a parent package of Android-related code-signing implementations for APKs, system images, and OTA images.

Index

• Constants
• func IDFor(key KeyAlgorithm, hash HashAlgorithm) uint32
• func IDtoString(id uint32) string
• type AlgorithmID
• type HashAlgorithm
  • func (h HashAlgorithm) AsHash() crypto.Hash
• type KeyAlgorithm
• type SigningCert
  • func (sc *SigningCert) Resolve() error
• type SigningKey
  • func (sk *SigningKey) Resolve() error
  • func (sk *SigningKey) Sign(data []byte, hash crypto.Hash) ([]byte, error)
  • func (sk *SigningKey) SignPrehashed(data []byte, hash crypto.Hash) ([]byte, error)

Constants

const (
	RSA    KeyAlgorithm = "RSA"
	RSAPSS              = "RSAPSS"
	EC                  = "EC"
	DSA                 = "DSA"
)

const (
	RSAPSS_SHA256   AlgorithmID = 0x0101
	RSAPSS_SHA512               = 0x0102
	RSA_PKCS_SHA256             = 0x0103
	RSA_PKCS_SHA512             = 0x0104
	ECDSA_SHA256                = 0x0201
	ECDSA_SHA512                = 0x0202
	DSA_SHA256                  = 0x0301
)

Functions

func IDFor

func IDFor(key KeyAlgorithm, hash HashAlgorithm) uint32

Returns the appropriate Android APK v2 signing scheme magic constant for the given cryptosystem.

func IDtoString

func IDtoString(id uint32) string

IDtoString returns a string representation of an Android APK signing scheme v2 magic constant.

Types

type AlgorithmID

type AlgorithmID uint32

AlgorithmID labels the Android APK signing scheme v2 magic constants. Note that these constants serve the same function as the usual ASN.1 object ID registered constants, but in an integer format.

type HashAlgorithm

type HashAlgorithm string

HashAlgorithm is used to map strings used in e.g. config files to implementations. This is partially redundant with crypto.Hash, but its purpose is to be able to basically map a string from a config file into a crypto.Hash elsewhere in code

const (
	SHA256 HashAlgorithm = "SHA256"
	SHA512               = "SHA512"
)

func (HashAlgorithm) AsHash

func (h HashAlgorithm) AsHash() crypto.Hash

AsHash turns our string-based enum type into a Go crypto.Hash value.

type KeyAlgorithm

type KeyAlgorithm string

KeyAlgorithm is used to map strings used in e.g. config files to implementations.

type SigningCert

type SigningCert struct {
	SigningKey
	CertPath    string
	Certificate *x509.Certificate
	CertHash    string
}

SigningCert is a SigningKey that adds a public key Certificate.

func (*SigningCert) Resolve

func (sc *SigningCert) Resolve() error

Resolve parses the PEM-encoded DER/ASN.1 X.509 certificate, as well as the private key (by calling SigningKey.Resolve() on itself.) A non-nil error is returned if the parsing fails for any reason, or on I/O errors.

type SigningKey

type SigningKey struct {
	KeyPath string
	Type    KeyAlgorithm
	Hash    HashAlgorithm
	Key     *rsa.PrivateKey
}

SigningKey wraps a private key disk file with functions that know how to parse the key, and sign things with it. Currently only RSA keys and SHA-2/256 and SHA-2/512 digests are supported.

func (*SigningKey) Resolve

func (sk *SigningKey) Resolve() error

Resolve loads the private key from disk and parses it. A non-nil error is returned if the parsing fails for any reason, or if the key type is unsupported.

func (*SigningKey) Sign

func (sk *SigningKey) Sign(data []byte, hash crypto.Hash) ([]byte, error)

Sign returns the input bytes signed using the private key and the provided hash function. A non-nil error indicates that the signing operation failed for some reason, usually do to incorrect use of the configured cryptosystem.

It is an error to call this function before Resolve(). Note again that currently only RSA is supported; the returned bytes will specifically be in binary DER-encoded PKCS#1v1.5 format.

func (*SigningKey) SignPrehashed

func (sk *SigningKey) SignPrehashed(data []byte, hash crypto.Hash) ([]byte, error)

SignPrehashed is the same as Sign, except that its input bytes must be pre-hashed (or at least the same length as a digest under the provided crypto.Hash scheme.)