[apple/libsecurity_codesigning.git] / lib / codedirectory.h

/*
 * 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.
//
// How to add a slot code:
//      1. Add the new name into the primary or virtual slot array at the end (below).
//      2a. For slots representing existing code pieces, follow the ball for cdInfoSlot.
//      2b. For slots representing global signature components, follow the ball for cdResourceDirSlot.
//      2c. For slots representing per-architecture signature components, follow the ball for cdEntitlementSlot.
// ("Follow the ball" -> Global search for that name and do likewise.)
//
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 (as a positive 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 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
        cdIdentificationSlot,                           // identification blob
        // (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. Two 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 checkValidity().
// 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. Remember to check
// for offset in-range in checkIntegrity(). 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)
        Endian<uint32_t> scatterOffset; // offset of optional scatter vector
        
        // works with the version field; see comments above
        static const uint32_t currentVersion = 0x20100;         // "version 2.1"
        static const uint32_t compatibilityLimit = 0x2F000;     // "version 3 with wiggle room"
        
        static const uint32_t earliestVersion = 0x20001;        // earliest supported version
        static const uint32_t supportsScatter = 0x20100;        // first version to support scatter option
        
        void checkIntegrity() const;    // throws if inconsistent or unsupported version

        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;
        }
        
        struct Scatter {
                Endian<uint32_t> count;                 // number of pages; zero for sentinel (only)
                Endian<uint32_t> base;                  // first page number
                Endian<uint64_t> targetOffset;  // offset in target
                Endian<uint64_t> spare;                 // reserved
        };
        Scatter *scatterVector()        // first scatter vector element (NULL if none)
                { return (version >= supportsScatter && scatterOffset) ? at<Scatter>(scatterOffset) : NULL; }
        const Scatter *scatterVector() const
                { return (version >= supportsScatter && scatterOffset) ? at<const Scatter>(scatterOffset) : NULL; }
        
public:
        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[]);
};


}       // CodeSigning
}       // Security


#endif //_H_CODEDIRECTORY