Skip to content

RaulVan/ios-signer

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
.gitignore
.gitignore
 
 
README.md
README.md
 
 
install.sh
install.sh
 
 
sign_ios_app.sh
sign_ios_app.sh
 
 

Repository files navigation

iOS App Resign Tool / iOS 应用重签名工具

English | 简体中文

This project's scripts and documentation are generated by Cursor AI. 该项目脚本代码以及文档使用 Cursor AI 生成。

English Documentation

Introduction

This is a command-line tool for iOS application re-signing, primarily used for enterprise application re-signing and distribution. It helps developers and enterprises quickly complete the iOS application re-signing process, supporting complex applications with extensions.

Key Features

  • Support for IPA file re-signing
  • Automatic handling of App Extensions
  • Automatic handling of Embedded Frameworks
  • Remove non-Payload content by default before repacking
  • Remove PlugIns by default when present
  • Remove libswift*.dylib from Frameworks by default when present
  • Automatic certificate information extraction and validation
  • AppIcon alpha-channel validation before signing
  • Preserve original orientation settings by default, and only auto-patch iPad multitasking orientations when required by Info.plist
  • Detailed logging output

Technical Features

  • Written in Shell script, no additional dependencies required
  • Provides automatic installation script for easy deployment
  • Supports command-line parameters for automation integration
  • Includes comprehensive error handling and logging

Documentation

1. Installation

1.1 Using Installation Script (Recommended)

An automatic installation script install.sh is provided to complete all installation steps:

# Add execution permission
chmod +x install.sh

# Execute installation
./install.sh

Installation Script Features:

  • Automatic system environment check (macOS and Xcode tools)
  • Automatic permission and dependency handling
  • Automatic installation verification
  • Uninstallation support

Uninstall command:

./install.sh --uninstall

1.2 Manual Installation (Optional)

If you prefer not to use the installation script, you can install manually:

1.2.1 Create System Directory
sudo mkdir -p /usr/local/bin
1.2.2 Copy Script to System Directory
sudo cp sign_ios_app.sh /usr/local/bin/ios_sign
1.2.3 Set Correct Permissions
# Add execution permission
sudo chmod 755 /usr/local/bin/ios_sign

# Set owner to root
sudo chown root:wheel /usr/local/bin/ios_sign
1.2.4 Verify Installation
# Check if command is available
which ios_sign

# Should output: /usr/local/bin/ios_sign

2. Usage

2.1 Command Format

ios_sign -f <ipa_file> -p <profile_file> -v <version> -b <build>

2.2 Parameters

  • -f, --file: IPA file path to be signed
  • -p, --profile: Provisioning profile (.mobileprovision) path
  • -v, --version: Version number (e.g., 1.0)
  • -b, --build: Build number (e.g., 1)
  • -n, --name: Override app display name
  • -o, --output: Custom output IPA filename
  • -c, --certificate: Override signing certificate name
  • --iphone-only: Strip iPad metadata and keep only iPhone device family
  • --ipad-multitasking-orientations: Force all four orientations for iPad multitasking validation
  • --no-ipad-multitasking-orientations: Disable auto orientation patching and keep original Info.plist values
  • -h, --help: Show help information

2.3 Examples

# Show help information
ios_sign -h

# Sign application
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1

# Override display name
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 -n "My App"

# Set custom output filename
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 -o release-build.ipa

# Force iPad multitasking orientations
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 --ipad-multitasking-orientations

2.4 Orientation Handling

  • By default the tool preserves the original orientation configuration from Info.plist
  • It only auto-patches UISupportedInterfaceOrientations when all of the following are true:
  • The app declares iPad support in UIDeviceFamily
  • UIRequiresFullScreen is not true
  • The orientation keys do not already contain all four required values for iPad multitasking
  • Use --ipad-multitasking-orientations to force the patch
  • Use --no-ipad-multitasking-orientations to disable the auto-patch completely

3. Prerequisites

3.1 Requirements

  • Ensure Xcode Command Line Tools is installed
  • Ensure signing certificate is imported to Keychain
  • Ensure valid provisioning profile (.mobileprovision) is available

3.2 File Requirements

  • IPA file must exist and be readable
  • Provisioning profile must exist and be valid
  • If app contains extensions, corresponding profiles should be in the same directory

3.3 Permission Requirements

  • Sufficient permissions to access Keychain
  • Write permissions to target directory

4. Output

4.1 Generated Files

  • Signed IPA filename format: version-build-timestamp.ipa
  • Example: 1.0-3-20250206_122425.ipa
  • You can override the output filename with -o, for example: release-build.ipa

