PySequoia

https://github.com/wiktor-k/pysequoia
Admin
PySequoia is a Python library that provides OpenPGP encryption and digital signature facilities...
Tokens:12,352
Snippets:89
Trust Score:9.4
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install PySequoia via Pip

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

This command shows how to install the PySequoia library using pip. It is the standard method for installing Python packages. If a suitable native wheel is not available for your system, a Rust toolchain will be required for installation.

```sh
pip install pysequoia
```

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

### Build PySequoia using Maturin

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

This snippet demonstrates how to build the PySequoia library using Maturin. It involves setting up a virtual environment, installing Maturin, and then running the 'maturin develop' command. This process is essential for development or if a pre-compiled wheel is not available for your system.

```bash
set -euxo pipefail
python -m venv .env
source .env/bin/activate
pip install maturin
maturin develop
```

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

### Revoke Certificates (Python)

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Illustrates the process of revoking a certificate using `Cert.revoke`. It details creating a revocation signature and then merging it with the certificate to mark it as permanently revoked. The example shows the state of the certificate before and after revocation.

```python
from pysequoia import Cert

cert = Cert.generate("Test Revocation <revoke@example.com>")
assert not cert.is_revoked  # Initially not revoked

# Create revocation signature
revocation = cert.revoke(certifier=cert.secrets.certifier())

# Creating revocation doesn't revoke the key yet
assert not cert.is_revoked

# Import revocation signature to revoke the certificate
revoked_cert = Cert.from_bytes(bytes(cert) + bytes(revocation))
assert revoked_cert.is_revoked  # Now revoked
```

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

### Decrypt Data with PySequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Provides an example of how to decrypt OpenPGP encrypted messages using PySequoia. This function can also verify signatures if the message was signed during encryption. Requires a receiver certificate with private keys.

```python
from pysequoia import Cert, encrypt, decrypt

sender = Cert.from_file("no-passwd.pgp")
receiver = Cert.from_file("passwd.pgp")

# Encrypt data
content = "Red Green Blue"
encrypted = encrypt(recipients=[receiver], bytes=content.encode("utf8"))

# Decrypt the data (assuming receiver has the private key and correct password)
# decrypted_content = decrypt(encrypted, password="receiver_password")
# print(f"Decrypted content: {decrypted_content}")
```

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

### Get PGP Key Expiration Time - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Retrieves the expiration time of a PGP key. The 'expiration' attribute returns None if the key has no expiration date, or a datetime object otherwise. Certificates are loaded from files.

```python
from pysequoia import Cert

cert = Cert.from_file("signing-key.asc")

# Cert does not have any expiration date:
assert cert.expiration is None

cert = Cert.from_file("wiktor.asc")
# Cert expires on New Year's Eve
assert str(cert.expiration) == "2022-12-31 12:00:02+00:00"
```

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

### Parse PGP Certificate from Bytes (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Parses a PGP certificate from raw bytes. This is useful when a certificate has been received as a byte string, for example, over a network connection or from a file. The parsed certificate can then be used for cryptographic operations like encryption or verification.

```python
from pysequoia.cert import Cert

cert1 = Cert.generate("Test <test@example.com>")
buffer = bytes(cert1)

parsed_cert = Cert.from_bytes(buffer)
assert str(parsed_cert.user_ids[0]) == "Test <test@example.com>"
```

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

### Revoke PGP Key - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Revokes a PGP key irreversibly. This involves creating a revocation signature using a certifier secret key. The example shows checking the 'is_revoked' status before and after importing the revocation.

```python
from pysequoia import Cert

cert = Cert.generate("Test Revocation <revoke@example.com>")
revocation = cert.revoke(certifier = cert.secrets.certifier())

# creating revocation signature does not revoke the key
assert not cert.is_revoked

# importing revocation signature marks the key as revoked
revoked_cert = Cert.from_bytes(bytes(cert) + bytes(revocation))
assert revoked_cert.is_revoked
```

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

### Add and Read Notations in Certificate (Python)

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Demonstrates how to add notations like Keyoxide proofs to a certificate and how to read existing notation data from a certificate object or file. It involves setting notations using `cert.set_notations` and accessing them via `cert.user_ids[0].notations`.

```python
from pysequoia import Cert, Notation

# Add notations (e.g., Keyoxide proofs)
cert = cert.set_notations(
    cert.secrets.certifier(),
    [Notation("proof@metacode.biz", "dns:metacode.biz")]
)
assert len(cert.user_ids[0].notations) == 1

# Read notation data
notation = cert.user_ids[0].notations[0]
assert notation.key == "proof@metacode.biz"
assert notation.value == "dns:metacode.biz"

# Read existing notations from file
cert_with_notations = Cert.from_file("wiktor.asc")
user_id = cert_with_notations.user_ids[0]
notation = user_id.notations[0]
print(f"Notation: {notation.key} = {notation.value}")
```

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

