From 47afedd4984e3064c9ef9f159b5856cd5097e187 Mon Sep 17 00:00:00 2001 From: marckeelingiv <32782256+marckeelingiv@users.noreply.github.com> Date: Wed, 2 Oct 2024 21:26:14 +0000 Subject: [PATCH 1/2] possible alternate for readme layout --- REACME_alt.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 REACME_alt.md diff --git a/REACME_alt.md b/REACME_alt.md new file mode 100644 index 0000000..453441c --- /dev/null +++ b/REACME_alt.md @@ -0,0 +1,130 @@ +# OwnCA - Python Certificate Authority Management + +[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) + +OwnCA is a Python library that simplifies the creation, management, and distribution of digital certificates. It can act as a full Certificate Authority (CA) for managing all your certificates. OwnCA can automatee the process of generating secure SSL/TLS certificates for servers and clients. + +## Features +- 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 + +## Table of Contents +- [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) +- [Configuration](#configuration) +- [Contributing](#contributing) +- [License](#license) + +## Installation + +### Prerequisites +- Python 3.6 or higher +- `cryptography` library (used for cryptographic functions) + +```bash +pip install ownca +``` + +## 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 +``` + +## 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. + From ac50b7ab6ae183a557e4411e59b8da5a70b89443 Mon Sep 17 00:00:00 2001 From: marckeelingiv <32782256+marckeelingiv@users.noreply.github.com> Date: Thu, 3 Oct 2024 15:23:36 +0000 Subject: [PATCH 2/2] Re-formatted --- REACME_alt.md | 130 ------------------------------------ README.md | 180 ++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 138 insertions(+), 172 deletions(-) delete mode 100644 REACME_alt.md diff --git a/REACME_alt.md b/REACME_alt.md deleted file mode 100644 index 453441c..0000000 --- a/REACME_alt.md +++ /dev/null @@ -1,130 +0,0 @@ -# OwnCA - Python Certificate Authority Management - -[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) - -OwnCA is a Python library that simplifies the creation, management, and distribution of digital certificates. It can act as a full Certificate Authority (CA) for managing all your certificates. OwnCA can automatee the process of generating secure SSL/TLS certificates for servers and clients. - -## Features -- 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 - -## Table of Contents -- [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) -- [Configuration](#configuration) -- [Contributing](#contributing) -- [License](#license) - -## Installation - -### Prerequisites -- Python 3.6 or higher -- `cryptography` library (used for cryptographic functions) - -```bash -pip install ownca -``` - -## 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 -``` - -## 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. - diff --git a/README.md b/README.md index 08c4436..fb4609d 100644 --- a/README.md +++ b/README.md @@ -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] 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] ` 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 - , ...)> - ``` +- [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 git@github.com:OwnCA/ownca.git @@ -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. \ No newline at end of file