codedirectory.h   [plain text]


/*
 * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

//
// codedirectory - format and operations for code signing "code directory" structures
//
// A CodeDirectory is a contiguous binary blob containing a two-tiered
// hash of (much of) the contents of a real StaticCode object.
// It consists of a header followed by an array of hash vector elements.
//
// This structure is meant to be self-describing, binary stable, and endian independent.
//
#ifndef _H_CODEDIRECTORY
#define _H_CODEDIRECTORY

#include <security_utilities/unix++.h>
#include <security_utilities/blob.h>
#include <security_utilities/cfutilities.h>
#include <security_utilities/hashing.h>


namespace Security {
namespace CodeSigning {


//
// Types of hashes supported.
// Actually, right now, only SHA1 is really supported.
//
enum {
	cdHashTypeSHA1 = 1,
	cdHashTypeSHA256 = 2,
	
	cdHashTypeDefault = cdHashTypeSHA1
};


//
// Conventional string names for various code signature components.
// Depending on storage, these may end up as filenames, extended attribute names, etc.
//
#define kSecCS_CODEDIRECTORYFILE	"CodeDirectory"		// CodeDirectory
#define kSecCS_SIGNATUREFILE		"CodeSignature"		// CMS Signature
#define kSecCS_REQUIREMENTSFILE		"CodeRequirements"	// internal requirements
#define kSecCS_RESOURCEDIRFILE		"CodeResources"		// resource directory
#define kSecCS_APPLICATIONFILE		"CodeApplication"	// application-specific resource
#define kSecCS_ENTITLEMENTFILE		"CodeEntitlements"	// entitlement configuration (just in case)


//
// Special hash slot values. In a CodeDirectory, these show up at negative slot
// indices. This enumeration is also used widely in various internal APIs, and as
// type values in embedded SuperBlobs.
//
enum {
	//
	// Primary slot numbers.
	// These values are potentially present in the CodeDirectory hash array
	// under their negative values. They are also used in APIs and SuperBlobs.
	// Note that zero must not be used for these (it's page 0 of the main code array),
	// and it's good to assign contiguous (very) small values for them.
	//
	cdInfoSlot = 1,						// Info.plist
	cdRequirementsSlot = 2,				// internal requirements
	cdResourceDirSlot = 3,				// resource directory
	cdApplicationSlot = 4,				// Application specific slot
	cdEntitlementSlot = 5,				// embedded entitlement configuration
	// (add further primary slot numbers here)

	cdSlotCount,						// total number of special slots (+1 for slot 0)
	cdSlotMax = cdSlotCount - 1,		// highest special slot number
	
	//
	// Virtual slot numbers.
	// These values are NOT used in the CodeDirectory hash array. The are used as
	// internal API identifiers and as types in in-image SuperBlobs.
	// Zero is okay to use here; and we assign that to the CodeDirectory itself so
	// it shows up first in (properly sorted) SuperBlob indices. The rest of the
	// numbers is set Far Away so the primary slot set can expand safely.
	// It's okay to have gaps in these assignments.
	//
	cdCodeDirectorySlot = 0,			// CodeDirectory
	cdSignatureSlot = 0x10000,			// CMS signature
	// (add further virtual slot numbers here)
};


//
// Special hash slot attributes.
// This is a central description of attributes of each slot.
// Various places in Code Signing pick up those attributes and act accordingly.
//
enum {
	cdComponentPerArchitecture = 1,			// slot value differs for each Mach-O architecture
	cdComponentIsBlob = 2,					// slot value is a Blob (need not be BlobWrapped)
};


//
// A CodeDirectory is a typed Blob describing the secured pieces of a program.
// This structure describes the common header and provides access to the variable-size
// elements packed after it. For help in constructing a CodeDirectory, use the nested
// Builder class.
//
// The hashes are stored as an array of digests. The array covers the range
// [-nSpecialSlots .. nCodeSlots-1]. Non-negative indices  denote pages of the main
// executable. Negative indices indicate "special" hashes, each of a different thing
// (see cd*Slot constants above). Special slots that are in range but not present
// are zeroed out. Unallocated special slots are also presumed absent; this is not
// an error. (Thus the range of special slots can be extended at will.)
//
// HOW TO MANAGE COMPATIBILITY:
// Each CodeDirectory has a format (compatibility) version. Three constants control
// versioning:
//	* currentVersion is the version used for newly created CodeDirectories.
//  * compatibilityLimit is the highest version the code will accept as compatible.
// Test for version < currentVersion to detect old formats that may need special
// handling. The current code rejects those; add backward cases to checkVersion().
// Break backward compatibility by rejecting versions that are unsuitable.
// Accept currentVersion < version <= compatibilityLimit as versions newer than
// those understood by this code but engineered (by newer code) to be backward
// compatible. Reject version > compatibilityLimit as incomprehensible gibberish.
//
// When creating a new version, increment currentVersion. When adding new fixed fields,
// just append them; the flex fields will shift to make room. To add new flex fields,
// add a fixed field containing the new field's offset and add suitable computations
// to the Builder to place the new data (right) before the hash array. Older code will
// then simply ignore your new fields on load/read.
// Add flag bits to the existing flags field to add features that step outside
// of the linear versioning stream. Leave the 'spare' fields alone unless you need
// something extraordinarily weird - they're meant to be the final escape when everything
// else fails.
// As you create new versions, consider moving the compatibilityLimit out to open up
// new room for backward compatibility.
// To break backward compatibility intentionally, move currentVersion beyond the
// old compatibilityLimit (and move compatibilityLimit further out).
//
class CodeDirectory: public Blob<CodeDirectory, 0xfade0c02> {
	typedef SHA1 Hash;
public:
	Endian<uint32_t> version;		// compatibility version
	Endian<uint32_t> flags;			// setup and mode flags
	Endian<uint32_t> hashOffset;	// offset of hash slot element at index zero
	Endian<uint32_t> identOffset;	// offset of identifier string
	Endian<uint32_t> nSpecialSlots;	// number of special hash slots
	Endian<uint32_t> nCodeSlots;	// number of ordinary (code) hash slots
	Endian<uint32_t> codeLimit;		// limit to main image signature range
	uint8_t hashSize;				// size of each hash in bytes
	uint8_t hashType;				// type of hash (cdHashType* constants)
	uint8_t spare1;					// unused (must be zero)
	uint8_t	pageSize;				// log2(page size in bytes); 0 => infinite
	Endian<uint32_t> spare2;		// unused (must be zero)
	
	// works with the version field; see comments above
	static const uint32_t currentVersion = 0x20001;		// "version 2"
	static const uint32_t compatibilityLimit = 0x2F000;	// "version 3 with wiggle room"
	
	void checkVersion() const;		// throws if not compatible with this code

	typedef int Slot;				// slot index (negative for special slots)
	typedef unsigned int SpecialSlot; // positive special slot index (not for code slots)
	
	const char *identifier() const { return at<const char>(identOffset); }
	char *identifier() { return at<char>(identOffset); }

	unsigned char *operator [] (Slot slot)
	{
		assert(slot >= int(-nSpecialSlots) && slot < int(nCodeSlots));
		return at<unsigned char>(hashOffset) + hashSize * slot;
	}
	
	const unsigned char *operator [] (Slot slot) const
	{
		assert(slot >= int(-nSpecialSlots) && slot < int(nCodeSlots));
		return at<unsigned char>(hashOffset) + hashSize * slot;
	}
	
	bool validateSlot(const void *data, size_t size, Slot slot) const;
	bool validateSlot(UnixPlusPlus::FileDesc fd, size_t size, Slot slot) const;
	bool slotIsPresent(Slot slot) const;
	
	class Builder;
	
protected:
	static size_t hash(UnixPlusPlus::FileDesc fd, Hash::Byte *digest, size_t limit = 0);
	static size_t hash(const void *data, size_t length, Hash::Byte *digest);
	
public:
	//
	// Information about SpecialSlots
	//
	static const char *canonicalSlotName(SpecialSlot slot);
	static unsigned slotAttributes(SpecialSlot slot);
	IFDEBUG(static const char * const debugSlotName[]);
	
public:
	//
	// Canonical text forms for (only) the user-settable flags
	//
	struct FlagItem {
		const char *name;
		uint32_t value;
		bool external;
	};
	static const FlagItem flagItems[];	// terminated with NULL item

	static uint32_t textFlags(std::string text);
};


}	// CodeSigning
}	// Security


#endif //_H_CODEDIRECTORY