### Generate GPG Keys for Testing

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

These bash commands illustrate how to generate GPG keys for testing PySequoia's functionality. One key is generated with a password ('passwd@example.com'), and another without a password ('no-passwd@example.com'). The generated keys are then exported to .pgp files.

```bash
# generate a key with password
gpg --batch --pinentry-mode loopback --passphrase hunter22 --quick-gen-key passwd@example.com
gpg --batch --pinentry-mode loopback --passphrase hunter22 --export-secret-key passwd@example.com > passwd.pgp

# generate a key without password
gpg --batch --pinentry-mode loopback --passphrase '' --quick-gen-key no-passwd@example.com future-default
gpg --batch --pinentry-mode loopback --passphrase '' --export-secret-key no-passwd@example.com > no-passwd.pgp
```

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

### Generate and Encrypt/Sign Key - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Demonstrates generating PGP keys for multiple users and then using them for encryption and signing operations. It shows how to encrypt content using one key and specify recipients for decryption.

```python
from pysequoia import Cert

alice = Cert.generate("Alice <alice@example.com>")
bob = Cert.generate("Bob <bob@example.com>")

content = "content to encrypt".encode("utf8")

encrypted = encrypt(signer = alice.secrets.signer(), recipients = [bob], bytes = content)
print(f"Encrypted data: {encrypted}")
```

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

### Parse OpenPGP Certificates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Illustrates parsing OpenPGP certificates from files or byte data using `Cert.from_file` and `Cert.from_bytes`. It also covers splitting byte data containing multiple certificates and parsing from a keyring file.

```python
from pysequoia import Cert

# Parse from file
cert = Cert.from_file("wiktor.asc")
print(f"Loaded cert: {cert.fingerprint}")

# Parse from bytes
cert1 = Cert.generate("Test <test@example.com>")
buffer = bytes(cert1)
parsed_cert = Cert.from_bytes(buffer)
assert str(parsed_cert.user_ids[0]) == "Test <test@example.com>"

# Parse multiple certificates from keyring
cert1 = Cert.generate("Test 1 <test-1@example.com>")
cert2 = Cert.generate("Test 2 <test-2@example.com>")
cert3 = Cert.generate("Test 3 <test-3@example.com>")
buffer = bytes(cert1) + bytes(cert2) + bytes(cert3)

certs = Cert.split_bytes(buffer)
assert len(certs) == 3

# Parse from keyring file
certs_from_file = Cert.split_file("keyring.pgp")
print(f"Found {len(certs_from_file)} certificates in keyring")
```

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

### Sign Data with PySequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Demonstrates how to create digital signatures for data using PySequoia. Supports inline, detached, and cleartext signature modes. Requires a certificate with secret keys for signing.

```python
from pysequoia import Cert, sign, SignatureMode

# Load a certificate with secret keys
signer_cert = Cert.from_file("signing-key.asc")

# Create an inline signature (default)
data = "data to be signed".encode("utf8")
signed = sign(signer_cert.secrets.signer(), data)
print(f"Signed data: {signed}")

# Create a detached signature
detached = sign(
    signer_cert.secrets.signer(),
    data,
    mode=SignatureMode.DETACHED
)
print(f"Detached signature: {detached}")

# Create a cleartext signature
clear = sign(
    signer_cert.secrets.signer(),
    data,
    mode=SignatureMode.CLEAR
)
print(f"Clear signed: {clear}")
```

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

### Generate OpenPGP Certificates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Shows how to generate new OpenPGP certificates with single or multiple user IDs. It supports both RFC 4880 and RFC 9580 profiles and demonstrates immediate use of a generated certificate for encryption.

```python
from pysequoia import Cert, Profile

# Generate a certificate with single user ID
alice = Cert.generate("Alice <alice@example.com>")
print(f"Generated cert with fingerprint {alice.fingerprint}:\n{alice}")

# Generate with multiple user IDs
cert = Cert.generate(user_ids=["First", "Second", "Third"])
assert len(cert.user_ids) == 3

# Generate modern PGP key (RFC 9580)
mary = Cert.generate("Modern Mary <mary@example.com>", profile=Profile.RFC9580)
print(f"Modern cert fingerprint: {mary.fingerprint}")

# Use generated certificate immediately
bob = Cert.generate("Bob <bob@example.com>")
content = "content to encrypt".encode("utf8")
encrypted = encrypt(
    signer=alice.secrets.signer(),
    recipients=[bob],
    bytes=content
)
print(f"Encrypted with generated keys: {encrypted}")
```

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

### Add Notations to Certificates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Demonstrates how to add notation data to a certificate's primary user ID using `Cert.set_notations`. Notations are key-value pairs used for identity proofs and are attached to signatures.

```python
from pysequoia import Cert, Notation

cert = Cert.from_file("signing-key.asc")
assert len(cert.user_ids[0].notations) == 0
```

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

