cryptography-project 0.2.0
A secure-by-default cryptography framework with HSM support
License: Apache-2.0
Requires Python: >=3.8

# Cryptography Project

A secure-by-default cryptography framework with HSM support for Python applications.

## Features

- **Symmetric Encryption**: AES-256-GCM with automatic nonce generation
- **Asymmetric Cryptography**:
  - Ed25519 for digital signatures
  - X25519 for key exchange
  - ECDSA (P-256) for digital signatures
- **Key Derivation**:
  - PBKDF2-HMAC
  - Scrypt
  - HKDF
- **HSM Integration**:
  - PKCS#11 support (e.g., SoftHSM2, Thales, YubiHSM)
  - Secure key storage and operations
  - In-memory backend for testing

## Installation

### Prerequisites

- Python 3.8+
- For HSM support: PKCS#11 library (e.g., [SoftHSM2](https://www.opendnssec.org/softhsm/))

### Install from PyPI

```bash
pip install cryptography-project
```

### Install with HSM Support

```bash
pip install "cryptography-project[hsm]"
```

### Install from Source

```bash
git clone https://github.com/yourusername/cryptography-project.git
cd cryptography-project
pip install -e .[dev,hsm]
```

## Quick Start

### Basic Usage

```python
from cryptography_project import (
    encrypt_aes_gcm,
    decrypt_aes_gcm,
    generate_ed25519_keypair,
    ed25519_sign,
    ed25519_verify,
    pbkdf2_hmac_derive
)

# Symmetric encryption
key = os.urandom(32)
nonce, ciphertext, tag = encrypt_aes_gcm(b"secret message", key)
plaintext = decrypt_aes_gcm(ciphertext, key, nonce, tag)

# Digital signatures
private_key, public_key = generate_ed25519_keypair()
signature = ed25519_sign(private_key, b"message to sign")
valid = ed25519_verify(public_key, signature, b"message to sign")

# Key derivation
key, salt = pbkdf2_hmac_derive("password", salt=os.urandom(16))
```

### HSM Integration

```python
from cryptography_project.hsm import PKCS11KeyStore

# Initialize with your HSM configuration
with PKCS11KeyStore(
    library_path="/path/to/libsofthsm2.so",
    token_label="my_token",
    pin="1234"
) as keystore:
    # Generate a key in the HSM
    key_id = keystore.generate_key("my_key", key_type="AES-256")
    
    # Encrypt/decrypt using the HSM key
    nonce, ciphertext, tag = keystore.encrypt(key_id, b"sensitive data")
    plaintext = keystore.decrypt(key_id, nonce, ciphertext, tag)
```

## Documentation

Full documentation is available at [https://yourusername.github.io/cryptography-project/](https://yourusername.github.io/cryptography-project/)

## Development

### Setup Development Environment

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/cryptography-project.git
   cd cryptography-project
   ```

2. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```

3. Install pre-commit hooks:
   ```bash
   pre-commit install
   ```

### Running Tests

```bash
# Run all tests
pytest

# Run tests with coverage
pytest --cov=cryptography_project --cov-report=html

# Run only unit tests
pytest tests/unit

# Run HSM integration tests (requires SoftHSM2)
pytest tests/integration/test_hsm.py -v
```

### Code Style

This project uses:
- `black` for code formatting
- `isort` for import sorting
- `mypy` for static type checking
- `pylint` for code quality

Run all code style checks:
```bash
pre-commit run --all-files
```

## Security

### Reporting Security Issues

Please report security issues to security@example.com. We take security issues seriously and will respond promptly.

### Security Considerations

- Always use the latest version of the library
- Store cryptographic keys securely (preferably in an HSM)
- Use strong, unique passwords for key derivation
- Keep your system's cryptographic libraries up to date

## License

Apache-2.0 License. See [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details.

## Acknowledgements

- Built on top of the excellent [cryptography](https://cryptography.io/) library
- Inspired by [PyKCS11](https://pypi.org/project/PyKCS11/) and [python-pkcs11](https://python-pkcs11.readthedocs.io/)

---

<p align="center">
  <a href="https://github.com/yourusername/cryptography-project/actions">
    <img src="https://github.com/yourusername/cryptography-project/actions/workflows/ci.yml/badge.svg" alt="CI Status">
  </a>
  <a href="https://codecov.io/gh/yourusername/cryptography-project">
    <img src="https://codecov.io/gh/yourusername/cryptography-project/branch/main/graph/badge.svg" alt="Code Coverage">
  </a>
  <a href="https://pypi.org/project/cryptography-project/">
    <img src="https://img.shields.io/pypi/v/cryptography-project.svg" alt="PyPI Version">
  </a>
  <a href="https://github.com/psf/black">
    <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">
  </a>
</p>