securesystemslib

https://python-securesystemslib.readthedocs.io/en/latest/
Admin
securesystemslib is a cryptography interface for signing and verifying digital signatures with...
Tokens:3,300
Snippets:44
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Signer Usage Example

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Instantiate a Signer from a private key URI and sign data. Applications should use generic try-except blocks to handle potential errors during instantiation or signing.

```python
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data")

```

--------------------------------

### Signer.from_priv_key_uri

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Loads a specific signer implementation from a URI.

```APIDOC
## Signer.from_priv_key_uri

### Description
Loads and initializes a signer instance based on a provided Uniform Resource Identifier (URI).

### Method
Class method, implementation-specific.

### Parameters
* **private_key_uri** (str) - Required - The URI pointing to the private key or signing service.
* **keyids** (list[str]) - Optional - A list of key identifiers to associate with the signer.

### Returns
* **Signer** - An initialized signer object.
```

--------------------------------

### Signer.from_priv_key_uri

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Factory constructor for creating a Signer instance based on a private key URI. It dispatches to specific implementations based on supported URI schemes.

```APIDOC
## Signer.from_priv_key_uri

### Description
Factory constructor for a given private key URI. Returns a specific Signer instance based on the private key URI and the supported uri schemes listed in `SIGNER_FOR_URI_SCHEME`.

### Method
classmethod

### Parameters
#### Path Parameters
- **_priv_key_uri_** (str) - URI that identifies the private key
- **_public_key_** (Key) - Key that is the public portion of this private key
- **_secrets_handler** (Callable[[str], str] | None) - Optional function that may be called if the signer needs additional secrets (like a PIN or passphrase). secrets_handler should return the requested secret string.

### Raises
- **ValueError** - Incorrect arguments
- **Other Signer-specific errors** - These could include OSErrors for reading files or network errors for connecting to a KMS.

### Return Type
Signer
```

--------------------------------

### Key Deserialization from Dictionary

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Demonstrates how to create a Key object from a dictionary representation. The `Key.from_dict()` method dispatches to the appropriate subclass based on the key type and scheme.

```python
key_obj = Key.from_dict(keyid='my-key-id', key_dict={'some': 'key_data'})

```

--------------------------------

### Key Serialization to Dictionary

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Shows how to convert a Key object into its dictionary representation for serialization. Key implementations must override the `to_dict()` method.

```python
key_dict = key_obj.to_dict()

```

--------------------------------

### Key.from_dict

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Loads a specific key implementation from a dictionary.

```APIDOC
## Key.from_dict

### Description
Loads and initializes a key instance from a dictionary representation.

### Method
Class method, implementation-specific.

### Parameters
* **key_dict** (dict) - Required - A dictionary containing the key material and metadata.

### Returns
* **Key** - An initialized key object.
```

--------------------------------

### Registering Custom Signer Implementation

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Allows applications to register their own Signer implementations with the SIGNER_FOR_URI_SCHEME dispatch table, enabling the use of custom signing logic.

```python
from securesystemslib.signer import Signer, SIGNER_FOR_URI_SCHEME
from mylib import MySigner

SIGNER_FOR_URI_SCHEME[MySigner.MY_SCHEME] = MySigner

```

--------------------------------

### Signer Class

Source: https://python-securesystemslib.readthedocs.io/en/latest/_sources/signer.rst.txt

The Signer class handles the private key as an implementation detail and provides methods for signing operations.

```APIDOC
## Signer

### Description
Represents a cryptographic signer that treats the private key as an implementation detail. It can interact with various signing technologies, including remote KMS or local hardware tokens.

### Methods

#### `sign(data: bytes) -> Signature`
Signs the given data using the signer's private key.

#### `from_priv_key_uri(private_key_uri: str, password: Optional[str] = None) -> Signer`
Loads a specific signer from a URI. The signer implementation is responsible for URI format and resolution. Signers are discoverable via the `SIGNER_FOR_URI_SCHEME` lookup table.
```

--------------------------------

### Key.verify_signature

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Abstract method to verify a signature against given data using a public key.

```APIDOC
## Key.verify_signature

### Description
Verifies if the provided signature is valid for the given data using this public key.

### Method
Abstract method, implementation-specific.

### Parameters
* **data** (bytes) - Required - The original data that was signed.
* **signature** (Signature) - Required - The signature to verify.

### Returns
* **bool** - True if the signature is valid, False otherwise.
```

--------------------------------

### Key.verify_signature

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Verifies a signature against a given piece of data using the public key.

```APIDOC
## Key.verify_signature

### Description
Verifies if a signature is valid for the given data.

### Method
Abstractmethod

### Parameters
#### Path Parameters
- **signature** (Signature) - Signature object.
- **data** (bytes) - Payload bytes.

### Raises
- **UnverifiedSignatureError** - Failed to verify signature.
```

--------------------------------

### Key Class

Source: https://python-securesystemslib.readthedocs.io/en/latest/_sources/signer.rst.txt