### Decrypt Data with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Demonstrates how to decrypt data using a provided decryptor and password. It also shows how to decrypt data while verifying signatures using a callback function to retrieve verification keys.

```python
decrypted = decrypt(
    decryptor=receiver.secrets.decryptor("hunter22"),  # Password for receiver's key
    bytes=encrypted
)
assert content == decrypted.bytes.decode("utf8")
assert len(decrypted.valid_sigs) == 0  # No signatures in unsigned message

# Decrypt and verify signatures
encrypted_signed = encrypt(
    signer=sender.secrets.signer(),
    recipients=[receiver],
    bytes=content.encode("utf8")
)

def get_certs(key_ids):
    print(f"Required verification keys: {key_ids}")
    return [sender]

decrypted = decrypt(
    decryptor=receiver.secrets.decryptor("hunter22"),
    bytes=encrypted_signed,
    store=get_certs
)
assert content == decrypted.bytes.decode("utf8")
assert decrypted.valid_sigs[0].certificate == sender.fingerprint
assert decrypted.valid_sigs[0].signing_key == sender.fingerprint
```

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

### Parse Signatures from File or Bytes (Python)

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Details how to parse detached OpenPGP signatures using `Sig.from_file` and `Sig.from_bytes`. The snippets demonstrate loading signatures and accessing metadata such as the issuer's fingerprint (`issuer_fpr`) and the creation timestamp (`created`).

```python
from pysequoia import Sig
from datetime import datetime

# Parse signature from file
sig = Sig.from_file("sig.pgp")
print(f"Parsed signature: {repr(sig)}")

# Access signature metadata
assert sig.issuer_fpr == "e8f23996f23218640cb44cbe75cf5ac418b8e74c"
assert sig.created == datetime.fromisoformat("2023-07-19T18:14:01+00:00")

# Parse from bytes
sig_bytes = open("sig.pgp", "rb").read()
sig = Sig.from_bytes(sig_bytes)
print(f"Issuer: {sig.issuer_fpr}")
print(f"Created: {sig.created}")
```

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

### Verify Signatures with PySequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Shows how to verify digital signatures on data using PySequoia. It handles both inline and detached signatures and requires a callback function to provide necessary certificates for verification.

```python
from pysequoia import Cert, sign, verify, SignatureMode, Sig
import tempfile

# Sign some data
signing_key = Cert.from_file("signing-key.asc")
data = "data to be signed".encode("utf8")
signed = sign(signing_key.secrets.signer(), data)

# Define a function to provide certificates for verification
def get_certs(key_ids):
    print(f"Required signing keys: {key_ids}")
    return [signing_key]

# Verify inline signature
result = verify(signed, get_certs)
assert result.bytes.decode("utf8") == "data to be signed"
assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"
assert result.valid_sigs[0].signing_key == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"

# Verify detached signature
detached = sign(signing_key.secrets.signer(), data, mode=SignatureMode.DETACHED)
detached_sig = Sig.from_bytes(detached)
result = verify(bytes=data, store=get_certs, signature=detached_sig)
assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"

# Verify detached signature against a file
with tempfile.NamedTemporaryFile(delete=False) as tmp:
    tmp.write(data)
    tmp.close()
    result = verify(file=tmp.name, store=get_certs, signature=detached_sig)
    assert len(result.valid_sigs) > 0
```

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

### Generate and Export Certificate Secrets (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Demonstrates how to generate a certificate with secret keys using Cert.generate(), verify that it has secret keys, and then export only the public parts. It also shows how to export the secret parts using `c.secrets` and reconstruct a certificate with secret keys from these exported parts. This functionality is crucial for securely managing cryptographic keys.

```python
c = Cert.generate("Testing key <test@example.com>")
assert c.has_secret_keys

# by default only public parts are exported
public_parts = Cert.from_bytes(f"{c}".encode("utf8"))
assert not public_parts.has_secret_keys
assert public_parts.secrets is None

# to export secret parts use the following:
private_parts = Cert.from_bytes(f"{c.secrets}".encode("utf8"))
assert private_parts.has_secret_keys
```

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

### Verify Signed Data with PySequoia

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

This Python code demonstrates how to verify signed data using PySequoia. It includes a function 'get_certs' to provide necessary certificates for verification and then uses the 'verify' function to check the integrity of the signed message. It also shows how to verify detached signatures by passing the signature separately.