4.2 Log Information

  • Shows detailed signing process
  • Shows all signed components (main app, frameworks, plugins)
  • Shows final verification results

5. Troubleshooting

5.1 Common Errors

  • command not found: Check installation path and permissions
  • no identity found: Check if certificate is properly imported to Keychain
  • signing verification failed: Check if certificate and profile match
  • AppIcon contains alpha: Replace all AppIcon PNG files with non-alpha RGB images and rebuild/repack the IPA
  • Invalid bundle ... need to include all orientations to support iPad multitasking: Review UIDeviceFamily, UIRequiresFullScreen, and UISupportedInterfaceOrientations, or force the patch with --ipad-multitasking-orientations

5.2 Solutions

  • Run security find-identity -v -p codesigning to view available signing certificates
  • Ensure certificate name in profile matches exactly with Keychain
  • Check if IPA file is complete and not corrupted

6. Maintenance

6.1 Update Using Installation Script

# Update installation
./install.sh

# Uninstall old version
./install.sh --uninstall

6.2 Manual Update

# Update script content
sudo vim /usr/local/bin/ios_sign

# Or copy new version
sudo cp new_sign_ios_app.sh /usr/local/bin/ios_sign

6.3 Uninstallation

# Uninstall using installation script
./install.sh --uninstall

# Or manual uninstall
sudo rm /usr/local/bin/ios_sign

7. Features

7.1 Automatic Processing

  • Automatically removes content outside Payload before repacking
  • Automatically removes PlugIns when present
  • Automatically removes libswift*.dylib in Frameworks when present
  • Automatically extracts certificate information from profile
  • Automatically handles nested bundles and embedded frameworks signing
  • Automatically validates AppIcon alpha channel before signing
  • Automatically decides whether iPad multitasking orientation patching is required

7.2 Security Features

  • Uses temporary directory for processing, avoiding original file pollution
  • Automatic cleanup of temporary files
  • Complete signing verification process

7.3 Error Handling

  • Detailed error messages
  • Automatic cleanup on failure
  • Signing integrity verification

中文文档

项目介绍

这是一个用于 iOS 应用重签名的命令行工具，主要用于企业级应用的重新签名和分发。它可以帮助开发者和企业快速完成 iOS 应用的重签名过程，支持处理包含扩展插件的复杂应用。

主要功能

  • 支持 IPA 文件的重签名
  • 自动处理应用扩展（App Extensions）
  • 自动处理嵌入式框架（Embedded Frameworks）
  • 默认删除 Payload 之外的文件和目录
  • 默认删除 PlugIns 目录（存在时）
  • 默认删除 Frameworks 下的 libswift*.dylib（存在时）
  • 自动提取和验证证书信息
  • 签名前自动检测 AppIcon 是否包含透明通道
  • 默认保留原始横竖屏配置，仅在 Info.plist 条件满足时自动补齐 iPad 多任务四方向
  • 提供详细的日志输出

技术特点

  • 使用 Shell 脚本编写，无需额外依赖
  • 提供自动安装脚本，便于部署
  • 支持命令行参数，便于集成到自动化流程
  • 包含完整的错误处理和日志记录

使用文档

1. 安装步骤

1.1 使用安装脚本（推荐）

提供了自动安装脚本 install.sh，可以自动完成所有安装步骤：

# 添加执行权限
chmod +x install.sh

# 执行安装
./install.sh

安装脚本特性：

  • 自动检查系统环境（macOS 和 Xcode 工具）
  • 自动处理权限和依赖
  • 自动验证安装结果
  • 提供卸载功能

卸载命令：

./install.sh --uninstall

1.2 手动安装（可选）

如果您不想使用安装脚本，也可以手动安装：

1.2.1 创建系统级目录
sudo mkdir -p /usr/local/bin
1.2.2 复制脚本到系统目录
sudo cp sign_ios_app.sh /usr/local/bin/ios_sign
1.2.3 设置正确的权限
# 添加执行权限
sudo chmod 755 /usr/local/bin/ios_sign

# 设置所有者为root
sudo chown root:wheel /usr/local/bin/ios_sign
1.2.4 验证安装
# 检查命令是否可用
which ios_sign

# 应该输出：/usr/local/bin/ios_sign

2. 使用方法

2.1 命令格式

ios_sign -f <ipa文件> -p <描述文件> -v <版本号> -b <构建号>

