| 1 | /** @file
|
|---|
| 2 | * IPRT - Apple Code Signing Structures and APIs.
|
|---|
| 3 | */
|
|---|
| 4 |
|
|---|
| 5 | /*
|
|---|
| 6 | * Copyright (C) 2018-2023 Oracle and/or its affiliates.
|
|---|
| 7 | *
|
|---|
| 8 | * This file is part of VirtualBox base platform packages, as
|
|---|
| 9 | * available from https://www.virtualbox.org.
|
|---|
| 10 | *
|
|---|
| 11 | * This program is free software; you can redistribute it and/or
|
|---|
| 12 | * modify it under the terms of the GNU General Public License
|
|---|
| 13 | * as published by the Free Software Foundation, in version 3 of the
|
|---|
| 14 | * License.
|
|---|
| 15 | *
|
|---|
| 16 | * This program is distributed in the hope that it will be useful, but
|
|---|
| 17 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
|---|
| 18 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|---|
| 19 | * General Public License for more details.
|
|---|
| 20 | *
|
|---|
| 21 | * You should have received a copy of the GNU General Public License
|
|---|
| 22 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
|---|
| 23 | *
|
|---|
| 24 | * The contents of this file may alternatively be used under the terms
|
|---|
| 25 | * of the Common Development and Distribution License Version 1.0
|
|---|
| 26 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|---|
| 27 | * in the VirtualBox distribution, in which case the provisions of the
|
|---|
| 28 | * CDDL are applicable instead of those of the GPL.
|
|---|
| 29 | *
|
|---|
| 30 | * You may elect to license modified versions of this file under the
|
|---|
| 31 | * terms and conditions of either the GPL or the CDDL or both.
|
|---|
| 32 | *
|
|---|
| 33 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|---|
| 34 | */
|
|---|
| 35 |
|
|---|
| 36 | #ifndef IPRT_INCLUDED_crypto_applecodesign_h
|
|---|
| 37 | #define IPRT_INCLUDED_crypto_applecodesign_h
|
|---|
| 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
|---|
| 39 | # pragma once
|
|---|
| 40 | #endif
|
|---|
| 41 |
|
|---|
| 42 | #include <iprt/types.h>
|
|---|
| 43 | #include <iprt/assertcompile.h>
|
|---|
| 44 | #include <iprt/crypto/pkcs7.h>
|
|---|
| 45 |
|
|---|
| 46 | /** @defgroup grp_rt_craplcs RTCrAppleCs - Apple Code Signing
|
|---|
| 47 | * @ingroup grp_rt_crypto
|
|---|
| 48 | * @{
|
|---|
| 49 | */
|
|---|
| 50 |
|
|---|
| 51 | /** Apple developer ID for iPhone application software development signing. */
|
|---|
| 52 | #define RTCR_APPLE_CS_DEVID_IPHONE_SW_DEV_OID "1.2.840.113635.100.6.1.2"
|
|---|
| 53 | /** Apple developer ID for Mac application software development signing. */
|
|---|
| 54 | #define RTCR_APPLE_CS_DEVID_MAC_SW_DEV_OID "1.2.840.113635.100.6.1.12"
|
|---|
| 55 | /** Apple developer ID for application signing. */
|
|---|
| 56 | #define RTCR_APPLE_CS_DEVID_APPLICATION_OID "1.2.840.113635.100.6.1.13"
|
|---|
| 57 | /** Apple developer ID for installer signing. */
|
|---|
| 58 | #define RTCR_APPLE_CS_DEVID_INSTALLER_OID "1.2.840.113635.100.6.1.14"
|
|---|
| 59 | /** Apple developer ID for kernel extension signing. */
|
|---|
| 60 | #define RTCR_APPLE_CS_DEVID_KEXT_OID "1.2.840.113635.100.6.1.18"
|
|---|
| 61 | /** Apple certificate policy OID. */
|
|---|
| 62 | #define RTCR_APPLE_CS_CERTIFICATE_POLICY_OID "1.2.840.113635.100.5.1"
|
|---|
| 63 |
|
|---|
| 64 |
|
|---|
| 65 | /** @name RTCRAPLCS_MAGIC_XXX - Apple code signing magic values for identifying blobs
|
|---|
| 66 | * @note No byte order conversion required.
|
|---|
| 67 | * @{ */
|
|---|
| 68 | #define RTCRAPLCS_MAGIC_BLOBWRAPPER RT_N2H_U32_C(UINT32_C(0xfade0b01))
|
|---|
| 69 | #define RTCRAPLCS_MAGIC_EMBEDDED_SIGNATURE_OLD RT_N2H_U32_C(UINT32_C(0xfade0b02))
|
|---|
| 70 | #define RTCRAPLCS_MAGIC_REQUIREMENT RT_N2H_U32_C(UINT32_C(0xfade0c00))
|
|---|
| 71 | #define RTCRAPLCS_MAGIC_REQUIREMENTS RT_N2H_U32_C(UINT32_C(0xfade0c01))
|
|---|
| 72 | #define RTCRAPLCS_MAGIC_CODEDIRECTORY RT_N2H_U32_C(UINT32_C(0xfade0c02))
|
|---|
| 73 | #define RTCRAPLCS_MAGIC_EMBEDDED_SIGNATURE RT_N2H_U32_C(UINT32_C(0xfade0cc0))
|
|---|
| 74 | #define RTCRAPLCS_MAGIC_DETACHED_SIGNATURE RT_N2H_U32_C(UINT32_C(0xfade0cc1))
|
|---|
| 75 | /** @} */
|
|---|
| 76 |
|
|---|
| 77 | /** @name Apple code signing versions.
|
|---|
| 78 | * @note Requires byte order conversion of the field value. That way
|
|---|
| 79 | * greater-than and less-than comparisons works correctly.
|
|---|
| 80 | * @{ */
|
|---|
| 81 | #define RTCRAPLCS_VER_2_0 UINT32_C(0x00020000)
|
|---|
| 82 | #define RTCRAPLCS_VER_SUPPORTS_SCATTER UINT32_C(0x00020100)
|
|---|
| 83 | #define RTCRAPLCS_VER_SUPPORTS_TEAMID UINT32_C(0x00020200)
|
|---|
| 84 | #define RTCRAPLCS_VER_SUPPORTS_CODE_LIMIT_64 UINT32_C(0x00020300)
|
|---|
| 85 | #define RTCRAPLCS_VER_SUPPORTS_EXEC_SEG UINT32_C(0x00020400)
|
|---|
| 86 | /** @} */
|
|---|
| 87 |
|
|---|
| 88 | /** @name RTCRAPLCS_SLOT_XXX - Apple code signing slots.
|
|---|
| 89 | * @note No byte order conversion required.
|
|---|
| 90 | * @{ */
|
|---|
| 91 | #define RTCRAPLCS_SLOT_CODEDIRECTORY RT_N2H_U32_C(UINT32_C(0x00000000))
|
|---|
| 92 | #define RTCRAPLCS_SLOT_INFO RT_N2H_U32_C(UINT32_C(0x00000001))
|
|---|
| 93 | #define RTCRAPLCS_SLOT_REQUIREMENTS RT_N2H_U32_C(UINT32_C(0x00000002))
|
|---|
| 94 | #define RTCRAPLCS_SLOT_RESOURCEDIR RT_N2H_U32_C(UINT32_C(0x00000003))
|
|---|
| 95 | #define RTCRAPLCS_SLOT_APPLICATION RT_N2H_U32_C(UINT32_C(0x00000004))
|
|---|
| 96 | #define RTCRAPLCS_SLOT_ENTITLEMENTS RT_N2H_U32_C(UINT32_C(0x00000005))
|
|---|
| 97 | #define RTCRAPLCS_SLOT_ALTERNATE_CODEDIRECTORIES RT_N2H_U32_C(UINT32_C(0x00001000))
|
|---|
| 98 | #define RTCRAPLCS_SLOT_ALTERNATE_CODEDIRECTORIES_END RT_N2H_U32_C(UINT32_C(0x00001005))
|
|---|
| 99 | #define RTCRAPLCS_SLOT_ALTERNATE_CODEDIRECTORIES_COUNT UINT32_C(0x00000005)
|
|---|
| 100 | #define RTCRAPLCS_SLOT_ALTERNATE_CODEDIRECTORY_INC RT_N2H_U32_C(UINT32_C(0x00000001))
|
|---|
| 101 | /** The signature.
|
|---|
| 102 | * This is simply a RTCRAPLCSHDR/RTCRAPLCS_MAGIC_BLOBWRAPPER followed by a DER
|
|---|
| 103 | * encoded \#PKCS7 ContentInfo structure containing signedData. The inner
|
|---|
| 104 | * signedData structure signs external data, so its ContentInfo member is set
|
|---|
| 105 | * to 1.2.840.113549.1.7.1 and has no data. */
|
|---|
| 106 | #define RTCRAPLCS_SLOT_SIGNATURE RT_N2H_U32_C(UINT32_C(0x00010000))
|
|---|
| 107 | /** @} */
|
|---|
| 108 |
|
|---|
| 109 | /** @name RTCRAPLCS_HASHTYPE_XXX - Apple code signing hash types
|
|---|
| 110 | * @note Byte sized field, so no byte order concerns.
|
|---|
| 111 | * @{ */
|
|---|
| 112 | #define RTCRAPLCS_HASHTYPE_SHA1 UINT8_C(1)
|
|---|
| 113 | #define RTCRAPLCS_HASHTYPE_SHA256 UINT8_C(2)
|
|---|
| 114 | #define RTCRAPLCS_HASHTYPE_SHA256_TRUNCATED UINT8_C(3) /**< Truncated to 20 bytes (SHA1 size). */
|
|---|
| 115 | #define RTCRAPLCS_HASHTYPE_SHA384 UINT8_C(4)
|
|---|
| 116 | /** @} */
|
|---|
| 117 |
|
|---|
| 118 |
|
|---|
| 119 | /**
|
|---|
| 120 | * Apple code signing blob header.
|
|---|
| 121 | */
|
|---|
| 122 | typedef struct RTCRAPLCSHDR
|
|---|
| 123 | {
|
|---|
| 124 | /** The magic value (RTCRAPLCS_MAGIC_XXX).
|
|---|
| 125 | * (Big endian, but constant are big endian already.) */
|
|---|
| 126 | uint32_t uMagic;
|
|---|
| 127 | /** The total length of the blob. Big endian. */
|
|---|
| 128 | uint32_t cb;
|
|---|
| 129 | } RTCRAPLCSHDR;
|
|---|
| 130 | AssertCompileSize(RTCRAPLCSHDR, 8);
|
|---|
| 131 | /** Pointer to a CS blob header. */
|
|---|
| 132 | typedef RTCRAPLCSHDR *PRTCRAPLCSHDR;
|
|---|
| 133 | /** Pointer to a const CS blob header. */
|
|---|
| 134 | typedef RTCRAPLCSHDR const *PCRTCRAPLCSHDR;
|
|---|
| 135 |
|
|---|
| 136 | /**
|
|---|
| 137 | * Apple code signing super blob slot.
|
|---|
| 138 | */
|
|---|
| 139 | typedef struct RTCRAPLCSBLOBSLOT
|
|---|
| 140 | {
|
|---|
| 141 | /** Slot type, RTCRAPLCS_SLOT_XXX.
|
|---|
| 142 | * (Big endian, but so are the constants too). */
|
|---|
| 143 | uint32_t uType;
|
|---|
| 144 | /** Data offset. Big endian. */
|
|---|
| 145 | uint32_t offData;
|
|---|
| 146 | } RTCRAPLCSBLOBSLOT;
|
|---|
| 147 | AssertCompileSize(RTCRAPLCSBLOBSLOT, 8);
|
|---|
| 148 | /** Pointer to a super blob slot. */
|
|---|
| 149 | typedef RTCRAPLCSBLOBSLOT *PRTCRAPLCSBLOBSLOT;
|
|---|
| 150 | /** Pointer to a const super blob slot. */
|
|---|
| 151 | typedef RTCRAPLCSBLOBSLOT const *PCRTCRAPLCSBLOBSLOT;
|
|---|
| 152 |
|
|---|
| 153 | /**
|
|---|
| 154 | * Apple code signing super blob.
|
|---|
| 155 | */
|
|---|
| 156 | typedef struct RTCRAPLCSSUPERBLOB
|
|---|
| 157 | {
|
|---|
| 158 | /** Header (uMagic = RTCRAPLCS_MAGIC_EMBEDDED_SIGNATURE?
|
|---|
| 159 | * or RTCRAPLCS_MAGIC_EMBEDDED_SIGNATURE_OLD? ). */
|
|---|
| 160 | RTCRAPLCSHDR Hdr;
|
|---|
| 161 | /** Number of slots. Big endian. */
|
|---|
| 162 | uint32_t cSlots;
|
|---|
| 163 | /** Slots. */
|
|---|
| 164 | RT_FLEXIBLE_ARRAY_EXTENSION
|
|---|
| 165 | RTCRAPLCSBLOBSLOT aSlots[RT_FLEXIBLE_ARRAY];
|
|---|
| 166 | } RTCRAPLCSSUPERBLOB;
|
|---|
| 167 | AssertCompileMemberOffset(RTCRAPLCSSUPERBLOB, aSlots, 12);
|
|---|
| 168 | /** Pointer to a CS super blob. */
|
|---|
| 169 | typedef RTCRAPLCSSUPERBLOB *PRTCRAPLCSSUPERBLOB;
|
|---|
| 170 | /** Pointer to a const CS super blob. */
|
|---|
| 171 | typedef RTCRAPLCSSUPERBLOB const *PCRTCRAPLCSSUPERBLOB;
|
|---|
| 172 |
|
|---|
| 173 | /**
|
|---|
| 174 | * Code directory (RTCRAPLCS_MAGIC_CODEDIRECTORY).
|
|---|
| 175 | */
|
|---|
| 176 | typedef struct RTCRAPLCSCODEDIRECTORY
|
|---|
| 177 | {
|
|---|
| 178 | /** 0x00: Header (uMagic = RTCRAPLCS_MAGIC_CODEDIRECTORY). */
|
|---|
| 179 | RTCRAPLCSHDR Hdr;
|
|---|
| 180 | /** 0x08: The version number (RTCRAPLCS_VER_XXX).
|
|---|
| 181 | * @note Big endian, host order constants. */
|
|---|
| 182 | uint32_t uVersion;
|
|---|
| 183 | /** 0x0c: Flags & mode, RTCRAPLCS_???. (Big endian. ) */
|
|---|
| 184 | uint32_t fFlags;
|
|---|
| 185 | /** 0x10: Offset of the hash slots. Big endian.
|
|---|
| 186 | * Special slots found below this offset, code slots at and after. */
|
|---|
| 187 | uint32_t offHashSlots;
|
|---|
| 188 | /** 0x14: Offset of the identifier string. Big endian. */
|
|---|
| 189 | uint32_t offIdentifier;
|
|---|
| 190 | /** 0x18: Number of special hash slots. Hubertus Bigend style. */
|
|---|
| 191 | uint32_t cSpecialSlots;
|
|---|
| 192 | /** 0x1c: Number of code hash slots. Big endian. */
|
|---|
| 193 | uint32_t cCodeSlots;
|
|---|
| 194 | /** 0x20: Number of bytes of code that's covered, 32-bit wide. Big endian. */
|
|---|
| 195 | uint32_t cbCodeLimit32;
|
|---|
| 196 | /** 0x24: The hash size. */
|
|---|
| 197 | uint8_t cbHash;
|
|---|
| 198 | /** 0x25: The hash type (RTCRAPLCS_HASHTYPE_XXX). */
|
|---|
| 199 | uint8_t bHashType;
|
|---|
| 200 | /** 0x26: Platform identifier or zero. */
|
|---|
| 201 | uint8_t idPlatform;
|
|---|
| 202 | /** 0x27: The page shift value. zero if infinite page size. */
|
|---|
| 203 | uint8_t cPageShift;
|
|---|
| 204 | /** 0x28: Spare field, MBZ. */
|
|---|
| 205 | uint32_t uUnused1;
|
|---|
| 206 | /** 0x2c: Offset of scatter vector (optional). Big endian.
|
|---|
| 207 | * @since RTCRAPLCS_VER_SUPPORTS_SCATTER */
|
|---|
| 208 | uint32_t offScatter;
|
|---|
| 209 | /** 0x30: Offset of team identifier (optional). Big endian.
|
|---|
| 210 | * @since RTCRAPLCS_VER_SUPPORTS_TEAMID */
|
|---|
| 211 | uint32_t offTeamId;
|
|---|
| 212 | /** 0x34: Unused field, MBZ.
|
|---|
| 213 | * @since RTCRAPLCS_VER_SUPPORTS_CODE_LIMIT_64 */
|
|---|
| 214 | uint32_t uUnused2;
|
|---|
| 215 | /** 0x38: Number of bytes of code that's covered, 64-bit wide. Big endian.
|
|---|
| 216 | * @since RTCRAPLCS_VER_SUPPORTS_CODE_LIMIT_64 */
|
|---|
| 217 | uint64_t cbCodeLimit64;
|
|---|
| 218 | /** 0x40: File offset of the first segment. Big endian.
|
|---|
| 219 | * @since RTCRAPLCS_VER_SUPPORTS_EXEC_SEG */
|
|---|
| 220 | uint64_t offExecSeg;
|
|---|
| 221 | /** 0x48: The size of the first segment. Big endian.
|
|---|
| 222 | * @since RTCRAPLCS_VER_SUPPORTS_EXEC_SEG */
|
|---|
| 223 | uint64_t cbExecSeg;
|
|---|
| 224 | /** 0x50: Flags for the first segment. Big endian.
|
|---|
| 225 | * @since RTCRAPLCS_VER_SUPPORTS_EXEC_SEG */
|
|---|
| 226 | uint64_t fExecSeg;
|
|---|
| 227 | } RTCRAPLCSCODEDIRECTORY;
|
|---|
| 228 | AssertCompileSize(RTCRAPLCSCODEDIRECTORY, 0x58);
|
|---|
| 229 | /** Pointer to a CS code directory. */
|
|---|
| 230 | typedef RTCRAPLCSCODEDIRECTORY *PRTCRAPLCSCODEDIRECTORY;
|
|---|
| 231 | /** Pointer to a const CS code directory. */
|
|---|
| 232 | typedef RTCRAPLCSCODEDIRECTORY const *PCRTCRAPLCSCODEDIRECTORY;
|
|---|
| 233 |
|
|---|
| 234 |
|
|---|
| 235 | /**
|
|---|
| 236 | * IPRT structure for working with an Apple code signing blob.
|
|---|
| 237 | */
|
|---|
| 238 | typedef struct RTCRAPLCS
|
|---|
| 239 | {
|
|---|
| 240 | uint8_t const *pbBlob;
|
|---|
| 241 | size_t cbBlob;
|
|---|
| 242 | size_t auReserved[4];
|
|---|
| 243 | } RTCRAPLCS;
|
|---|
| 244 | /** Pointer to an IPRT CS blob descriptor. */
|
|---|
| 245 | typedef RTCRAPLCS *PRTCRAPLCS;
|
|---|
| 246 |
|
|---|
| 247 | /**
|
|---|
| 248 | * Initialize a RTCRAPLCS descriptor and validate the blob data.
|
|---|
| 249 | *
|
|---|
| 250 | * @returns IPRT status code.
|
|---|
| 251 | * @param pDesc The descirptor to initialize.
|
|---|
| 252 | * @param pvBlob The blob bytes.
|
|---|
| 253 | * @param cbBlob The number of bytes in the blob.
|
|---|
| 254 | * @param fFlags Future validation flags, MBZ.
|
|---|
| 255 | * @param pErrInfo Where to return additional error details. Optional.
|
|---|
| 256 | */
|
|---|
| 257 | RTDECL(int) RTCrAppleCsInit(PRTCRAPLCS pDesc, void const *pvBlob, size_t cbBlob, uint32_t fFlags, PRTERRINFO pErrInfo);
|
|---|
| 258 |
|
|---|
| 259 | /**
|
|---|
| 260 | * Callback used by RTCrAppleCsVerifyImage to digest a section of the image.
|
|---|
| 261 | *
|
|---|
| 262 | * @return IPRT status code.
|
|---|
| 263 | * @param hDigest The digest to feed the bytes to.
|
|---|
| 264 | * @param off The RVA of the bytes to digest.
|
|---|
| 265 | * @param cb Number of bytes to digest.
|
|---|
| 266 | * @param pvUser User argument.
|
|---|
| 267 | */
|
|---|
| 268 | typedef DECLCALLBACKTYPE(int, FNRTCRAPPLECSDIGESTAREA,(RTCRDIGEST hDigest, size_t off, size_t cb, void *pvUser));
|
|---|
| 269 | /** Pointer to a image digest callback. */
|
|---|
| 270 | typedef FNRTCRAPPLECSDIGESTAREA *PFNRTCRAPPLECSDIGESTAREA;
|
|---|
| 271 |
|
|---|
| 272 | /**
|
|---|
| 273 | * Verifies an image against the given signature blob.
|
|---|
| 274 | *
|
|---|
| 275 | * @return IPRT status code.
|
|---|
| 276 | * @param pDesc The apple code signing blob to verify against.
|
|---|
| 277 | * @param fFlags Future verification flags, MBZ.
|
|---|
| 278 | * @param pfnCallback Image digest callback.
|
|---|
| 279 | * @param pvUser User argument for the callback.
|
|---|
| 280 | * @param pErrInfo Where to return additional error details. Optional.
|
|---|
| 281 | */
|
|---|
| 282 | RTDECL(int) RTCrAppleCsVerifyImage(PRTCRAPLCS pDesc, uint32_t fFlags, PFNRTCRAPPLECSDIGESTAREA pfnCallback,
|
|---|
| 283 | void *pvUser, PRTERRINFO pErrInfo);
|
|---|
| 284 |
|
|---|
| 285 | RTDECL(int) RTCrAppleCsQuerySigneddData(PRTCRAPLCS pDesc, PRTCRPKCS7SIGNEDDATA pSignedData, PRTERRINFO pErrInfo);
|
|---|
| 286 |
|
|---|
| 287 | /** @} */
|
|---|
| 288 |
|
|---|
| 289 | #endif /* !IPRT_INCLUDED_crypto_applecodesign_h */
|
|---|
| 290 |
|
|---|
