# Offline Signature Provider for SPSDK
A plugin for SPSDK that provides an offline signature provider for secure boot workflows.
## Overview
The Offline Signature Provider allows you to sign data without having the private key directly accessible to the SPSDK tool. Instead, it:
1. Calculates the hash of the data to be signed
2. Writes the hash to a file
3. Waits for you to provide a signature file (which you can generate using your secure signing process)
4. Verifies and uses the provided signature
This workflow is particularly useful for high-security environments where private keys must be kept in secure hardware or air-gapped systems.
## Installation
```bash
pip install spsdk-offline-signature-provider
```
## Configuration
The Offline Signature Provider can be configured with the following options:
### Supported Algorithms
- **ECC** (`ecc`): Elliptic Curve Cryptography
- **RSA-PSS** (`rsa-pss`): RSA with PSS padding
- **RSA-PKCS1v15** (`rsa-pkcs1v15`): RSA with PKCS#1 v1.5 padding
### Supported Key Sizes
#### ECC Key Sizes
- **256 bits**: Default SHA-256 hash algorithm, 64-byte signature
- **384 bits**: Default SHA-384 hash algorithm, 96-byte signature
- **521 bits**: Default SHA-512 hash algorithm, 132-byte signature
#### RSA Key Sizes
- **2048 bits**: Default SHA-256 hash algorithm, 256-byte signature
- **3072 bits**: Default SHA-256 hash algorithm, 384-byte signature
- **4096 bits**: Default SHA-256 hash algorithm, 512-byte signature
### Supported Hash Algorithms
You can override the default hash algorithm by specifying one of:
- **SHA-256** (`sha256`): 256-bit hash
- **SHA-384** (`sha384`): 384-bit hash
- **SHA-512** (`sha512`): 512-bit hash
- **SHA-1** (`sha1`): 160-bit hash (legacy, not recommended for new applications)
### Configuration Parameters
When configuring the offline signature provider in your SPSDK configuration file, you can specify:
- `hash_file`: Base name for the hash file (default: `"hash_file"`)
- `key_size`: Size of the key in bits (default: `"256"`)
- `algorithm`: Signature algorithm to use (default: `"ecc"`)
- `hash_algorithm`: Hash algorithm to use (optional, uses algorithm/key-size defaults if not specified)
### Example Configurations
#### Basic Configuration (using defaults)
```yaml
# SPSDK configuration file example
signer: type=offline-sp;algorithm=ecc;key_size=256
```
#### Advanced Configuration with Custom Hash Algorithm
```yaml
# SPSDK configuration file example with custom hash
signer: type=offline-sp;algorithm=rsa-pss;key_size=2048;hash_algorithm=sha384
```
#### Configuration with Custom Hash File Name
```yaml
# SPSDK configuration file example with custom hash file
signer: type=offline-sp;hash_file=my_container_hash;algorithm=ecc;key_size=384
```
### Hash File Naming
The provider automatically creates algorithm-specific hash file names:
- Format: `{hash_file}_{algorithm}.{hash_algorithm}`
- Examples:
- `hash_file_ecc.SHA256` (ECC-256 with default SHA-256)
- `hash_file_rsa-pss.SHA384` (RSA-PSS-2048 with custom SHA-384)
- `my_container_hash_ecc.SHA384` (ECC-384 with custom hash file name)
### Default Hash Algorithm Behavior
If no `hash_algorithm` is specified, the provider uses these defaults:
#### ECC Defaults
- 256-bit key: SHA-256
- 384-bit key: SHA-384
- 521-bit key: SHA-512
#### RSA Defaults (both PSS and PKCS1v15)
- 2048-bit key: SHA-256
- 3072-bit key: SHA-256
- 4096-bit key: SHA-256
### Workflow
1. When SPSDK needs to sign data, it will call the Offline Signature Provider
2. The provider will:
- Calculate the hash of the data using the configured hash algorithm
- Print the hash value to the console
- Save the hash to a file (e.g., `hash_file_ecc.SHA256`)
- Display algorithm-specific signing instructions
- Indicate whether using default or custom hash algorithm
- Prompt you to provide the path to a signature file
3. You can then:
- Use your secure signing process to sign the hash according to the displayed instructions
- Provide the path to the signature file when prompted
4. The provider will:
- Validate the signature format and size
- Process the signature according to the algorithm (handle DER encoding if needed)
- Return the signature to SPSDK to complete the operation
### Algorithm-Specific Instructions
#### ECC Signing
- Use the provided hash with your ECC private key
- Signature can be in raw r||s format or DER-encoded format
- The provider will automatically convert DER-encoded signatures to raw format
#### RSA-PSS Signing
- Use the provided hash with your RSA private key and PSS padding
- Use the specified hash algorithm with PSS padding
- Salt length should equal digest length
- Provide signature as raw bytes
#### RSA-PKCS1v15 Signing
- Use the provided hash with your RSA private key and PKCS#1 v1.5 padding
- Use the specified hash algorithm with PKCS#1 v1.5 padding
- Provide signature as raw bytes
### Hash Algorithm Override Examples
#### Using SHA-384 with ECC-256 (instead of default SHA-256)
```yaml
signer: type=offline-sp;algorithm=ecc;key_size=256;hash_algorithm=sha384
```
#### Using SHA-512 with RSA-PSS-2048 (instead of default SHA-256)
```yaml
signer: type=offline-sp;algorithm=rsa-pss;key_size=2048;hash_algorithm=sha512
```
### Requirements
- Python 3.9+
- SPSDK 3.x
### Provider Identifier
The provider uses the identifier `offline-sp` in SPSDK configuration files.
## License
This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "spsdk-offline-signature-provider",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "NXP <spsdk@nxp.com>",
"keywords": "NXP, SPSDK, Signature Provider",
"author": "NXP",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/59/db/768091d0b2d782b0fd1790c45405baef79a7b1a24ed7e15a7c56775fe3e5/spsdk_offline_signature_provider-0.2.0.tar.gz",
"platform": null,
"description": "# Offline Signature Provider for SPSDK\n\nA plugin for SPSDK that provides an offline signature provider for secure boot workflows.\n\n## Overview\n\nThe Offline Signature Provider allows you to sign data without having the private key directly accessible to the SPSDK tool. Instead, it:\n\n1. Calculates the hash of the data to be signed\n2. Writes the hash to a file\n3. Waits for you to provide a signature file (which you can generate using your secure signing process)\n4. Verifies and uses the provided signature\n\nThis workflow is particularly useful for high-security environments where private keys must be kept in secure hardware or air-gapped systems.\n\n## Installation\n\n```bash\npip install spsdk-offline-signature-provider\n```\n\n## Configuration\n\nThe Offline Signature Provider can be configured with the following options:\n\n### Supported Algorithms\n\n- **ECC** (`ecc`): Elliptic Curve Cryptography\n- **RSA-PSS** (`rsa-pss`): RSA with PSS padding\n- **RSA-PKCS1v15** (`rsa-pkcs1v15`): RSA with PKCS#1 v1.5 padding\n\n### Supported Key Sizes\n\n#### ECC Key Sizes\n- **256 bits**: Default SHA-256 hash algorithm, 64-byte signature\n- **384 bits**: Default SHA-384 hash algorithm, 96-byte signature\n- **521 bits**: Default SHA-512 hash algorithm, 132-byte signature\n\n#### RSA Key Sizes\n- **2048 bits**: Default SHA-256 hash algorithm, 256-byte signature\n- **3072 bits**: Default SHA-256 hash algorithm, 384-byte signature\n- **4096 bits**: Default SHA-256 hash algorithm, 512-byte signature\n\n### Supported Hash Algorithms\n\nYou can override the default hash algorithm by specifying one of:\n- **SHA-256** (`sha256`): 256-bit hash\n- **SHA-384** (`sha384`): 384-bit hash\n- **SHA-512** (`sha512`): 512-bit hash\n- **SHA-1** (`sha1`): 160-bit hash (legacy, not recommended for new applications)\n\n### Configuration Parameters\n\nWhen configuring the offline signature provider in your SPSDK configuration file, you can specify:\n\n- `hash_file`: Base name for the hash file (default: `\"hash_file\"`)\n- `key_size`: Size of the key in bits (default: `\"256\"`)\n- `algorithm`: Signature algorithm to use (default: `\"ecc\"`)\n- `hash_algorithm`: Hash algorithm to use (optional, uses algorithm/key-size defaults if not specified)\n\n### Example Configurations\n\n#### Basic Configuration (using defaults)\n```yaml\n# SPSDK configuration file example\nsigner: type=offline-sp;algorithm=ecc;key_size=256\n```\n\n#### Advanced Configuration with Custom Hash Algorithm\n```yaml\n# SPSDK configuration file example with custom hash\nsigner: type=offline-sp;algorithm=rsa-pss;key_size=2048;hash_algorithm=sha384\n```\n\n#### Configuration with Custom Hash File Name\n```yaml\n# SPSDK configuration file example with custom hash file\nsigner: type=offline-sp;hash_file=my_container_hash;algorithm=ecc;key_size=384\n```\n\n### Hash File Naming\n\nThe provider automatically creates algorithm-specific hash file names:\n- Format: `{hash_file}_{algorithm}.{hash_algorithm}`\n- Examples:\n - `hash_file_ecc.SHA256` (ECC-256 with default SHA-256)\n - `hash_file_rsa-pss.SHA384` (RSA-PSS-2048 with custom SHA-384)\n - `my_container_hash_ecc.SHA384` (ECC-384 with custom hash file name)\n\n### Default Hash Algorithm Behavior\n\nIf no `hash_algorithm` is specified, the provider uses these defaults:\n\n#### ECC Defaults\n- 256-bit key: SHA-256\n- 384-bit key: SHA-384\n- 521-bit key: SHA-512\n\n#### RSA Defaults (both PSS and PKCS1v15)\n- 2048-bit key: SHA-256\n- 3072-bit key: SHA-256\n- 4096-bit key: SHA-256\n\n### Workflow\n\n1. When SPSDK needs to sign data, it will call the Offline Signature Provider\n2. The provider will:\n - Calculate the hash of the data using the configured hash algorithm\n - Print the hash value to the console\n - Save the hash to a file (e.g., `hash_file_ecc.SHA256`)\n - Display algorithm-specific signing instructions\n - Indicate whether using default or custom hash algorithm\n - Prompt you to provide the path to a signature file\n3. You can then:\n - Use your secure signing process to sign the hash according to the displayed instructions\n - Provide the path to the signature file when prompted\n4. The provider will:\n - Validate the signature format and size\n - Process the signature according to the algorithm (handle DER encoding if needed)\n - Return the signature to SPSDK to complete the operation\n\n### Algorithm-Specific Instructions\n\n#### ECC Signing\n- Use the provided hash with your ECC private key\n- Signature can be in raw r||s format or DER-encoded format\n- The provider will automatically convert DER-encoded signatures to raw format\n\n#### RSA-PSS Signing\n- Use the provided hash with your RSA private key and PSS padding\n- Use the specified hash algorithm with PSS padding\n- Salt length should equal digest length\n- Provide signature as raw bytes\n\n#### RSA-PKCS1v15 Signing\n- Use the provided hash with your RSA private key and PKCS#1 v1.5 padding\n- Use the specified hash algorithm with PKCS#1 v1.5 padding\n- Provide signature as raw bytes\n\n### Hash Algorithm Override Examples\n\n#### Using SHA-384 with ECC-256 (instead of default SHA-256)\n```yaml\nsigner: type=offline-sp;algorithm=ecc;key_size=256;hash_algorithm=sha384\n```\n\n#### Using SHA-512 with RSA-PSS-2048 (instead of default SHA-256)\n```yaml\nsigner: type=offline-sp;algorithm=rsa-pss;key_size=2048;hash_algorithm=sha512\n```\n\n### Requirements\n\n- Python 3.9+\n- SPSDK 3.x\n\n### Provider Identifier\n\nThe provider uses the identifier `offline-sp` in SPSDK configuration files.\n\n## License\n\nThis project is licensed under the BSD-3-Clause License - see the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Offline Signature Provider for SPSDK.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/nxp-mcuxpresso/spsdk_plugins/tree/master/offline_signature_provider",
"Issues": "https://github.com/nxp-mcuxpresso/spsdk_plugins/issues"
},
"split_keywords": [
"nxp",
" spsdk",
" signature provider"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "59db768091d0b2d782b0fd1790c45405baef79a7b1a24ed7e15a7c56775fe3e5",
"md5": "f570bda83d4b5d56ba634e29dc39ec93",
"sha256": "afb04766d30d78300ed0c5c07de4e9a9f64a1b81a3209c16b61ea42bb0c25b25"
},
"downloads": -1,
"filename": "spsdk_offline_signature_provider-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f570bda83d4b5d56ba634e29dc39ec93",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14242,
"upload_time": "2025-08-29T06:24:12",
"upload_time_iso_8601": "2025-08-29T06:24:12.024151Z",
"url": "https://files.pythonhosted.org/packages/59/db/768091d0b2d782b0fd1790c45405baef79a7b1a24ed7e15a7c56775fe3e5/spsdk_offline_signature_provider-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 06:24:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nxp-mcuxpresso",
"github_project": "spsdk_plugins",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spsdk-offline-signature-provider"
}
JSON
