{ "info": { "author": "jaddison", "author_email": "addi00+github.com@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Environment :: Web Environment", "Intended Audience :: Developers", "Intended Audience :: Information Technology", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Topic :: Internet :: WWW/HTTP", "Topic :: Security" ], "description": "certbot\\_py Documentation\n-------------------------\n\nCurrent Status: Very Alpha, Proof of Concept\n''''''''''''''''''''''''''''''''''''''''''''\n\nUse at your own peril, until there's some shakedown.\n\nOverview\n^^^^^^^^\n\nThis library is a wrapper around the ``certbot``/``certbot-auto``\ncommand line tool operating ``certonly`` in manual, non-interactive\nmode. It does this via Python's ``subprocess.Popen()``.\n\nThis allows Python developers to automate the creation of certificates\nin a web app (ie. Flask or Django). Let's Encrypt's certificate\ngeneration process, simplified:\n\n1. ``certbot`` sends a certificate request for a domain (or multiple\n domains in the case of SAN/UCC)\n2. Let's Encrypt responds with validation instructions for each\n requested domain\n3. For each set of validation instructions, << developer/operations team\n member needs to manually perform some action - DNS record addition or\n web server file creation >>\n4. Let's Encrypt attempts to validate each domain\n5. Upon successful validation, a certificate is provided (either single\n domain or SAN/UCC)\n\nStep 3 is where this library allows the developer to customize and\n**automate** their process of setting up validation (see ``auth_script``\nbelow). This library currently only supports web server validation (ie\nhttp-01).\n\nAn example scenario where this library becomes useful: > You have a\nblogging platform (ie. blog-platform.io) where your customers can sign\nup and create their own blog (ie. customer1.blog-platform.io). > >The\nCustomer would like to host their new blog on their own sub-domain (ie.\nblog.customer-site.com) for SEO purposes - obviously they want to make\nsure it's HTTPS enabled. They can easily do this by adding a CNAME from\nblog.customer-site.com to customer1.blog-platform.io. > > So your\nblogging platform needs to automatically provision HTTPS certificates as\nyour customers create new blogs and set up CNAMEs for them.\n``certbot_py`` to the rescue.\n\nPlease note that there is **NO** mechanism for renewal included; `using\n``certbot renew`` via a cron job is the recommended\nway `__.\n\nInstallation\n^^^^^^^^^^^^\n\n1. You must install ``certbot`` or ``certbot-auto`` as you will need to\n specify the full path to it. It does all the heavy lifting.\n2. The user running your Python project code must have access to run\n ``sudo certbot`` or ``sudo certbot-auto`` without a password, which\n is largely dependent on how you configure your ``gunicorn``,\n ``uwsgi``, etc to run (if in a web environment).\n\n - This likely means running ``sudo visudo`` or adding an entry to\n ``/etc/sudoers.d/``.\n - **For security, it is highly recommended to only allow ``sudo``\n access to just the one command (``certbot`` or\n ``certbot-auto``).**\n\n3. Register an account with Let's Encrypt's servers (if you haven't\n already). Note that ``certbot_py`` (this library) defaults to using\n Let's Encrypt staging servers, while ``certbot`` and ``certbot-auto``\n default to production servers. An example of registration for staging\n servers:\n ``certbot register --staging # OR certbot-auto register --staging``\n4. In your Python project's virtual environment, install ``certbot_py``:\n ``pip install certbot_py``\n\nUsage\n^^^^^\n\nEnsure you register an account with Let's Encrypt, as mentioned above.\n\nThere is a single ``generate_certificate`` method which requires 3\nparameters: ``domains``, ``certbot_command``, and ``auth_script``. There\nare many other optional parameters which mostly map to corresponding\n``certbot`` arguments.\n\n::\n\n from certbot_py import client\n\n command = '/my/path/to/certbot'\n script = '/my/other/path/to/auth-hook-script.sh'\n my_domains = ['example1.com', 'example2.com', 'example3.com']\n results = client.generate_certificate(\n domains=my_domains,\n certbot_command=command,\n auth_script=script\n )\n\nIf you wanted to generate a SAN (ie. UCC) certificate instead, use\n``san_ucc=True``. As with ``certbot``, the first domain in ``domains``\nwill be the common name listed on the resulting cert.\n\n::\n\n results = client.generate_certificate(\n domains=my_domains,\n certbot_command=command,\n auth_script=script,\n san_ucc=True\n )\n\nThere are many more options, most of the pertinent ones are listed\nbelow. Skip further down for more information on ``auth_script``.\n\nOption List\n'''''''''''\n\nFull list of ``generate_certificate`` parameters (order is unimportant\nas they must be passed as keyword arguments):\n\n::\n\n account = None\n allow_domain_subset = False\n allow_self_upgrade = False\n auth_script = None\n certbot_command = None\n domains = None\n hsts = False\n must_staple = False\n production = False\n redirect = False\n rsa_key_size = None\n san_ucc = False\n staple_ocsp = False\n uir = False\n\nThese mostly map to `corresponding ``certbot``\narguments `__,\nwith a few exceptions:\n\n- ``production`` will enable the live generation of certificates from\n Let's Encrypt's production servers. By default (and safely),\n ``certbot_py`` uses staging servers.\n- ``san_ucc`` indicates that a SAN/UCC certificate is wanted, otherwise\n an individual cert will be requested for each domain passed in.\n- ``certbot_command`` is the full path the the installed ``certbot`` or\n ``certbot-auto`` command line executable.\n- ``auth_script`` is the full path to a script which will use the\n ``certbot``-provided ``$CERTBOT_DOMAIN``, ``$CERTBOT_VALIDATION``,\n and ``$CERTBOT_TOKEN`` environment variables to perform some\n developer-specific action (ie. add ``$CERTBOT_VALIDATION`` and\n ``$CERTBOT_TOKEN`` to a database) so that the subsequent validation\n request from Let's Encrypt's servers can succeed.\n- ``allow_self_upgrade`` would allow auto-upgrading (``certbot-auto``\n only), which has been disabled by default to prevent breakage due to\n tool upgrades\n\nExample ``auth_script`` (Django example), just a single bash script:\n\n::\n\n #~/bin/bash\n /home/webuser/.virtualenvs/bin/python /home/webuser/my_project/manage.py set_domain_validation \"$CERTBOT_DOMAIN\" \"$CERTBOT_VALIDATION\" \"$CERTBOT_TOKEN\"\n\nCommand Line\n''''''''''''\n\nThere is a command line alias configured upon ``pip install`` that you\ncan use to test with. Simply use ``certbot_py`` on the command line,\nfull help is available.\n\nNotes\n^^^^^\n\n1. ``certbot`` version 0.10.0 is the first version to expose the\n necessary command line arguments - prior versions will fail.\n2. This library should be updated for security and bug fixes (obviously)\n but also may require updating if the underlying arguments to\n ``certbot`` change or features are added.\n\nFuture\n^^^^^^\n\nGee, I should mock in some tests...\n\nLonger term, I look forward to having this library change (and improve!)\nso that it no longer needs Python's ``subprocess.Popen()`` or a\n``certbot`` installation. This is technically possible using Let's\nEncrypt's ```acme``\nlibrary `__;\nhowever creating a client around ``acme`` involves much more than\nsomething simple like ``acme.generate_certificate(...)``. Much in this\nACME/Let's Encrypt world seems in flux at the moment, so implementing\nthis wrapper felt like the easiest path forward for the time being - and\nretains full compatibility with the standard Let's Encrypt command line\ntools.\n\nFeedback is encouraged and appreciated. `File issues on\nGithub `__. Feel free to\nfork and suggest improvements.\n\n\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/jaddison/certbot_py", "keywords": "certbot letsencrypt ssl certificate https secure encrypt encryption", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "certbot-py", "package_url": "https://pypi.org/project/certbot-py/", "platform": "", "project_url": "https://pypi.org/project/certbot-py/", "project_urls": { "Homepage": "https://github.com/jaddison/certbot_py" }, "release_url": "https://pypi.org/project/certbot-py/0.10.1/", "requires_dist": [ "six" ], "requires_python": "", "summary": "Python module to integrate automated Let's Encrypt `certbot certonly` certificate creation into Python projects.", "version": "0.10.1" }, "last_serial": 2689337, "releases": { "0.10.0": [ { "comment_text": "", "digests": { "md5": "4402c1f1d7c7ed4846fd09dbd5520916", "sha256": "19c209467b40de22a8bf095cd8e312db58a9bb23a636a4e89a6b9ee725847138" }, "downloads": -1, "filename": "certbot_py-0.10.0-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "4402c1f1d7c7ed4846fd09dbd5520916", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 12030, "upload_time": "2017-01-12T18:22:40", "url": "https://files.pythonhosted.org/packages/ec/09/c5ef51e907640b5126c6a130a3b00ae9bb948f0c21196842bc37ba78bc0c/certbot_py-0.10.0-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "fda9098853baef4ac96b481f0a521b16", "sha256": "cd4c88811b03e718474656ca1b24dc9b9116b1c90dadac41924b5dd57040245e" }, "downloads": -1, "filename": "certbot_py-0.10.0.tar.gz", "has_sig": false, "md5_digest": "fda9098853baef4ac96b481f0a521b16", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8449, "upload_time": "2017-01-12T18:22:42", "url": "https://files.pythonhosted.org/packages/cc/83/20e013b9291e3dda3342b929cbbe75a91579a760588a19f30e69ceba3e01/certbot_py-0.10.0.tar.gz" } ], "0.10.1": [ { "comment_text": "", "digests": { "md5": "02ac8e14bca627cca630b56641090d84", "sha256": "e72e59da88e394098777b9767527217ace5e9fcc11af8926f6187eff7719870f" }, "downloads": -1, "filename": "certbot_py-0.10.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "02ac8e14bca627cca630b56641090d84", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 12033, "upload_time": "2017-03-07T17:07:39", "url": "https://files.pythonhosted.org/packages/59/9e/868bb97f0e9ed12bfb2cd9bba451ea703cb679c4da5e1fd1a8d4b2c2f15e/certbot_py-0.10.1-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c09b482804e4b9383a9b2120a353bbcf", "sha256": "9209e5a1cd161082e2a4d49e2f7ba8abec2d7f6695cfada279672fd7e87f2b69" }, "downloads": -1, "filename": "certbot_py-0.10.1.tar.gz", "has_sig": false, "md5_digest": "c09b482804e4b9383a9b2120a353bbcf", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8459, "upload_time": "2017-03-07T17:07:41", "url": "https://files.pythonhosted.org/packages/2c/b6/22166fe7f992c80617c9cd10e25d934540ec5df72384d7251889425775ec/certbot_py-0.10.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "02ac8e14bca627cca630b56641090d84", "sha256": "e72e59da88e394098777b9767527217ace5e9fcc11af8926f6187eff7719870f" }, "downloads": -1, "filename": "certbot_py-0.10.1-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "02ac8e14bca627cca630b56641090d84", "packagetype": "bdist_wheel", "python_version": "py2.py3", "requires_python": null, "size": 12033, "upload_time": "2017-03-07T17:07:39", "url": "https://files.pythonhosted.org/packages/59/9e/868bb97f0e9ed12bfb2cd9bba451ea703cb679c4da5e1fd1a8d4b2c2f15e/certbot_py-0.10.1-py2.py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "c09b482804e4b9383a9b2120a353bbcf", "sha256": "9209e5a1cd161082e2a4d49e2f7ba8abec2d7f6695cfada279672fd7e87f2b69" }, "downloads": -1, "filename": "certbot_py-0.10.1.tar.gz", "has_sig": false, "md5_digest": "c09b482804e4b9383a9b2120a353bbcf", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8459, "upload_time": "2017-03-07T17:07:41", "url": "https://files.pythonhosted.org/packages/2c/b6/22166fe7f992c80617c9cd10e25d934540ec5df72384d7251889425775ec/certbot_py-0.10.1.tar.gz" } ] }