The Key class serves as a container for public key data and provides methods for verification and loading keys.

```APIDOC
## Key

### Description
A container class for public key data, enabling signature verification and loading of keys from serialized formats.

### Methods

#### `verify_signature(signature: Signature, data: bytes) -> None`
Verifies if the provided signature is valid for the given data using the public key.

#### `from_dict(key_dict: Dict[str, Any]) -> Key`
Loads a specific key from a serialized dictionary format. The key implementation is responsible for deserialization. Key types and signing schemes are registered in the `KEY_FOR_TYPE_AND_SCHEME` lookup table.
```

--------------------------------

### Key.from_dict

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Creates a Key object from a serialized dictionary representation. This is a factory method that dispatches to specific Key subclass implementations.

```APIDOC
## Key.from_dict

### Description
Creates `Key` object from a serialization dict. Key implementations must override this factory constructor that is used as a deserialization helper. Users should call `Key.from_dict()`: it dispatches to the actual subclass implementation based on supported keys in `KEY_FOR_TYPE_AND_SCHEME`.

### Method
Abstractmethod classmethod

### Parameters
#### Path Parameters
- **keyid** (str)
- **key_dict** (dict[str, Any])

### Raises
- **KeyError**, **TypeError** - Invalid arguments.

### Return Type
Key
```

--------------------------------

### Key.to_dict

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Returns a dictionary representation of the Key object, suitable for serialization.

```APIDOC
## Key.to_dict

### Description
Returns a serialization dict. Key implementations must override this serialization helper.

### Method
Abstractmethod

### Return Type
dict[str, Any]
```

--------------------------------

### Signer.sign

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Signs a given payload using the private key associated with the Signer instance.

```APIDOC
## Signer.sign

### Description
Signs a given payload by the key assigned to the Signer instance.

### Method
Abstractmethod

### Parameters
#### Path Parameters
- **payload** (bytes) - The bytes to be signed.

### Returns
Returns a “Signature” class instance.

### Return Type
Signature
```

--------------------------------

### Signature Class

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

The Signature class is a container for signature information, including the signature itself and the key ID used to generate it. It provides methods to create Signature objects from dictionaries and to convert them back into dictionary representations.

```APIDOC
## Class Signature

### Description
A container class containing information about a signature. Contains a signature and the keyid uniquely identifying the key used to generate the signature. Provides utility methods to easily create an object from a dictionary and return the dictionary representation of the object.

### Parameters
- **keyid** (str) - HEX string used as a unique identifier of the key.
- **sig** (str) - HEX string representing the signature.
- **unrecognized_fields** (dict[str, Any] | None) - Dictionary of all attributes that are not managed by securesystemslib.

### Attributes
- **keyid** (str) - HEX string used as a unique identifier of the key.
- **signature** (str) - HEX string representing the signature.
- **unrecognized_fields** (dict[str, Any] | None) - Dictionary of all attributes that are not managed by securesystemslib.

## Class Method from_dict

### Description
Creates a Signature object from its JSON/dict representation.

### Parameters
- **signature_dict** (dict) - A dict containing a valid keyid and a signature. Note that the fields in it should be named “keyid” and “sig” respectively.

### Raises
- **KeyError** - If any of the “keyid” and “sig” fields are missing from the signature_dict.

### Returns
- **Signature** - A “Signature” instance.

### Side Effects
- Destroys the metadata dict passed by reference.

## Method to_dict

### Description
Returns the JSON-serializable dictionary representation of self.

### Returns
- **dict** - The dictionary representation of the Signature object.
```

--------------------------------

### Signer.sign

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Abstract method to sign data. Implementations will handle the actual signing process using specific technologies.

```APIDOC
## Signer.sign

### Description
Signs the given data using the configured private key.

### Method
Abstract method, implementation-specific.

### Parameters
* **data_to_sign** (bytes) - Required - The data to be signed.

### Returns
* **Signature** - An object containing the signature and associated key information.
```

--------------------------------

### Signer with Secrets Handler

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Provides a custom secrets handler to the Signer for interactive applications that may require user input for secrets like PINs or passphrases.

```python
from getpass import getpass

def sec_handler(secret_name:str) -> str:
    return getpass(f"Enter {secret_name}: ")

signer = Signer.from_priv_key_uri(uri, pub_key, sec_handler)

```

--------------------------------

### Signature Class

Source: https://python-securesystemslib.readthedocs.io/en/latest/_sources/signer.rst.txt

Represents a cryptographic signature.

```APIDOC
## Signature

### Description
A class representing a cryptographic signature. It is used in conjunction with the `Signer` and `Key` classes for signing and verification operations.
```

--------------------------------

### Signature Verification

Source: https://python-securesystemslib.readthedocs.io/en/latest/signer.html

Verifies a signature against a given payload using the Key object's `verify_signature` method. This method raises an `UnverifiedSignatureError` if verification fails.

```python
key_obj.verify_signature(signature, data)

```
Tokens:
Raw