Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

possible alternate for readme layout #98

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 138 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,66 +1,145 @@
# OwnCA - Python Certificate Authority Management

[![Build Status](https://github.com/OwnCA/ownca/workflows/Tests/badge.svg)](https://github.com/OwnCA/ownca/actions?query=workflow%3ATests)
[![Documentation Status](https://readthedocs.org/projects/ownca/badge/?version=latest)](https://ownca.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/OwnCA/ownca/branch/master/graph/badge.svg)](https://codecov.io/gh/OwnCA/ownca)
[![pypi](https://img.shields.io/pypi/v/ownca.svg)](https://pypi.python.org/pypi/ownca)
[![pypi Downloads](https://img.shields.io/pypi/dm/ownca)](https://pypistats.org/packages/ownca)
[![pypi](https://img.shields.io/pypi/l/ownca.svg)](https://pypi.python.org/pypi/ownca)
[![PyPI Version](https://img.shields.io/pypi/v/ownca.svg)](https://pypi.python.org/pypi/ownca)
[![PyPI Downloads](https://img.shields.io/pypi/dm/ownca)](https://pypistats.org/packages/ownca)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

### THIS PROJECT IS OPEN FOR MAINTAINERS

> Development on the OwnCA projects has been stagnated for a while
> For that reason, I'm opening the organization to new maintainers who will have the proper permissions to unstuck development.
> Development on the OwnCA project has stagnated for a while.
> For that reason, I'm opening the organization to new maintainers who will have the proper permissions to jumpstart development.
>
> Those willing to join, contact me by email with the subject [OwnCA Maintainer] <your name> and please let me know what
> motivates you to join in such role.
> Those willing to join, contact me by email with the subject `[OwnCA Maintainer] <your name>` and please let me know what
> motivates you to join in such a role.

Python Own Certificate Authority (OwnCA)
========================================
---

OwnCA makes it easy to handle a Certificate Authority (CA) and manage certificates
for hosts, servers or clients.
OwnCA is a Python library that simplifies the creation, management, and distribution of digital certificates. It acts as a full Certificate Authority (CA) for managing all your certificates and can automate the process of generating secure SSL/TLS certificates for servers and clients.

An example of high-level usage:
## Features

```pycon
>>> from ownca import CertificateAuthority
>>> ca = CertificateAuthority(ca_storage='/opt/CA', common_name='Corp CA')
>>> example_com = ca.issue_certificate('www.example.com', dns_names=['www.example.com', 'w3.example.com'])
```
- Create and manage your own Certificate Authority (CA)
- Issue and revoke certificates for servers and clients
- Automatically sign certificate requests (CSRs)
- Easy-to-use Python API for automating certificate creation

Basically, in these three lines we:
1. Imported the ownca Certificate Authority library
2. Created a new CA named *Corp CA* that uses ```/opt/CA``` as CA storage
for certificates, keys, etc.
3. Created a signed certificate by *Corp CA* for *www.example.com*,
whose files are also stored in ```/opt/CA/certs/www.example.com```
## Table of Contents

```pycon
>>> example_com.cert
<Certificate(subject=<Name(CN=www.example.com)>, ...)>
```
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Creating a Certificate Authority](#creating-a-certificate-authority)
- [Generating Server Certificates](#generating-server-certificates)
- [Generating Client Certificates](#generating-client-certificates)
- [Revoking Certificates](#revoking-certificates)
- [Configuration](#configuration)
- [Development](#development)
- [Preparing the Environment](#preparing-the-environment)
- [Installing & Enabling Pre-commit](#installing--enabling-pre-commit)
- [Contributing](#contributing)
- [License](#license)

More detailed usage can be found in [http://ownca.readthedocs.org](
http://ownca.readthedocs.org).
## Installation

### Prerequisites

Installation
============
- Python 3.6 or higher
- `cryptography` library (used for cryptographic functions)

```shell
```bash
pip install ownca
```

Documentation
=============
Visit [http://ownca.readthedocs.org](http://ownca.readthedocs.org)
## Quick Start

### Creating a Certificate Authority

To initialize a Certificate Authority (CA), you need to specify a storage path and a common name (CN) for your CA. The `CertificateAuthority` class handles the generation of CA keys and certificates.

```python
from ownca import CertificateAuthority

# Initialize the CA
ca = CertificateAuthority(
ca_storage="/etc/my-ca",
common_name="my-ca",
maximum_days=365 # Valid for one year
)
print("CA has been created.")
```

This will generate a CA certificate and private key, which will be used to sign certificates for your servers and clients.

### Generating Server Certificates

For each server in your service that needs SSL/TLS certificates, you can issue a server certificate as follows:

```python
nodes = ["server1", "server2", "server3"]

for node in nodes:
ca.issue_certificate(
hostname=node,
common_name=f"{node}.example.com", # Adjust with your actual domain
dns_names=[f"{node}.example.com"],
maximum_days=365
)
print(f"Certificate for {node} issued.")
```

Each server will have its own certificate stored in `/etc/my-ca/certs/`.

### Generating Client Certificates

Client certificates are needed for secure client-server communication. Here’s how you can generate client certificates:

```python
client_common_name = "my-client"
ca.issue_certificate(
hostname=client_common_name,
common_name=client_common_name,
dns_names=[client_common_name],
maximum_days=180 # Valid for 6 months
)
print("Client certificate has been issued.")
```

### Revoking Certificates

In case you need to revoke a certificate (e.g., a server has been decommissioned), use the following:

```python
ca.revoke_certificate("server1")
print("Certificate for server1 has been revoked.")
```

## Configuration

- **Certificate Authority Storage**: All certificates and keys are stored in the directory specified in the `ca_storage` parameter.
- **Maximum Certificate Validity**: The `maximum_days` parameter determines how long certificates are valid (e.g., 365 days for one year).
- **DNS Names**: Ensure to pass appropriate DNS names while issuing certificates to secure multiple domains.

Example directory structure:

```
/etc/my-ca/
├── certs/
│ ├── server1/
│ │ ├── server1.crt
│ │ ├── server1.pem
│ │ └── server1.pub
├── ca.crt
├── ca_key.pem
└── ca_key.pub
```

Development
===========
## Development

Preparing the environment
-------------------------
### Preparing the Environment

```shell
git clone [email protected]:OwnCA/ownca.git
Expand All @@ -76,11 +155,28 @@ pip uninstall cryptography cffi
LDFLAGS=-L$(brew --prefix libffi)/lib CFLAGS=-I$(brew --prefix libffi)/include pip install cffi cryptography rust --no-binary :all:
```

Installing & enabling pre-commit
--------------------------------
### Installing & Enabling Pre-commit

To automatically run checks before you commit your changes, you should install the git hook scripts with **pre-commit**:

To automatically run checks before you commit your changes you should install the git hook scripts with **pre-commit**:
```shell
pre-commit install
pre-commit autoupdate
```

## Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

To contribute:

1. Fork this repository
2. Create a new branch
3. Commit your changes
4. Submit a pull request

For major changes, please open an issue first to discuss what you would like to change.

## License

This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.