```python
from pysequoia import verify

# sign some data
signing_key = Cert.from_file("signing-key.asc")
signed = sign(s.secrets.signer(), "data to be signed".encode("utf8"))

def get_certs(key_ids):
  # key_ids is an array of required signing keys
  print(f"For verification, we need these keys: {key_ids}")
  return [signing_key]

# verify the data
result = verify(signed, get_certs)
assert result.bytes.decode("utf8") == "data to be signed"

# let's check the valid signature's certificate and signing subkey fingerprints
assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"
assert result.valid_sigs[0].signing_key == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"

# Detached signatures can be verified by passing additional parameter with the detached signature:
data = "data to be signed".encode("utf8")
detached = sign(s.secrets.signer(), data, mode=SignatureMode.DETACHED)
detached = Sig.from_bytes(detached)

result = verify(bytes=data, store=get_certs, signature=detached)
```

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

### Sign Data with PySequoia

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

This Python code snippet demonstrates how to sign data using PySequoia. It shows signing in three modes: standard (armored output), detached signature, and clear-signed message. It requires loading a signing certificate and uses the 'sign' function with different 'SignatureMode' options.

```python
from pysequoia import sign, SignatureMode

s = Cert.from_file("signing-key.asc")
signed = sign(s.secrets.signer(), "data to be signed".encode("utf8"))
print(f"Signed data: {signed}")
assert "PGP MESSAGE" in str(signed)

detached = sign(s.secrets.signer(), "data to be signed".encode("utf8)), mode=SignatureMode.DETACHED)
print(f"Detached signature: {detached}")
assert "PGP SIGNATURE" in str(detached)

clear = sign(s.secrets.signer(), "data to be signed".encode("utf8)), mode=SignatureMode.CLEAR)
print(f"Clear signed: {clear}")
assert "PGP SIGNED MESSAGE" in str(clear)
```

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

### sign - Create digital signatures for data

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Signs data using a private key and returns an armored OpenPGP signature. Supports inline signatures (data embedded), detached signatures (separate signature file), and cleartext signatures (human-readable signed messages).

```APIDOC
## sign - Create digital signatures for data

### Description
Signs data using a private key and returns an armored OpenPGP signature. Supports inline signatures (data embedded), detached signatures (separate signature file), and cleartext signatures (human-readable signed messages).

### Method
POST (conceptual, as this is a library function, not a web API endpoint)

### Endpoint
N/A (Python library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **signer** (object) - Required - The signer's secret key.
- **data** (bytes) - Required - The data to be signed.
- **mode** (SignatureMode, optional) - The mode of the signature (e.g., SignatureMode.DETACHED, SignatureMode.CLEAR). Defaults to inline signature.

### Request Example
```python
from pysequoia import Cert, sign, SignatureMode

# Load a certificate with secret keys
signer_cert = Cert.from_file("signing-key.asc")

# Create an inline signature (default)
data = "data to be signed".encode("utf8")
signed = sign(signer_cert.secrets.signer(), data)
print(f"Signed data: {signed}")

# Create a detached signature
detached = sign(
    signer_cert.secrets.signer(),
    data,
    mode=SignatureMode.DETACHED
)
print(f"Detached signature: {detached}")

# Create a cleartext signature
clear = sign(
    signer_cert.secrets.signer(),
    data,
    mode=SignatureMode.CLEAR
)
print(f"Clear signed: {clear}")
```

### Response
#### Success Response (200)
- **signed_data** (str) - The armored OpenPGP signature or signed message.

#### Response Example
```json
{
  "signed_data": "-----BEGIN PGP MESSAGE-----\n\n...\n-----END PGP MESSAGE-----"
}
```
```

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

### Access Secret Key Material (Python)

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Explains how to access secret key material for certificates that contain private keys using `Cert.secrets`. It covers exporting public and private parts of a certificate and using the secret keys for signing, decryption, and certification operations.

```python
from pysequoia import Cert

# Generate certificate with secret keys
cert = Cert.generate("Testing key <test@example.com>")
assert cert.has_secret_keys

# By default, only public parts are exported
public_parts = Cert.from_bytes(f"{cert}".encode("utf8"))
assert not public_parts.has_secret_keys
assert public_parts.secrets is None

# Export secret parts explicitly
private_parts = Cert.from_bytes(f"{cert.secrets}".encode("utf8"))
assert private_parts.has_secret_keys

# Use secrets for signing and decryption
signer = cert.secrets.signer()  # For signing operations
decryptor = cert.secrets.decryptor("password")  # For decryption
certifier = cert.secrets.certifier()  # For certificate modifications
```

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

### Merge Certificate Updates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Demonstrates merging updates from a newer certificate version into an older one using `Cert.merge`. This is useful for importing new signatures, user IDs, or revocations.

```python
from pysequoia import Cert

# Load old and new versions of the same certificate
old = Cert.from_file("wiktor.asc")
new = Cert.from_file("wiktor-fresh.asc")

# Merge updates from new version
merged = old.merge(new)
print(f"Merged certificate: {merged.fingerprint}")
```

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

### Generate and Serialize PGP Certificate (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Generates a new PGP certificate for a given user ID and serializes it into ASCII armored and raw byte formats. The generated certificate can be used for cryptographic operations. The raw bytes can be stored or transmitted, while the armored version is human-readable.