2.2 参数说明

  • -f, --file: 要签名的IPA文件路径
  • -p, --profile: 描述文件(.mobileprovision)路径
  • -v, --version: 版本号（如：1.0）
  • -b, --build: 构建号（如：1）
  • -n, --name: 修改应用显示名称
  • -o, --output: 自定义输出 IPA 文件名
  • -c, --certificate: 指定签名证书名称
  • --iphone-only: 移除 iPad 声明，仅保留 iPhone 设备族
  • --ipad-multitasking-orientations: 强制补齐 iPad 多任务所需四方向
  • --no-ipad-multitasking-orientations: 禁止自动补方向键，完全保留原始 Info.plist
  • -h, --help: 显示帮助信息

2.3 使用示例

# 显示帮助信息
ios_sign -h

# 签名应用
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1

# 修改显示名称
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 -n "新应用名称"

# 自定义输出文件名
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 -o release-build.ipa

# 强制补齐 iPad 多任务四方向
ios_sign -f MyApp.ipa -p MyApp.mobileprovision -v 1.0 -b 1 --ipad-multitasking-orientations

2.4 横竖屏处理策略

  • 默认保留 IPA 原始 Info.plist 中的横竖屏配置
  • 只有同时满足以下条件时，脚本才会自动补齐 UISupportedInterfaceOrientations 四方向：
  • UIDeviceFamily 声明支持 iPad
  • UIRequiresFullScreen 不为 true
  • 当前方向键尚未包含 iPad 多任务要求的四个方向
  • --ipad-multitasking-orientations 可强制补齐四方向
  • --no-ipad-multitasking-orientations 可完全关闭自动补丁

3. 注意事项

3.1 前置条件

  • 确保系统已安装 Xcode 命令行工具
  • 确保签名证书已导入到钥匙串中
  • 确保有正确的描述文件(.mobileprovision)

3.2 文件要求

  • IPA文件必须存在且可读
  • 描述文件必须存在且有效
  • 如果应用包含扩展插件，相应的描述文件应该位于同一目录下

3.3 权限要求

  • 需要有足够的权限访问钥匙串
  • 需要有目标目录的写入权限

4. 输出说明

4.1 生成文件

  • 签名后的IPA文件名格式：版本号-构建号-时间戳.ipa
  • 例如：1.0-3-20250206_122425.ipa
  • 可通过 -o 指定自定义输出文件名，例如：release-build.ipa

4.2 日志信息

  • 显示签名过程的详细信息
  • 显示所有签名的组件（主程序、框架、插件等）
  • 显示最终的验证结果

5. 故障排除

5.1 常见错误

  • command not found: 检查安装路径和权限
  • no identity found: 检查证书是否正确导入钥匙串
  • 验证签名失败: 检查证书和描述文件是否匹配
  • 检测到 AppIcon 存在透明度: 需要将所有 AppIcon PNG 替换为无 alpha 的 RGB 图片后重新打包
  • Invalid bundle ... need to include all orientations to support iPad multitasking: 检查 UIDeviceFamily、UIRequiresFullScreen 与方向键配置，必要时使用 --ipad-multitasking-orientations

5.2 解决方法

  • 运行 security find-identity -v -p codesigning 查看可用的签名证书
  • 确保描述文件中的证书名称与钥匙串中的完全匹配
  • 检查 IPA 文件是否完整且未损坏

6. 更新维护

6.1 使用安装脚本更新

# 更新安装
./install.sh

# 卸载旧版本
./install.sh --uninstall

6.2 手动更新

# 更新脚本内容
sudo vim /usr/local/bin/ios_sign

# 或者重新复制新版本
sudo cp new_sign_ios_app.sh /usr/local/bin/ios_sign

6.3 卸载

# 使用安装脚本卸载
./install.sh --uninstall

# 或者手动卸载
sudo rm /usr/local/bin/ios_sign

7. 功能特性

7.1 自动处理

  • 重新打包前自动删除 Payload 之外的内容
  • 自动删除 PlugIns 目录（存在时）
  • 自动删除 Frameworks 下的 libswift*.dylib（存在时）
  • 自动从描述文件中提取证书信息
  • 自动处理嵌套 Bundle 与嵌入式 Framework 的签名
  • 自动执行 AppIcon alpha 检查
  • 自动判断是否需要补齐 iPad 多任务方向键

7.2 安全特性

  • 使用临时目录处理文件，避免污染原始文件
  • 自动清理临时文件
  • 完整的签名验证流程

7.3 错误处理

  • 详细的错误提示
  • 失败时自动清理
  • 验证签名完整性

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages