# python-cert_manager
This library provides a [Python][1] interface to the [Sectigo][2] Certificate Manager REST API. python-cert_manager is open sourced under the [BSD 3-Clause license](LICENSE.txt).
## Basics
`cert_manager` runs on [Python][1] >= 3.7
## Features
There are many API endpoints under Certificate Manager, and this library currently supports a subset of those endpoints. The current list of written and tested endpoint classes includes:
* Organization (/organization)
* Person (/person)
* SSL (/ssl)
* Client Administrator (/admin)
* Domain (/domain)
* Report (/report)
Other endpoints we hope to add in the near future:
* Code Signing Certificates (/csod)
* Custom Fields (/customField)
* Domain Control Validation (/dcv)
* Device Certificates (/device)
* Discovery (/discovery)
* SMIME (/smime)
## Installing
You can use pip to install cert_manager:
```sh
pip install cert_manager
```
## Examples
This is a simple example that just shows initializing the `Client` object and using it to query the `Organization` and `SSL` endpoints:
```python
from cert_manager import Organization
from cert_manager import Client
from cert_manager import SSL
client = Client(
base_url="https://cert-manager.com/api",
login_uri="SomeOrg",
username="your_username",
password="your_password",
)
org = Organization(client=client)
ssl = SSL(client=client)
print(ssl.types)
print(org.all())
```
The most common process you would do, however, is enroll and then collect a certificate you want to order from the Certificate Manager:
```python
from time import sleep
from cert_manager import Organization
from cert_manager import Client
from cert_manager import SSL
client = Client(
base_url="https://cert-manager.com/api",
login_uri="SomeOrg",
username="your_username",
password="your_password",
)
# We need to enroll the certificate under an organization, so we will need to query the API for that
org = Organization(client=client)
# We need the SSL module to enroll the certificate
ssl = SSL(client=client)
cert_org = org.find(dept_name="MyDept")
with open("host.csr", "r") as filep:
csr = filep.read()
result = ssl.enroll(cert_type_name="InCommon SSL (SHA-2)", csr=csr, term=365, org_id=cert_org[0]["id"])
# This is just for demonstration purposes.
# Doing a wait loop like this to poll for the certificate is not the best way to go about this.
while(True):
# Collect the certificate from Sectigo
try:
cert_pem = ssl.collect(cert_id=result["sslId"], cert_format="x509CO")
print(cert_pem)
break
except PendingError:
print("Certificate is still pending...sleeping for 60s")
sleep(60)
continue
except Exception:
# For some unexpected exception, exit
break
```
## Contributing
Pull requests to add functionality and fix bugs are always welcome. Please check the CONTRIBUTING.md for specifics on contributions.
### Testing
We try to have a high level of test coverage on the code. Therefore, when adding anything to the repo, tests should be written to test a new feature or to test a bug fix so that there won't be a regression. This library is setup to be pretty simple to build a working development environment using [Docker][4]. Therefore, it is suggested that you have [Docker][4] installed where you clone this repository to make development easier.
To start a development environment, you should be able to just run the `dev.sh` script. This script will use the `Dockerfile` in this repository to build a [Docker][4] container with all the dependencies for development installed using [Pipenv][3].
```sh
./dev.sh
```
The first time you run the script, it should build the [Docker][4] image and then drop you into the container's shell. The directory where you cloned this repository should be volume mounted in to `/usr/src`, which should also be the current working directory. From there, you can make changes as you see fit. Tests can be run from the `/usr/src` directory by simply typing `green` as [green][5] has been setup to with the correct parameters.
## Changelog
To generate the `CHANGELOG.md`, you will need [Docker][4] and a GitHub personal access token. We currently use [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator) for this purpose. The following should generate the file using information from GitHub:
```sh
docker run -it --rm \
-e CHANGELOG_GITHUB_TOKEN='yourtokenhere' \
-v "$(pwd)":/working \
-w /working \
ferrarimarco/github-changelog-generator --verbose
```
To generate the log for an upcoming release that has not yet been tagged, you can run a command to include the upcoming release version. For example, `2.0.0`:
```sh
docker run -it --rm \
-e CHANGELOG_GITHUB_TOKEN='yourtokenhere' \
-v "$(pwd)":/working \
-w /working \
ferrarimarco/github-changelog-generator --verbose --future-release 2.0.0 --unreleased
```
As a note, this repository uses the default labels for formatting the `CHANGELOG.md`. Label information can be found here: [Advanced-change-log-generation-examples](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Advanced-change-log-generation-examples#section-options)
## Releases
Releases to the codebase are typically done using the [bump2version][6] tool. This tool takes care of updating the version in all necessary files, updating its own configuration, and making a GitHub commit and tag. We typically do version bumps as part of a PR, so you don't want to have [bump2version][6] tag the version at the same time it does the commit as commit hashes may change. Therefore, to bump the version a patch level, one would run the command:
```sh
bump2version --verbose --no-tag patch
```
Once the PR is merged, you can then checkout the new `main` branch and tag it using the new version number that is now in `.bumpversion.cfg`:
```sh
git checkout main
git pull --rebase
git tag 1.0.0 -m 'Bump version: 0.1.0 → 1.0.0'
git push --tags
```
[1]: https://www.python.org/ "Python"
[2]: https://sectigo.com/ "Sectigo"
[3]: https://pipenv.readthedocs.io/en/latest/ "Pipenv"
[4]: https://www.docker.com/ "Docker"
[5]: https://github.com/CleanCut/green "green"
[6]: https://pypi.org/project/bump2version/ "bump2version"
Raw data
{
"_id": null,
"home_page": "https://github.com/broadinstitute/python-cert_manager.git",
"name": "cert_manager",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "sectigo,comodo,certificate",
"author": "Andrew Teixeira",
"author_email": "teixeira@broadinstitute.org",
"download_url": "https://files.pythonhosted.org/packages/38/22/cfcdeeb05c6d7d1139a6ee7f4c8735ee13f546b2b12eb9d8afafd845ebdb/cert_manager-2.4.0.tar.gz",
"platform": null,
"description": "# python-cert_manager\n\nThis library provides a [Python][1] interface to the [Sectigo][2] Certificate Manager REST API. python-cert_manager is open sourced under the [BSD 3-Clause license](LICENSE.txt).\n\n\n\n## Basics\n\n`cert_manager` runs on [Python][1] >= 3.7\n\n## Features\n\nThere are many API endpoints under Certificate Manager, and this library currently supports a subset of those endpoints. The current list of written and tested endpoint classes includes:\n\n* Organization (/organization)\n* Person (/person)\n* SSL (/ssl)\n* Client Administrator (/admin)\n* Domain (/domain)\n* Report (/report)\n\nOther endpoints we hope to add in the near future:\n\n* Code Signing Certificates (/csod)\n* Custom Fields (/customField)\n* Domain Control Validation (/dcv)\n* Device Certificates (/device)\n* Discovery (/discovery)\n* SMIME (/smime)\n\n## Installing\n\nYou can use pip to install cert_manager:\n\n```sh\npip install cert_manager\n```\n\n## Examples\n\nThis is a simple example that just shows initializing the `Client` object and using it to query the `Organization` and `SSL` endpoints:\n\n```python\nfrom cert_manager import Organization\nfrom cert_manager import Client\nfrom cert_manager import SSL\n\nclient = Client(\n base_url=\"https://cert-manager.com/api\",\n login_uri=\"SomeOrg\",\n username=\"your_username\",\n password=\"your_password\",\n)\n\norg = Organization(client=client)\nssl = SSL(client=client)\n\nprint(ssl.types)\nprint(org.all())\n```\n\nThe most common process you would do, however, is enroll and then collect a certificate you want to order from the Certificate Manager:\n\n```python\nfrom time import sleep\n\nfrom cert_manager import Organization\nfrom cert_manager import Client\nfrom cert_manager import SSL\n\nclient = Client(\n base_url=\"https://cert-manager.com/api\",\n login_uri=\"SomeOrg\",\n username=\"your_username\",\n password=\"your_password\",\n)\n\n# We need to enroll the certificate under an organization, so we will need to query the API for that\norg = Organization(client=client)\n# We need the SSL module to enroll the certificate\nssl = SSL(client=client)\n\ncert_org = org.find(dept_name=\"MyDept\")\nwith open(\"host.csr\", \"r\") as filep:\n csr = filep.read()\n\nresult = ssl.enroll(cert_type_name=\"InCommon SSL (SHA-2)\", csr=csr, term=365, org_id=cert_org[0][\"id\"])\n\n# This is just for demonstration purposes.\n# Doing a wait loop like this to poll for the certificate is not the best way to go about this.\nwhile(True):\n # Collect the certificate from Sectigo\n try:\n cert_pem = ssl.collect(cert_id=result[\"sslId\"], cert_format=\"x509CO\")\n print(cert_pem)\n break\n except PendingError:\n print(\"Certificate is still pending...sleeping for 60s\")\n sleep(60)\n continue\n except Exception:\n # For some unexpected exception, exit\n break\n```\n\n## Contributing\n\nPull requests to add functionality and fix bugs are always welcome. Please check the CONTRIBUTING.md for specifics on contributions.\n\n### Testing\n\nWe try to have a high level of test coverage on the code. Therefore, when adding anything to the repo, tests should be written to test a new feature or to test a bug fix so that there won't be a regression. This library is setup to be pretty simple to build a working development environment using [Docker][4]. Therefore, it is suggested that you have [Docker][4] installed where you clone this repository to make development easier.\n\nTo start a development environment, you should be able to just run the `dev.sh` script. This script will use the `Dockerfile` in this repository to build a [Docker][4] container with all the dependencies for development installed using [Pipenv][3].\n\n```sh\n./dev.sh\n```\n\nThe first time you run the script, it should build the [Docker][4] image and then drop you into the container's shell. The directory where you cloned this repository should be volume mounted in to `/usr/src`, which should also be the current working directory. From there, you can make changes as you see fit. Tests can be run from the `/usr/src` directory by simply typing `green` as [green][5] has been setup to with the correct parameters.\n\n## Changelog\n\nTo generate the `CHANGELOG.md`, you will need [Docker][4] and a GitHub personal access token. We currently use [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator) for this purpose. The following should generate the file using information from GitHub:\n\n```sh\ndocker run -it --rm \\\n -e CHANGELOG_GITHUB_TOKEN='yourtokenhere' \\\n -v \"$(pwd)\":/working \\\n -w /working \\\n ferrarimarco/github-changelog-generator --verbose\n```\n\nTo generate the log for an upcoming release that has not yet been tagged, you can run a command to include the upcoming release version. For example, `2.0.0`:\n\n```sh\ndocker run -it --rm \\\n -e CHANGELOG_GITHUB_TOKEN='yourtokenhere' \\\n -v \"$(pwd)\":/working \\\n -w /working \\\n ferrarimarco/github-changelog-generator --verbose --future-release 2.0.0 --unreleased\n```\n\nAs a note, this repository uses the default labels for formatting the `CHANGELOG.md`. Label information can be found here: [Advanced-change-log-generation-examples](https://github.com/github-changelog-generator/github-changelog-generator/wiki/Advanced-change-log-generation-examples#section-options)\n\n## Releases\n\nReleases to the codebase are typically done using the [bump2version][6] tool. This tool takes care of updating the version in all necessary files, updating its own configuration, and making a GitHub commit and tag. We typically do version bumps as part of a PR, so you don't want to have [bump2version][6] tag the version at the same time it does the commit as commit hashes may change. Therefore, to bump the version a patch level, one would run the command:\n\n```sh\nbump2version --verbose --no-tag patch\n```\n\nOnce the PR is merged, you can then checkout the new `main` branch and tag it using the new version number that is now in `.bumpversion.cfg`:\n\n```sh\ngit checkout main\ngit pull --rebase\ngit tag 1.0.0 -m 'Bump version: 0.1.0 \u2192 1.0.0'\ngit push --tags\n```\n\n[1]: https://www.python.org/ \"Python\"\n[2]: https://sectigo.com/ \"Sectigo\"\n[3]: https://pipenv.readthedocs.io/en/latest/ \"Pipenv\"\n[4]: https://www.docker.com/ \"Docker\"\n[5]: https://github.com/CleanCut/green \"green\"\n[6]: https://pypi.org/project/bump2version/ \"bump2version\"\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python interface to the Sectigo Certificate Manager REST API",
"version": "2.4.0",
"project_urls": {
"Homepage": "https://github.com/broadinstitute/python-cert_manager.git",
"Repository": "https://github.com/broadinstitute/python-cert_manager.git"
},
"split_keywords": [
"sectigo",
"comodo",
"certificate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60b8360d9a864812ba673ca93e4ce24d1937f0d485078834f832260d9ef67887",
"md5": "ccc4dd9ec4788118ddf2fb60e4958ae8",
"sha256": "2ff51e21b46d552476b0aa9d3e08af0b5d6f6bd42d96f91b096c7a742e384618"
},
"downloads": -1,
"filename": "cert_manager-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccc4dd9ec4788118ddf2fb60e4958ae8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 28252,
"upload_time": "2024-01-29T17:27:35",
"upload_time_iso_8601": "2024-01-29T17:27:35.825278Z",
"url": "https://files.pythonhosted.org/packages/60/b8/360d9a864812ba673ca93e4ce24d1937f0d485078834f832260d9ef67887/cert_manager-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3822cfcdeeb05c6d7d1139a6ee7f4c8735ee13f546b2b12eb9d8afafd845ebdb",
"md5": "06e728714762349b9f4edca17e17f779",
"sha256": "260c54be2525487b99ea7dbaac368054a875fb5ed86e5119e781efbb1f2717bf"
},
"downloads": -1,
"filename": "cert_manager-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "06e728714762349b9f4edca17e17f779",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 21513,
"upload_time": "2024-01-29T17:27:37",
"upload_time_iso_8601": "2024-01-29T17:27:37.699582Z",
"url": "https://files.pythonhosted.org/packages/38/22/cfcdeeb05c6d7d1139a6ee7f4c8735ee13f546b2b12eb9d8afafd845ebdb/cert_manager-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-29 17:27:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "broadinstitute",
"github_project": "python-cert_manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cert_manager"
}
JSON