```python
from pysequoia.cert import Cert

cert = Cert.generate("Test <test@example.com>")

print(f"Armored cert: {cert}")
print(f"Bytes of the cert: {bytes(cert)}")
```

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

### Read PGP Certificate Notation - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Reads and displays a notation attached to a user ID within a PGP certificate. Notations are small data pieces, often used for proofs like Keyoxide URIs. Access is via 'user_ids[index].notations[index]'.

```python
from pysequoia import Cert

cert = Cert.from_file("wiktor.asc")
user_id = cert.user_ids[0]
notation = user_id.notations[0]

assert notation.key == "proof@metacode.biz";
assert notation.value == "dns:metacode.biz?type=TXT";
```

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

### Encrypt Data with PySequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Illustrates how to encrypt data using recipient public keys with PySequoia. The function can optionally sign the encrypted data using a sender's private key. Requires recipient certificates and optionally sender certificate with password.

```python
from pysequoia import Cert, encrypt

# Load sender's certificate with secret keys (for signing)
sender = Cert.from_file("passwd.pgp")

# Load recipient's certificate (for encryption)
recipient = Cert.from_bytes(open("wiktor.asc", "rb").read())

# Encrypt and sign data
content = "content to encrypt".encode("utf8")
encrypted = encrypt(
    signer=sender.secrets.signer("hunter22"),  # Password for sender's key
    recipients=[recipient],
    bytes=content
).decode("utf8")
print(f"Encrypted data: {encrypted}")

# Encrypt without signing (anonymous encryption)
receiver = Cert.from_file("passwd.pgp")
content = "Red Green Blue".encode("utf8")
encrypted = encrypt(recipients=[receiver], bytes=content)
```

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

### Parse Detached Signatures (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Shows how to load detached signatures from files or bytes using `Sig.from_file` and `Sig.from_bytes`. It demonstrates accessing signature properties like the issuer's fingerprint (`issuer_fpr`) and creation timestamp (`created`). This is useful for verifying the authenticity and integrity of signed data.

```python
from pysequoia import Sig
from datetime import datetime

sig = Sig.from_file("sig.pgp")

print(f"Parsed signature: {repr(sig)}")

assert sig.issuer_fpr == "e8f23996f23218640cb44cbe75cf5ac418b8e74c"
assert sig.created == datetime.fromisoformat("2023-07-19T18:14:01+00:00")
```

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

### Generate Key with Multiple User IDs - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Creates a new PGP key that can have multiple user IDs associated with it. User IDs are provided as a list to the 'generate' function. This is useful for associating an identity with multiple names or email addresses.

```python
from pysequoia import Cert

cert = Cert.generate(user_ids = ["First", "Second", "Third"])
assert len(cert.user_ids) == 3
```

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

### Set Certificate Expiration (Python)

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Shows how to set or update the expiration time for a certificate's primary key using the `Cert.set_expiration` method. This involves providing a `datetime` object for the expiration and the certifier's identity. It also demonstrates checking the expiration on an existing certificate.

```python
from pysequoia import Cert
from datetime import datetime

cert = Cert.from_file("signing-key.asc")
assert cert.expiration is None  # No expiration initially

# Set expiration date
expiration = datetime.fromisoformat("2021-11-04T00:05:23+00:00")
cert = cert.set_expiration(
    expiration=expiration,
    certifier=cert.secrets.certifier()
)
assert str(cert.expiration) == "2021-11-04 00:05:23+00:00"

# Check expiration on an existing certificate
cert_with_expiry = Cert.from_file("wiktor.asc")
print(f"Certificate expires: {cert_with_expiry.expiration}")
# Output: 2022-12-31 12:00:02+00:00
```

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

### Add PGP Certificate Notation - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Adds a new notation to a user ID within a PGP certificate. This involves creating a Notation object and using the 'set_notations' method, requiring a certifier. The number of notations and their content are verified.

```python
from pysequoia import Notation, Cert

cert = Cert.from_file("signing-key.asc")

# No notations initially
assert len(cert.user_ids[0].notations) == 0;

cert = cert.set_notations(cert.secrets.certifier(), [Notation("proof@metacode.biz", "dns:metacode.biz")])

# Has one notation now
print(str(cert.user_ids[0].notations))
assert len(cert.user_ids[0].notations) == 1;

# Check the notation data
notation = cert.user_ids[0].notations[0]

assert notation.key == "proof@metacode.biz";
assert notation.value == "dns:metacode.biz";
```

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

### verify - Verify digital signatures

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Verifies signed data and returns the verified content along with signature information. Supports both inline and detached signatures, and can verify against files or byte data.

```APIDOC
## verify - Verify digital signatures

### Description
Verifies signed data and returns the verified content along with signature information. Supports both inline and detached signatures, and can verify against files or byte data.

### Method
POST (conceptual, as this is a library function, not a web API endpoint)

### Endpoint
N/A (Python library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **signed_data** (bytes or str) - Required - The signed data or signature to verify.
- **data** (bytes, optional) - The data content to verify against (used for detached signatures).
- **signature** (Sig, optional) - The detached signature object.
- **store** (function) - Required - A function that takes a list of key IDs and returns a list of certificates to use for verification.
- **file** (str, optional) - Path to a file containing the signed data.

### Request Example
```python
from pysequoia import Cert, sign, verify, SignatureMode, Sig

# Sign some data
signing_key = Cert.from_file("signing-key.asc")
data = "data to be signed".encode("utf8")
signed = sign(signing_key.secrets.signer(), data)

# Define a function to provide certificates for verification
def get_certs(key_ids):
    print(f"Required signing keys: {key_ids}")
    return [signing_key]

# Verify inline signature
result = verify(signed, get_certs)
assert result.bytes.decode("utf8") == "data to be signed"
assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"
assert result.valid_sigs[0].signing_key == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"

# Verify detached signature
detached = sign(signing_key.secrets.signer(), data, mode=SignatureMode.DETACHED)
detached_sig = Sig.from_bytes(detached)
result = verify(bytes=data, store=get_certs, signature=detached_sig)
assert result.valid_sigs[0].certificate == "afcf5405e8f49dbcd5dc548a86375b854b86acf9"

# Verify detached signature against a file
import tempfile
with tempfile.NamedTemporaryFile(delete=False) as tmp:
    tmp.write(data)
    tmp.close()
    result = verify(file=tmp.name, store=get_certs, signature=detached_sig)
    assert len(result.valid_sigs) > 0
```

### Response
#### Success Response (200)
- **result** (object) - An object containing the verified content and signature information.
  - **bytes** (bytes) - The verified content as bytes.
  - **valid_sigs** (list) - A list of valid signature objects.
    - **certificate** (str) - The certificate ID of the valid signature.
    - **signing_key** (str) - The signing key ID of the valid signature.

#### Response Example
```json
{
  "result": {
    "bytes": "data to be signed",
    "valid_sigs": [
      {
        "certificate": "afcf5405e8f49dbcd5dc548a86375b854b86acf9",
        "signing_key": "afcf5405e8f49dbcd5dc548a86375b854b86acf9"
      }
    ]
  }
}
```
```

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

### List Existing User IDs - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Retrieves and lists the user IDs associated with a given PGP certificate. User IDs are accessed via the 'user_ids' attribute of a Cert object.

```python
from pysequoia import Cert

cert = Cert.from_file("wiktor.asc")
user_id = cert.user_ids[0]
assert str(user_id).startswith("Wiktor Kwapisiewicz")
```

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

### Decrypt Data and Verify Signatures (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Decrypts encrypted data and optionally verifies signatures using provided certificates. The `decryptor` is required for decryption, and the `store` function can be provided to supply certificates for signature verification. If signatures are present and valid, their details are available in `decrypted.valid_sigs`.

```python
from pysequoia import decrypt, encrypt
from pysequoia.cert import Cert

# Mocking certificates and data for demonstration:
sender = Cert.generate("Test Sender <sender@example.com>")
receiver = Cert.generate("Test Receiver <receiver@example.com>")

content = "Red Green Blue"

encrypted = encrypt(signer = sender.secrets.signer(), recipients = [receiver], bytes = content.encode("utf8"))

def get_certs(key_ids):
  print(f"For verification after decryption, we need these keys: {key_ids}")
  return [sender]

decrypted = decrypt(decryptor = receiver.secrets.decryptor("hunter22"), bytes = encrypted, store = get_certs)

assert content == decrypted.bytes.decode("utf8");

# let's check the valid signature's certificate and signing subkey fingerprints
assert decrypted.valid_sigs[0].certificate == sender.fingerprint
assert decrypted.valid_sigs[0].signing_key == sender.fingerprint
```

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

### Generate General Purpose Key - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Generates a new general-purpose PGP key with a specified user ID. The generated key can be used for both encryption and signing. Dependencies include the Cert class from pysequoia.

```python
from pysequoia import Cert

alice = Cert.generate("Alice <alice@example.com>")
fpr = alice.fingerprint
print(f"Generated cert with fingerprint {fpr}:\n{alice}")
```

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

### Verify Detached Signature Against File (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Verifies a detached signature against a file. This method is beneficial for large files as it operates directly on the file path. It requires the file path, a certificate store function, and the detached signature object. The result includes valid signatures with their certificate and signing key fingerprints.

