{"id":13725444,"url":"https://github.com/laurivosandi/certidude","last_synced_at":"2025-05-08T21:15:30.745Z","repository":{"id":62561473,"uuid":"38974467","full_name":"laurivosandi/certidude","owner":"laurivosandi","description":"Easy to use Certificate Authority web service for OpenVPN, StrongSwan and HTTPS","archived":false,"fork":false,"pushed_at":"2018-10-05T07:47:44.000Z","size":5840,"stargazers_count":127,"open_issues_count":29,"forks_count":30,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-08T21:15:24.332Z","etag":null,"topics":["apache2","kerberos","ldap","nginx","openssl","openvpn","python","strongswan","x509"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laurivosandi.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-12T19:15:19.000Z","updated_at":"2024-12-31T11:36:48.000Z","dependencies_parsed_at":"2022-11-03T15:16:48.759Z","dependency_job_id":null,"html_url":"https://github.com/laurivosandi/certidude","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurivosandi%2Fcertidude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurivosandi%2Fcertidude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurivosandi%2Fcertidude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurivosandi%2Fcertidude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laurivosandi","download_url":"https://codeload.github.com/laurivosandi/certidude/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149619,"owners_count":21861740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache2","kerberos","ldap","nginx","openssl","openvpn","python","strongswan","x509"],"created_at":"2024-08-03T01:02:23.420Z","updated_at":"2025-05-08T21:15:30.721Z","avatar_url":"https://github.com/laurivosandi.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Certidude\n=========\n\n.. image:: https://travis-ci.org/laurivosandi/certidude.svg?branch=master\n    :target: https://travis-ci.org/laurivosandi/certidude\n\n.. image:: http://codecov.io/github/laurivosandi/certidude/coverage.svg?branch=master\n    :target: http://codecov.io/github/laurivosandi/certidude?branch=master\n\n\nIntroduction\n------------\n\nCertidude is a minimalist X.509 Certificate Authority management tool\nwith Kerberos authentication mainly designed for OpenVPN gateway operators to make\nVPN client setup on laptops, desktops and mobile devices as painless as possible.\n\n.. figure:: doc/certidude.png\n\nCertidude can also be used to manage IPSec certifcates (StrongSwan)\nor HTTPS client certificates to limit access to eg. intranet websites.\nFor a full-blown CA you might want to take a look at\n`EJBCA \u003chttp://www.ejbca.org/features.html\u003e`_ or\n`OpenCA \u003chttps://pki.openca.org/\u003e`_.\n\n\nUsecases\n--------\n\n.. figure:: doc/usecase-diagram.png\n\nFollowing usecases are covered:\n\n* I am a sysadmin. Employees with different operating systems need to access\n  internal network services over OpenVPN.\n  I want to provide web interface for submitting the certificate signing request online.\n  I want to get notified via e-mail when a user submits a certificate.\n  Once I have signed the certificate I want the user to have easy way to download\n  the signed certificate from the same web interface.\n  Request submission and signing has to be visible in the web interface\n  immediately. Common name is set to username.\n\n* I am a sysadmin. I want to allow my Ubuntu roadwarriors to\n  connect to network services at headquarters via IPSec.\n  I want to make use of domain membership trust to automatically sign the certificates.\n  Common name is set to computers hostname without the domain suffix.\n  NetworkManager integration is necessary so the user can see the VPN connection state.\n  Software installation and one simple configuration file should suffice to get up and running.\n\n* I am a sysadmin. Employees need to get access to intranet wiki using\n  HTTPS certificates possibly with multiple devices.\n  Common name is set to username@device-identifier.\n  The user logs in using domain account in the web interface and can automatically\n  retrieve a P12 bundle which can be installed on her Android device.\n\n\nFeatures\n--------\n\nCommon:\n\n* Standard request, sign, revoke workflow via web interface.\n* RSA and Elliptic Curve Cryptography both supported, use ``certidude provision authority --elliptic-curve`` for the second\n* `OCSP \u003chttps://tools.ietf.org/html/rfc4557\u003e`_ and `SCEP \u003chttps://tools.ietf.org/html/draft-nourse-scep-23\u003e`_ support.\n* PAM and Active Directory compliant authentication backends: Kerberos single sign-on, LDAP simple bind.\n* POSIX groups and Active Directory (LDAP) group membership based authorization.\n* Server-side command-line interface, check out ``certidude list``, ``certidude sign`` and ``certidude revoke``.\n* Certificate serial numbers are intentionally randomized to avoid leaking information about business practices.\n* Server-side events support via `nchan \u003chttps://nchan.slact.net/\u003e`_.\n* E-mail notifications about pending, signed, revoked, renewed and overwritten certificates.\n* Built using compilation-free `oscrypto \u003chttps://github.com/wbond/oscrypto\u003e`_ library.\n* Object tagging, attach metadata to certificates using extended filesystem attributes.\n\nVirtual private networking:\n\n* Send VPN profile URL tokens via e-mail, for simplified VPN adoption on Android, iOS, Windows, Mac OS X and Ubuntu.\n* OpenVPN gateway and roadwarrior integration, check out ``certidude provision openvpn server`` and ``certidude provision openvpn client``.\n* StrongSwan gateway and roadwarrior integration, check out ``certidude provision strongswan server`` and ``certidude provision strongswan client``.\n* NetworkManager integration for Ubuntu and Fedora, check out ``certidude provision openvpn networkmanager`` and ``certidude provision strongswan networkmanager``.\n\nHTTPS:\n\n* P12 bundle generation for web browsers, seems to work well with Android\n* HTTPS server setup with client verification, check out ``certidude provision nginx``\n\n\nInstall\n-------\n\nTo install Certidude server you need certain system libraries in addition to\nregular Python dependencies.\n\nSystem dependencies for Ubuntu 16.04:\n\n.. code:: bash\n\n    apt install -y python3-click python3-jinja2 python3-markdown \\\n        python3-pip python3-mysql.connector python3-requests python3-pyxattr\n\nSystem dependencies for Fedora 25+:\n\n.. code:: bash\n\n    yum install redhat-rpm-config python-devel openssl-devel openldap-devel\n\nAt the moment package at PyPI is rather outdated.\nPlease proceed down to `Development \u003c#development\u003e`_ section to install Certidude from source.\n\n\nSetting up authority\n--------------------\n\nFirst make sure the machine used for certificate authority has fully qualified\ndomain name set up properly.\nYou can check it with:\n\n.. code:: bash\n\n    hostname -f\n\nThe command should return ``ca.example.com``.\nIf necessary tweak machine's fully qualified hostname in ``/etc/hosts``:\n\n.. code::\n\n    127.0.0.1 localhost\n    127.0.1.1 ca.example.com ca\n\nCertidude will submit e-mail notifications to locally running MTA.\nInstall Postfix and configure it as Satellite system:\n\n.. code:: bash\n\n    apt install postfix\n\nCertidude can set up certificate authority relatively easily.\nFollowing will set up certificate authority in ``/var/lib/certidude/``,\nconfigure systemd service for your platform,\nnginx in ``/etc/nginx/sites-available/certidude.conf``,\ncronjobs in ``/etc/cron.hourly/certidude`` and much more:\n\n.. code:: bash\n\n    certidude provision authority\n\nTweak the configuration in ``/etc/certidude/server.conf`` until you meet your requirements,\nto apply changes run:\n\n.. code:: bash\n\n    systemctl restart certidude\n\n\nSetting up PAM authentication\n-----------------------------\n\nFollowing assumes the OS user accounts are used to authenticate users.\nThis means users can be easily managed with OS tools such as ``adduser``, ``usermod``, ``userdel`` etc.\n\nMake sure you insert `AllowUsers administrator-account-username`\nto SSH server configuration if you have SSH server installed on the machine\nto prevent regular users from accessing the command line of certidude.\nNote that in future we're planning to add command-line interaction\nin which case SSH access makes sense.\n\nIf you're planning to use PAM for authentication you need to install corresponding\nPython modules:\n\n.. code:: bash\n\n    pip3 install simplepam\n\nThe default configuration generated by ``certidude provision`` should make use of the\nPAM.\n\nSetting up Active Directory authentication\n------------------------------------------\n\nFollowing assumes you have already set up Kerberos infrastructure and\nCertidude is simply one of the servers making use of that infrastructure.\n\nInstall additional dependencies:\n\n.. code:: bash\n\n    apt-get install samba-common-bin krb5-user ldap-utils python-gssapi\n\nReset Samba client configuration in ``/etc/samba/smb.conf``, adjust\nworkgroup and realm accordingly:\n\n.. code:: ini\n\n    [global]\n    security = ads\n    netbios name = CA\n    workgroup = EXAMPLE\n    realm = EXAMPLE.COM\n    kerberos method = system keytab\n\nReset Kerberos client configuration in ``/etc/krb5.conf``:\n\n.. code:: ini\n\n    [libdefaults]\n    default_realm = EXAMPLE.COM\n    dns_lookup_realm = true\n    dns_lookup_kdc = true\n\nInitialize Kerberos credentials:\n\n.. code:: bash\n\n    kinit administrator\n\nJoin the machine to domain:\n\n.. code:: bash\n\n    net ads join -k\n\nSet up Kerberos keytab for the web service:\n\n.. code:: bash\n\n    KRB5_KTNAME=FILE:/etc/certidude/server.keytab net ads keytab add HTTP -k\n    chown root:certidude /etc/certidude/server.keytab\n    chmod 640 /etc/certidude/server.keytab\n\nReconfigure /etc/certidude/server.conf so ``kerberos`` backend is used for authentication,\nand ``ldap`` backend is used for accoutns and authorization.\nAdjust related options as necessary.\nAlso make sure there is cron.hourly job for creating GSSAPI credential cache -\nthat's necessary for querying LDAP using Certidude machine's credentials.\n\nCommon pitfalls:\n\n* Following error message may mean that the IP address of the web server does not match the IP address used to join\n  the CA machine to domain, eg when you're running CA behind SSL terminating web server:\n  Bad credentials: Unspecified GSS failure.  Minor code may provide more information (851968)\n\n\nSetting up services\n-------------------\n\nSet up services as usual (OpenVPN, Strongswan, etc), when setting up certificates\nSee Certidude admin interface how to submit CSR-s and retrieve signed certificates.\n\n\nSetting up clients\n------------------\n\nThis example works for Ubuntu 16.04 desktop with corresponding plugins installed\nfor NetworkManager.\n\nConfigure Certidude client in ``/etc/certidude/client.conf``:\n\n.. code:: ini\n\n    [ca.example.com]\n    trigger = interface up\n    hostname = $HOSTNAME\n\nConfigure services in ``/etc/certidude/services.conf``:\n\n.. code:: bash\n\n    [OpenVPN to gateway.example.com]\n    authority = ca.example.com\n    service = network-manager/openvpn\n    remote = gateway.example.com\n\n    [IPSec to gateway.example.com]\n    authority = ca.example.com\n    service = network-manager/strongswan\n    remote = gateway.example.com\n\nTo request certificate:\n\n.. code:: bash\n\n    certidude enroll\n\nThe keys, signing requests, certificates and CRL-s are placed under\n/etc/certidude/authority/ca.example.com/\n\nThe VPN connection should immideately become available under network connections.\n\n\nDevelopment\n-----------\n\nTo use dependencies from pip:\n\n.. code:: bash\n\n    apt install build-essential python-dev cython libffi-dev libssl-dev \\\n        libkrb5-dev ldap-utils krb5-user libsasl2-modules-gssapi-mit \\\n        libsasl2-dev libldap2-dev\n\nClone the repository:\n\n.. code:: bash\n\n    git clone https://github.com/laurivosandi/certidude /srv/certidude\n    cd /srv/certidude\n\nInstall dependencies as shown above and additionally:\n\n.. code:: bash\n\n    pip3 install -r requirements.txt\n\nTo install the package from the source tree:\n\n.. code:: bash\n\n    pip3 install -e .\n\nTo run tests and measure code coverage grab a clean VM or container,\nset hostname to ca.example.lan, export environment variable COVERAGE_PROCESS_START globally and run:\n\n.. code:: bash\n\n    pip3 install codecov pytest-cov\n    rm /tmp/.coverage*\n    COVERAGE_PROCESS_START=/srv/certidude/.coveragerc  py.test tests --capture=sys\n    coverage combine\n    coverage report\n    coverage html -i\n\nTo uninstall:\n\n.. code:: bash\n\n    pip3 uninstall certidude\n\n\nDocker\n------\n\n.. code:: bash\n\n    git clone https://github.com/laurivosandi/certidude\n    cd certidude\n    docker build .\n    docker run --name ca --hostname ca.example.lan\n\n\nOffline install\n---------------\n\nTo prepare packages for offline installation use following snippet on a\nvanilla Ubuntu 16.04 or container:\n\n.. code:: bash\n\n    rm -fv /var/cache/apt/archives/*.deb /var/cache/certidude/wheels/*.whl\n    apt install python3-pip\n    pip3 wheel --wheel-dir=/var/cache/certidude/wheels -r requirements.txt\n    pip3 wheel --wheel-dir=/var/cache/certidude/wheels .\n    tar -cf certidude-client.tar /var/cache/certidude/wheels\n    add-apt-repository -y ppa:nginx/stable\n    apt-get update -q\n    apt install --download-only python3-markdown python3-pyxattr python3-jinja2 python3-cffi software-properties-common libnginx-mod-nchan nginx-full\n    pip3 wheel --wheel-dir=/var/cache/certidude/wheels falcon humanize ipaddress simplepam user-agents python-ldap gssapi\n    tar -cf certidude-server.tar /var/lib/certidude/assets/ /var/cache/apt/archives/ /var/cache/certidude/wheels\n\nTransfer certidude-server.tar or certidude-client.tar to the target machine and execute:\n\n.. code:: bash\n\n    rm -fv /var/cache/apt/archives/*.deb /var/cache/certidude/wheels/*.whl\n    tar -xvf certidude-*.tar -C /\n    dpkg -i /var/cache/apt/archives/*.deb\n    pip3 install  --use-wheel --no-index --find-links /var/cache/certidude/wheels/*.whl\n\nProceed to bootstrap authority without installing packages or assembling assets:\n\n.. code:: bash\n\n    certidude provision authority  --skip-packages --skip-assets [--elliptic-curve] [--organization \"Mycorp LLC\"]\n\nNote it's highly recommended to enable nginx PPA in the target machine\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurivosandi%2Fcertidude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaurivosandi%2Fcertidude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurivosandi%2Fcertidude/lists"}