Rel4tion-Wiki/maint/admin/ca.mdwn

If you'd like to know how Rel4tion's independent
[[!wikipedia Certificate_Authority]] (CA) works and how to participate in its
administration (if you talked to [[fr33domlover]] about it), you came to the
right place.

# Intro

When SSL certificates were first created for Rel4tion, there was only the
[OpenNIC] domain name `partager.null` and [[!wikipedia TinyCA]] was used for all
the CA related tasks. All the files were stored directly on the server, because
there was no other computer to use for managing the CA (and there still isn't).
It felt easy, but it was clear that it's not the safest option.

[OpenNIC]: http://opennicproject.org

The instructions for TinyCA can still be generally useful, since they aren't
specific to Partager/Rel4tion, and be found here: [[CA with TinyCA|tinyca]]. In
fact, they are more verbose than the instructions below and explain things, so
if you see too many unfamiliar words below, take a look.

While the author believes that the key to security and privacy is simply not
violating and not harming them (and that requires personal responsibility and
respect between people, not complicated technology), in today's sad situation it
seems that such technology is a good tool in the hands of those who wish to
fight the global abuse by selfish companies and governments, or just protect
themselves and others without depending on central forces. Therefore, SSL
certificates are consistently provided for all services and subdomains where
relevant. They aren't needed for networks with authentication built-in, such as
[[!wikipedia I2P]], but they're used for
"[[!wikipedia surface_web desc=clearnet]]" with both the OpenNIC domain
`partager.null` and the [[!wikipedia ICANN]] domain `rel4tion.org`.

Rel4tion's CA is a **community CA**. It means that anyone can participate and
get their certificates signed, but only as long as everyone knows everyone. This
requirement means that trust between members is maintained and the community
remains small enough to sustain the trust. So joining means talking to people,
getting to know them, becoming part of the community and later possibly also
helping new participants. There is no need to check your goverment ID or phone
number or any other private information, because trust here is real actual trust
between friends, not the digital fake "trust" that large CAs provide by checking
your paperwork. As an example, g00gle and faceb00k with their spyware still get
as many certificates as they want, simply because they are real registered
companies. See below for more info about the CA's management.

# Technology

The tools used for managing the Rel4tion CA are:

- The [[!wikipedia GnuTLS]] software
- The [[!wikipedia GnuPG]] software
- The [Monkeysphere] software
- The [[!wikipedia ext4]] filesystem, with encryption
- A [[!wikipedia USB_flash_drive]]
- A micro [[!wikipedia SD_card]]

[Monkeysphere]: http://web.monkeysphere.info

# Social Workflow

[[TODO|/todo/open]] fill info here

# Technical Workflow

All the files related to the CA and the certificates, including copies of all
the keys and all the certificates used on Rel4tion's server, are stored on two
storage devices - the flash drive and the SD card mentioned above. The same
content is stored on both. Using 2 devices provides more realiable backup than
1, because if something happens to one, all the files are available on the
other. These are the only two locations - except for the certificates and keys
required by Rel4tion's server, the files aren't stored on the server itself or
on always-attached external storage.

Both devices have encrypted ext4 partitions, on which the files are stored.

When a change needs to be made, the USB flash drive is attached to the server
and the commands are executed by the root user. If needed, certificates and keys
are copied to the server, where the server daemons can find and use them.

After the operation, the updated files are copied to the MicroSD card, so it
contains an exact copy of what the flash drive contains. Finally, both are
physically detached from the server.

# Technical Conventions

The content stored on these two devices is referred to as "the CA package" or
just "the package".

The filenames of certificates and keys have the form
`<subdomain>.<domain>.<extension>`, where:

- `subdomain` is optional, and if it's not there the period after it is not
  needed either. But it shouldn't be omitted unless it's the website certificate
  or the CA certificate etc., i.e. perhaps not tied to a subdomain. Examples:
  `www`, `doc`, `mail`, `ftp`, `git`.
- `domain` is `rel4tion.org`, even if the certificate/key is used with
   additional domains such as `partager.null`.
- `extension` is `key`, `crt` or `pem`. If the file contains just the private
  key, then it's `key`. If the file contains just the public certificate, then
  it's `crt`. If it contains both, then it's `pem`.

The files of the CA itself may be an exception, since they aren't tied to any
specific domain name.

# Commands and Procedures

When creating new files, always change their permissions to give only the root
user, and nobody else, access to the files.

## CA Creation

Install the required software:

	# apt-get install gnutls-bin gnupg

Create an RSA private key for the CA:

	# certtool --generate-privkey --bits 4096 --outfile rel4tion-ca.key

Use a long password. Write it on a piece of paper and store in a safe place.

Create a template file for the CA certificate. The certificate will be created
once, but any future updates will be much easier because you just need to update
the template file and pass it to `certtool`. Initial template file
`rel4tion-ca.template`:

[[ca-template-initial]]

Create a certificate for the CA:

	# certtool --generate-self-signed \
	           --load-privkey rel4tion-ca.key \
	           --template rel4tion-ca.template \
	           --outfile rel4tion-ca.crt

[[TODO|/todo/open]] what about the CRL? explain

## CA Deployment

Using GnuPG, sign the CA certificate:

	$ gpg --armor \
	      --comment "http://www.rel4tion.org/people/fr33domlover" \
	      --detach-sign \
	      rel4tion-ca.crt
	$ mv rel4tion-ca.crt.asc rel4tion-ca.crt.sig

Put the CA certificate and the signature under the `cert` subdomain, from which
they will be downloaded by clients:

	# mv rel4tion-ca.crt rel4tion-ca.crt.sig /var/www/cert

And make sure they are readable by the `www-data` user.

[[TODO|/todo/open]] link to and explain about writing/updating usage
instructions for users. The current plan is to move them to [[/access/www]].

## Certificate Creation

The commands below assume we're creating a certificate for the
`mail.rel4tion.org` service.

First of all, generating a signed certificate requires trust in order to have
any value (compared to a self-signed certificate). The good old kind, trust
between friends. So you should get to know the people here, and they should get
to know you, and GPG keys should be exchanged and signed. In particular, make
sure [[fr33domlover]] signs the GPG key you use for signing e-mail.

Create an RSA private key for the service.

	# certtool --generate-privkey \
	           --bits 4096 \
	           --outfile mail.rel4tion.org.key

Create a template file for the service certificate. If there's more than one
domain name for which the certificate will be used (i.e. the Common Name field
isn't enough), add the domains as [[!wikipedia "Subject Alternative Name"]]s
(SANs). Actually, you can put anything in the CN and add domains only as SANs,
even if you're adding just a single domain. Here's an example template file:

[[service-template-example]]

Also note that if a DNS name is used as a SAN, any subdomains will be matched
as well. For example, a certificate for `xmpp.example.org` will also be valid
for `muc.xmpp.example.org`.

Create a certificate signing request (CSR):

	# certtool --generate-request \
	           --load-privkey mail.rel4tion.org.key \
	           --template mail.rel4tion.org.template \
	           --outfile mail.rel4tion.org.csr

Send the CSR and the template in a GPG-signed e-mail message. Here's how to sign
the CSR as the CA, assuming our template file is `mail.rel4tion.org.template`:

	# certtool --generate-certificate \
	           --load-request mail.rel4tion.org.csr \
	           --load-ca-certificate rel4tion-ca.crt \
	           --load-ca-privkey rel4tion-ca.key \
	           --template mail.rel4tion.org.template \
	           --outfile mail.rel4tion.org.crt

If you sent the CSR and the template using signed e-mail, you should receive the
signed certificate as signed e-mail too, and verify the signature.

Examine the certificate and make sure the contents are all there as expected:

	# certtool --certificate-info --infile mail.rel4tion.org.crt

[[TODO|/todo/open]] explain how to sign cert with monkeysphere

[[TODO|/todo/open]] explain how to basically let server daemons access the cert
and the key, `cat` PEM files, maybe link to some server config pages on the wiki
if any exist, etc.

## Certificate Deployment

[[TODO|/todo/open]]