```python
import tempfile
from pysequoia import sign, verify, Sig, SignatureMode
from pysequoia.cert import Cert

# Assuming 's' and 'get_certs' are defined elsewhere and accessible
# For demonstration purposes, let's mock them:
s = Cert.generate("Test Signer <signer@example.com>")
def get_certs(key_ids):
  print(f"For verification, need these keys: {key_ids}")
  return [Cert.generate("Test Verifier <verifier@example.com>")]

with tempfile.NamedTemporaryFile(delete=False) as tmp:
  data = "data to be signed".encode("utf8")
  detached = sign(s.secrets.signer(), data, mode=SignatureMode.DETACHED)
  detached = Sig.from_bytes(detached)

  tmp.write(data)
  tmp.close()

  # verify a detached signature against a file name
  result = verify(file=tmp.name, store=get_certs, signature=detached)

  # let's check the valid signature's certificate and signing subkey fingerprints
  assert result.valid_sigs[0].certificate == s.fingerprint
  assert result.valid_sigs[0].signing_key == s.fingerprint
```

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

### encrypt - Encrypt and optionally sign data

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Encrypts data for one or more recipients using their public keys. Optionally signs the encrypted data with a sender's private key.

```APIDOC
## encrypt - Encrypt and optionally sign data

### Description
Encrypts data for one or more recipients using their public keys. Optionally signs the encrypted data with a sender's private key.

### Method
POST (conceptual, as this is a library function, not a web API endpoint)

### Endpoint
N/A (Python library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **signer** (object, optional) - The sender's secret key, used for signing the encrypted data. Requires password if the key is protected.
- **recipients** (list of Cert) - Required - A list of recipient certificates (public keys).
- **bytes** (bytes) - Required - The data to encrypt.

### Request Example
```python
from pysequoia import Cert, encrypt

# Load sender's certificate with secret keys (for signing)
sender = Cert.from_file("passwd.pgp")

# Load recipient's certificate (for encryption)
recipient = Cert.from_bytes(open("wiktor.asc", "rb").read())

# Encrypt and sign data
content = "content to encrypt".encode("utf8")
encrypted = encrypt(
    signer=sender.secrets.signer("hunter22"),  # Password for sender's key
    recipients=[recipient],
    bytes=content
).decode("utf8")
print(f"Encrypted data: {encrypted}")

# Encrypt without signing (anonymous encryption)
receiver = Cert.from_file("passwd.pgp")
content = "Red Green Blue".encode("utf8")
encrypted = encrypt(recipients=[receiver], bytes=content)
# No signer parameter means unsigned encrypted message
```

### Response
#### Success Response (200)
- **encrypted_data** (str) - The armored OpenPGP encrypted message.

#### Response Example
```json
{
  "encrypted_data": "-----BEGIN PGP MESSAGE-----\n\n...\n-----END PGP MESSAGE-----"
}
```
```

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

### Generate Modern PGP Key (RFC9580) - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Generates a modern PGP key compliant with RFC9580 using the 'profile' parameter in the 'generate' function. Note that older PGP implementations might not support these certificates.

```python
from pysequoia import Cert, Profile

mary = Cert.generate("Modern Mary <mary@example.com", profile=Profile.RFC9580)
print(f"Generated cert with fingerprint {mary.fingerprint}:\n{mary}")
```

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

### Split Multiple PGP Certificates from Bytes (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Splits a byte buffer containing multiple concatenated PGP certificates into individual `Cert` objects. This function is useful when dealing with keyrings or files that store several certificates together. It allows iterating through and processing each certificate separately.

```python
from pysequoia.cert import Cert

cert1 = Cert.generate("Test 1 <test-1@example.com>")
cert2 = Cert.generate("Test 2 <test-2@example.com>")
cert3 = Cert.generate("Test 3 <test-3@example.com>")

buffer = bytes(cert1) + bytes(cert2) + bytes(cert3)
certs = Cert.split_bytes(buffer)
assert len(certs) == 3
```

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

### Encrypt Data to Recipients (Python)

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Encrypts data to one or more recipients using a signer for authentication. The `signer` argument is optional; omitting it results in an unsigned but encrypted message. The function returns the encrypted data as a UTF-8 decoded string. Requires recipient certificates and the data to be encrypted.

```python
from pysequoia import encrypt
from pysequoia.cert import Cert

# Assuming Cert.from_file and encrypt are available
# Mocking for demonstration:
s = Cert.generate("Test Signer <signer@example.com>")
r = Cert.generate("Test Recipient <recipient@example.com>")

content = "content to encrypt".encode("utf8")
encrypted = encrypt(signer = s.secrets.signer("hunter22"), recipients = [r], bytes = content).decode("utf8")
print(f"Encrypted data: {encrypted}")
```

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

### Merge Certificate Versions - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Merges packet data from a newer version of a certificate into an older version. This is useful for updating or combining information from different certificate states. Requires loading certificates from files.

```python
from pysequoia import Cert

old = Cert.from_file("wiktor.asc")
new = Cert.from_file("wiktor-fresh.asc")
merged = old.merge(new)
```

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

