diff --git a/README.rst b/README.rst index c613bc7..a0a45ea 100644 --- a/README.rst +++ b/README.rst @@ -17,9 +17,10 @@ eventually support PKCS#11 and in far future WebCrypto. .. figure:: doc/usecase-diagram.png -Certidude is mainly designed for VPN gateway operators to make -desktop/laptop VPN setup as easy as possible. -User certificate management eg. for HTTPS is also made reasonably simple. +Certidude is mainly designed for StrongSwan and OpenVPN gateway operators to make +VPN client setup on laptops, desktops and mobile devices as painless as possible. +Certidude can also be used to manage HTTPS client certificates for +eg. maintaining an extra layer of protection for intranet websites. For a full-blown CA you might want to take a look at `EJBCA `_ or `OpenCA `_. @@ -105,18 +106,29 @@ TODO Install ------- -To install Certidude server: +To install Certidude server you need certain system libraries in addition to +regular Python dependencies. + +System dependencies for Ubuntu 16.04: .. code:: bash - apt-get install -y python python-pip python-dev cython \ + apt install -y python python-pip python-dev cython \ python-cffi python-configparser \ python-pysqlite2 python-mysql.connector python-ldap \ build-essential libffi-dev libssl-dev libkrb5-dev \ ldap-utils krb5-user \ libsasl2-modules-gssapi-mit \ libsasl2-dev libldap2-dev - pip install simplepam pykerberos certidude + +System dependencies for Fedora 24+: + +.. code:: bash + + yum install redhat-rpm-config python-devel openssl-devel openldap-devel + +At the moment package at PyPI is rather outdated. +Please proceed down to Development section to install Certidude from source. Setting up authority @@ -139,15 +151,6 @@ If necessary tweak machine's fully qualified hostname in ``/etc/hosts``: 127.0.0.1 localhost 127.0.1.1 ca.example.com ca -Then proceed to install `nchan `_: - -.. code:: bash - - wget https://nchan.slact.net/download/nginx-common.deb \ - https://nchan.slact.net/download/nginx-extras.deb - dpkg -i nginx-common.deb nginx-extras.deb - apt-get -f install - Certidude can set up certificate authority relatively easily. Following will set up certificate authority in ``/var/lib/certidude/hostname.domain.tld``, configure systemd service for your platform, @@ -166,27 +169,27 @@ and start the services: systemctl restart certidude -Certificate management ----------------------- +Setting up PAM authentication +----------------------------- -Use following command to request a certificate on a machine: +Following assumes the OS user accounts are used to authenticate users. +This means users can be easily managed with OS tools such as ``adduser``, ``usermod``, ``userdel`` etc. -.. code:: +Make sure you insert `AllowUsers administrator-account-username` +to SSH server configuration if you have SSH server installed on the machine +to prevent regular users from accessing the command line of certidude. +Note that in future we're planning to add command-line interaction +in which case SSH access makes sense. - certidude setup client ca.example.com +If you're planning to use PAM for authentication you need to install corresponding +Python modules: -Use following to list signing requests, certificates and revoked certificates on server: +.. code:: bash -.. code:: - - certidude list - -Use web interface or following to sign a certificate on server: - -.. code:: - - certidude sign client-hostname-or-common-name + pip install simplepam +The default configuration generated by ``certidude setup`` should make use of the +PAM. Setting up Active Directory authentication ------------------------------------------ @@ -199,6 +202,7 @@ Install dependencies: .. code:: bash apt-get install samba-common-bin krb5-user ldap-utils + pip install pykerberos Reset Samba client configuration in ``/etc/samba/smb.conf``, adjust workgroup and realm accordingly: @@ -274,33 +278,58 @@ Common pitfalls: the CA machine to domain, eg when you're running CA behind SSL terminating web server: Bad credentials: Unspecified GSS failure. Minor code may provide more information (851968) -Automating certificate setup ----------------------------- -Ubuntu 14.04 based desktops come with NetworkManager installed. -Create ``/etc/NetworkManager/dispatcher.d/certidude`` with following content: +Setting up services +------------------- + +Set up services as usual (OpenVPN, Strongswan, etc), when setting up certificates +generate signing request with TLS server flag set. +Paste signing request into the Certidude web interface and hit the submit button. + +Since signing requests with custom flags are not allowed to be signed +from the interface due to security concerns, sign the certificate at Certidude command line: .. code:: bash - #!/bin/sh -e - # Set up certificates for IPSec connection + certidude sign gateway.example.com - case "$2" in - up) - LANG=C.UTF-8 /usr/local/bin/certidude request spawn -k - ;; - esac +Download signed certificate from the web interface or ``wget`` it into the service machine. +Fetch also CA certificate and finish configuring the service. -Finally make it executable: + +Setting up clients +------------------ + +This example works for Ubuntu 16.04 desktop with corresponding plugins installed +for NetworkManager. + +Configure Certidude client in ``/etc/certidude/client.conf``: + +.. code:: ini + + [ca.example.com] + insecure = true + trigger = interface up + +Configure services in ``/etc/certidude/services.conf``: .. code:: bash - chmod +x /etc/NetworkManager/dispatcher.d/certidude + [gateway.example.com] + authority = ca.example.com + service = network-manager/openvpn + remote = gateway.example.com -Whenever a wired or wireless connection is brought up, -the dispatcher invokes ``certidude`` in order to generate RSA keys, -submit CSR, fetch signed certificate, -create NetworkManager configuration for the VPN connection. +To request certificate: + +.. code:: bash + + certidude request + +The keys, signing requests, certificates and CRL-s are placed under +/var/lib/certidude/ca.example.com/ + +The VPN connection should immideately become available under network connections. Development @@ -323,7 +352,7 @@ To generate templates: .. code:: bash - apt-get install npm nodejs + apt install npm nodejs sudo ln -s nodejs /usr/bin/node # Fix 'env node' on Ubuntu 14.04 npm install -g nunjucks@2.5.2 nunjucks-precompile --include "\\.html$" --include "\\.svg$" certidude/static/ > certidude/static/js/templates.js @@ -340,3 +369,30 @@ To install the package from the source: .. code:: bash python setup.py install --single-version-externally-managed --root / + +To uninstall: + + pip uninstall certidude + + +Certificate attributes +---------------------- + +Certificates have a lot of fields that can be filled in. +In any case country, state, locality, organization, organizational unit are not filled in +as this information will already exist in AD and duplicating it in the certificate management +doesn't make sense. Additionally the information will get out of sync if +attributes are changed in AD but certificates won't be updated. + +If machine is enrolled, eg by running certidude request: + +* If Kerberos credentials are presented machine is automatically enrolled +* Common name is set to short hostname/machine name in AD +* E-mail is not filled in (maybe we can fill in something from AD?) +* Given name and surname are not filled in + +If user enrolls, eg by clicking generate bundle button in the web interface: + +* Common name is either set to username or username@device-identifier depending on the 'user certificate enrollment' setting +* Given name and surname are filled in based on LDAP attributes of the user +* E-mail not filled in (should it be filled in? Can we even send mail to user if it's in external domain?)