Skip to content

keys

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

flavor.packaging.keys

Key management for FlavorPack package signing.

Functions

generate_key_pair 

generate_key_pair(keys_dir: Path) -> tuple[Path, Path]

Generates a new Ed25519 key pair and saves them to PEM files.

This function is used for CLI operations where keys need to be persisted to files for later use. For internal package building where keys are used immediately and discarded, use flavor.psp.format_2025.crypto.generate_key_pair() which returns raw bytes instead.

Ed25519 is used for all PSPF packages as specified in the PSPF/2025 format. This provides: - Small keys (32 bytes public, 32 bytes private seed) - Fast signing and verification - Deterministic signatures - Strong security with no parameters to misconfigure

Parameters:

Name Type Description Default
keys_dir Path

Directory to save the key files

 required

Returns:

Name Type Description
tuple tuple[Path, Path]

(private_key_path, public_key_path)
See Also

flavor.psp.format_2025.crypto.generate_key_pair: For in-memory key generation

Source code in flavor/packaging/keys.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def generate_key_pair(keys_dir: Path) -> tuple[Path, Path]:
    """Generates a new Ed25519 key pair and saves them to PEM files.

    This function is used for CLI operations where keys need to be persisted
    to files for later use. For internal package building where keys are
    used immediately and discarded, use flavor.psp.format_2025.crypto.generate_key_pair()
    which returns raw bytes instead.

    Ed25519 is used for all PSPF packages as specified in the PSPF/2025 format.
    This provides:
    - Small keys (32 bytes public, 32 bytes private seed)
    - Fast signing and verification
    - Deterministic signatures
    - Strong security with no parameters to misconfigure

    Args:
        keys_dir: Directory to save the key files

    Returns:
        tuple: (private_key_path, public_key_path)

    See Also:
        flavor.psp.format_2025.crypto.generate_key_pair: For in-memory key generation
    """
    # Generate Ed25519 key pair
    private_key = ed25519.Ed25519PrivateKey.generate()
    public_key = private_key.public_key()

    # Serialize to PEM format
    private_pem = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    )
    public_pem = public_key.public_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PublicFormat.SubjectPublicKeyInfo,
    )

    # Save to files with secure permissions
    private_key_path = keys_dir / "flavor-private.key"
    public_key_path = keys_dir / "flavor-public.key"

    ensure_dir(keys_dir, mode=0o700)

    # Write private key with restricted permissions (atomic for safety)
    atomic_write(private_key_path, private_pem)
    private_key_path.chmod(DEFAULT_FILE_PERMS)

    # Write public key (atomic for safety)
    atomic_write(public_key_path, public_pem)
    public_key_path.chmod(DEFAULT_FILE_PERMS)  # Use same security level

    return private_key_path, public_key_path

load_private_key_raw 

load_private_key_raw(key_path: Path) -> bytes

Load a private key from PEM file and return raw 32-byte seed.

Parameters:

Name Type Description Default
key_path Path

Path to PEM-encoded private key file

 required

Returns:

Name Type Description
bytes bytes

Raw 32-byte private key seed for Ed25519
Source code in flavor/packaging/keys.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def load_private_key_raw(key_path: Path) -> bytes:
    """Load a private key from PEM file and return raw 32-byte seed.

    Args:
        key_path: Path to PEM-encoded private key file

    Returns:
        bytes: Raw 32-byte private key seed for Ed25519
    """
    from cryptography.hazmat.backends import default_backend
    from cryptography.hazmat.primitives import serialization
    from cryptography.hazmat.primitives.asymmetric import ed25519

    pem_data = key_path.read_bytes()
    try:
        private_key = serialization.load_pem_private_key(pem_data, password=None, backend=default_backend())
    except Exception as e:
        raise ValueError(
            f"Failed to load private key from {key_path}: {e}\n"
            f"Ensure the key is in PEM format and is a valid Ed25519 key."
        ) from e

    # For Ed25519, we need to extract the raw private key bytes differently
    # The cryptography library stores Ed25519 private keys as 32-byte seeds
    if isinstance(private_key, ed25519.Ed25519PrivateKey):
        # Get the private key bytes in PKCS8 format and extract the seed
        pkcs8_bytes = private_key.private_bytes(
            encoding=serialization.Encoding.DER,
            format=serialization.PrivateFormat.PKCS8,
            encryption_algorithm=serialization.NoEncryption(),
        )
        # The Ed25519 seed is the last 32 bytes of the PKCS8 structure
        # PKCS8 format for Ed25519: version + algorithm OID + private key octets
        # The actual seed starts at byte 16 (after headers)
        return pkcs8_bytes[-32:]
    else:
        # Provide helpful error message for incompatible key types
        from cryptography.hazmat.primitives.asymmetric import dsa, ec, rsa

        key_type_name = "unknown"
        if isinstance(private_key, ec.EllipticCurvePrivateKey):
            key_type_name = "EC (Elliptic Curve)"
        elif isinstance(private_key, rsa.RSAPrivateKey):
            key_type_name = "RSA"
        elif isinstance(private_key, dsa.DSAPrivateKey):
            key_type_name = "DSA"
        else:
            key_type_name = type(private_key).__name__

        raise ValueError(
            f"Incompatible key type at {key_path}: Found {key_type_name} key, but Ed25519 is required.\n"
            f"PSPF packages require Ed25519 keys for signing.\n"
            f"To generate new Ed25519 keys, delete the existing keys and run:\n"
            f"  flavor keygen --output keys/"
        )

load_public_key_raw 

load_public_key_raw(key_path: Path) -> bytes

Load a public key from PEM file and return raw 32-byte key.

Parameters:

Name Type Description Default
key_path Path

Path to PEM-encoded public key file

 required

Returns:

Name Type Description
bytes bytes

Raw 32-byte public key for Ed25519
Source code in flavor/packaging/keys.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def load_public_key_raw(key_path: Path) -> bytes:
    """Load a public key from PEM file and return raw 32-byte key.

    Args:
        key_path: Path to PEM-encoded public key file

    Returns:
        bytes: Raw 32-byte public key for Ed25519
    """
    from cryptography.hazmat.primitives import serialization
    from cryptography.hazmat.primitives.asymmetric import dsa, ec, ed25519, rsa

    pem_data = key_path.read_bytes()
    try:
        public_key = serialization.load_pem_public_key(pem_data)
    except Exception as e:
        raise ValueError(
            f"Failed to load public key from {key_path}: {e}\n"
            f"Ensure the key is in PEM format and is a valid Ed25519 key."
        ) from e

    # Check if it's Ed25519
    if isinstance(public_key, ed25519.Ed25519PublicKey):
        # Extract the raw 32-byte public key
        raw_public = public_key.public_bytes(
            encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw
        )
        return raw_public
    else:
        # Provide helpful error message for incompatible key types
        key_type_name = "unknown"
        if isinstance(public_key, ec.EllipticCurvePublicKey):
            key_type_name = "EC (Elliptic Curve)"
        elif isinstance(public_key, rsa.RSAPublicKey):
            key_type_name = "RSA"
        elif isinstance(public_key, dsa.DSAPublicKey):
            key_type_name = "DSA"
        else:
            key_type_name = type(public_key).__name__

        raise ValueError(
            f"Incompatible key type at {key_path}: Found {key_type_name} key, but Ed25519 is required.\n"
            f"PSPF packages require Ed25519 keys for signing.\n"
            f"To generate new Ed25519 keys, delete the existing keys and run:\n"
            f"  flavor keygen --output keys/"
        )