### decrypt - Decrypt encrypted data

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Decrypts OpenPGP encrypted messages using a private key. Optionally verifies signatures if the message was signed during encryption.

```APIDOC
## decrypt - Decrypt encrypted data

### Description
Decrypts OpenPGP encrypted messages using a private key. Optionally verifies signatures if the message was signed during encryption.

### Method
POST (conceptual, as this is a library function, not a web API endpoint)

### Endpoint
N/A (Python library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **encrypted_data** (str or bytes) - Required - The armored OpenPGP encrypted message.
- **recipient_key** (Cert) - Required - The recipient's certificate (private key) to decrypt the message.

### Request Example
```python
from pysequoia import Cert, encrypt, decrypt

sender = Cert.from_file("no-passwd.pgp")
receiver = Cert.from_file("passwd.pgp")

# Encrypt data
content = "Red Green Blue"
encrypted = encrypt(recipients=[receiver], bytes=content.encode("utf8"))

# Decrypt the message
decrypted_content = decrypt(encrypted, receiver)
print(f"Decrypted content: {decrypted_content.decode('utf8')}")
```

### Response
#### Success Response (200)
- **decrypted_data** (bytes) - The decrypted content as bytes.

#### Response Example
```json
{
  "decrypted_data": "Red Green Blue"
}
```
```

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

### Add User IDs to Certificates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Explains how to add new user IDs to an existing certificate using `Cert.add_user_id`. This function creates a self-signature to bind the new user ID to the certificate.

```python
from pysequoia import Cert

cert = Cert.generate("Alice <alice@example.com>")
assert len(cert.user_ids) == 1

# Add a second user ID
cert = cert.add_user_id(
    value="Alice <alice@company.invalid>",
    certifier=cert.secrets.certifier()
)
assert len(cert.user_ids) == 2

# Print all user IDs
for user_id in cert.user_ids:
    print(f"User ID: {user_id}")
```

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

### Add New User ID to Certificate - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Adds a new user ID to an existing PGP certificate. This operation requires a certifier secret key to sign the addition. The function 'add_user_id' is used, and the number of user IDs is asserted before and after.

```python
from pysequoia import Cert

cert = Cert.generate("Alice <alice@example.com>")
assert len(cert.user_ids) == 1;

cert = cert.add_user_id(value = "Alice <alice@company.invalid>", certifier = cert.secrets.certifier())

assert len(cert.user_ids) == 2;
```

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

### Set PGP Key Expiration Time - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Sets or adjusts the expiration time for a PGP key. This requires a certifier secret key to sign the change. The 'set_expiration' method takes a datetime object and returns the updated certificate.

```python
from datetime import datetime
from pysequoia import Cert

cert = Cert.from_file("signing-key.asc")

# Cert does not have any expiration date:
assert cert.expiration is None

# Set the expiration to some specified point in time
expiration = datetime.fromisoformat("2021-11-04T00:05:23+00:00")
cert = cert.set_expiration(expiration = expiration, certifier = cert.secrets.certifier())
assert str(cert.expiration) == "2021-11-04 00:05:23+00:00"
```

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

### Revoke User IDs from Certificates with pysequoia

Source: https://context7.com/wiktor-k/pysequoia/llms.txt

Details the process of revoking user IDs from a certificate using `Cert.revoke_user_id`. It involves creating a revocation signature and merging it back into the certificate.

```python
from pysequoia import Cert

cert = Cert.generate("Bob <bob@example.com>")
cert = cert.add_user_id(
    value="Bob <bob@company.invalid>",
    certifier=cert.secrets.certifier()
)
assert len(cert.user_ids) == 2

# Create user ID revocation
revocation = cert.revoke_user_id(
    user_id=cert.user_ids[1],
    certifier=cert.secrets.certifier()
)

# Merge revocation with certificate
cert = Cert.from_bytes(bytes(cert) + bytes(revocation))
assert len(cert.user_ids) == 1  # Revoked user ID no longer visible
```

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

### Revoke User ID from Certificate - Python

Source: https://github.com/wiktor-k/pysequoia/blob/main/README.md

Revokes a specific user ID from a PGP certificate. This involves creating a revocation signature for the user ID and then merging this revocation back into the certificate. The user ID count is checked before and after.

```python
from pysequoia import Cert

cert = Cert.generate("Bob <bob@example.com>")

cert = cert.add_user_id(value = "Bob <bob@company.invalid>", certifier = cert.secrets.certifier())
assert len(cert.user_ids) == 2

# create User ID revocation
revocation = cert.revoke_user_id(user_id = cert.user_ids[1], certifier = cert.secrets.certifier())

# merge the revocation with the cert
cert = Cert.from_bytes(bytes(cert) + bytes(revocation))
assert len(cert.user_ids) == 1
```
Tokens:
Raw