General Description

Pidgin doesn't currently do any certificate verification for SSL. In order to properly do this and ensure security, a certificate manager (something like Mozilla's) needs to be added.

This is William Ehlhardt's project for Summer of Code

Branch

im.pidgin.soc.2007.certmgr

Handy-dandy overview

SSL: The Connection Process

1. purple_ssl_connect called
2. ssl_connect looks up the "x509" CertificateScheme?, making sure that it is loaded
3. ssl_connect fetches a the host's certificate
4. ssl_connect asks the "tls_peers" CertificateAuthorizer? for verification of the certificate.
5. The tls_peers CertificateAuthorizer? sees if the get_unique_id(cert) can be found within the pool "tls_servers". If so, the certificate is considered Authenticated, and control returns to ssl_connect, which proceeds to the Hostname Check.
6. If the certificate cannot be found in the "tls_servers" pool, the tls_peers Authorizer then checks the "tls_ca" pool to see if the certificate chain (using get_signer_unique_id(cert)) leads to any certificates in the "tls_ca" pool. If it does find such a certificate, it uses the check_signature function to verify the signature chain, and if THAT passes, control returns to ssl_connect, which proceeds to the Hostname Check.
7. If the tls_peers CertAuthorizer? finds an invalid (apparently attempted forged) signature, the connection fails and the user is given a popup detailing the reason.
8. If the tls_peers CertAuthorizer? fails to find any appropriate signers in the "tls_ca" or "tls_servers" pool, the user is prompted with the certificate details given by get_verification_data. If the certificate passes user prompting, tls_peers->bless_certificate is called.
9. If tls_peers finds an expired certificate or any other problem, the connection is aborted with an error.
10. We shouldn't get to step 10.

Hostname Check

(some logic needs to be changed here to ensure that we don't prompt every connect for incorrect CN fields)

1. ssl_connect checks that the certificate Common Name matches the hostname being connected to. If it matches, it completes the connection initialization. The hostname check may not always work, though, so:
2. If the hostname check fails, ssl_connect will prompt the user with the certificate data and a warning that the hostname check failed.
3. If the user authorizes the certificate anyways, ssl_connect calls bless_certificate in the tls_peers CertificateAuthorizor?, which adds it to the "tls_peers" pool. The connection initialization is then completed. (The exact action at this step is not really laid in stone, though)

CertificateScheme? API

• Closely modeled on Cipher API

struct Certificate

• CertificateScheme? * scheme
• Internal data

struct CertificateScheme?

Will be registered into an internal list of scheme types

• char * name = "x509", "pgp", etc. This must be internally unique - there must be only ONE CertificateScheme? for each name. This is to pre-empt the possibility of someone creating some Certificate instances with a GnuTLS backend and then feeding them to a libNSS backend.
• int ref - for reference counting
• Certificate * import_certificate(file arguments) -
• export_certificate(filename?)
• gboolean check_signature(Certificate * certificate, Certificate * signer) - returns whether one certificate is signed by another
• (some_tuple_list_type) get_verification_data() - returns a list of key-value pairs containing things to show to the user to check the certificate's validity. It's not strictly key-value due to i18n concerns, but here is an example: [ ("fpr_sha1","0123456789abcdef0123456789abcdef",_("SHA1 Fingerprint")), ("common_name","gmail.com",_("Common Name")), NULL ]
• char * get_unique_id - returns a string (probably something involving a key fingerprint) that can usefully be used to uniquely identify this certificate (for storage purposes)
• char * get_signer_unique_id - returns a unique identifier for the key used to sign the certificate
• destroy_certificate(Certificate * crt) - when a certificate's life has reached its end, call this to get rid of it. Will execute free(crt) for you.

Certificate Scheme Requirements

Requirements for implementors of various CertificateSchemes?

X.509

Name	"x509"
import_certificate File Format	PEM
unique_id construction	Not yet defined

struct CertificatePool?

• char * name - the pool identifier
• CertificateScheme? * scheme - certificate type this pool is filled with
• gboolean exists_in_pool(unique_id) - checks for the presence of a given cert in the pool (see get_unique_id above) (may take Certificate instead of unique_id?)
• Certificate * retrieve_certificate(unique_id)
• store_certificate(Certificate) - overwrites previous certificate by unique_id if it exists

struct CertificateAuthorizer?

• char * name - unique identifier ("tls_peers", "silc_servers", etc.)
• CertificateScheme? * scheme - certificate type this authorizer works with
• bless_certificate - forces the certificate's authorization (just calls CertificatePool?->store_certificate, most likely)
• gboolean certificate_is_valid (Certificate) - returns whether a certificate can be verified as usable.
  • Perhaps it should also take an expected_values argument of the same form as the return value from get_verification_data(Certificate) to specify some values to check (such as Common Name, which maybe ought to be optional?)

SslOps? Additions

• get_peer_certificates - fetches as much of the certificate chain as the peer is willing to provide off of the wire and exports the certificates as several "x509" Certificate instances.

Key Store

Managed by a CertificatePool?.

The API for this hasn't been totally decided yet. However, the organization will look something like this: ~/.purple/certificates/cert_scheme_name/cert_pool/cert_unique_id(.pem?) So an example X.509 certificate might be stored as: ~/.purple/certificates/x509/tls_servers/gmail_com_1234567890abcdef1234567890abcdef.pem The keystore logic will be left mostly up to the relevant CertificatePool?; these are only guidelines for how the CertificatePools? should run their backends.

Miscellaneous API changes

• Jabber (and possibly other protocols) use purple_ssl_connect_fd to create SSL connections, throwing out possibly important data about the other end of the connection (hostname, port number) in the process. In the interests of keeping this data intact, I propose adding a purple_ssl_connect_proxyconn that will create an SSL connection around a previously existing ProxyConnection? instead of ripping out its file descriptor and starting anew.

Issues

• Jabber (and possibly others) use the purple_ssl_connect_fd function to build an SSL connection over a previously existing ProxyConnection?. Since all the SSL side sees is the file descriptor in this case, hostname verification is impossible. (29 May)
• talk.google.com gives back a gmail.com certificate?! (29 May)

Resolved Issues

• It looks like PKCS12 (the certificate import/export format) is supported by both libNSS and GnuTLS.

TODO

• General paranoia
• Look at how the SILC prpl does its key management, especially the organization of the API used to check certs and interact with the user to verify them.
• Add some way of passing useful error messages back up out of the SSL interface (23 May)
• Fix purple_ssl_init in sslconn.c; it doesn't do anything (23 May)
  • Talking to nosnilmot suggests that this ought to just be removed outright (24 May)
• Figure out libNSS everything. (25 May)
• Why am I getting single-byte serial numbers from servers? (25 May)
• Work out how to use Glib functions for time checking on certificates. (29 May)
• Stall the timeouts on the TCP connection while waiting for user input on SSL? (29 May)
• Worry about ensuring that plugins don't kill in-use ciphers/certschemes when unloaded? (29 May)
• GnuTLS and NSS should probably be configured to use g_malloc and g_free for paranoia's sake (1 June)

Tasks done

• Figure out how to get key fingerprints out of GnuTLS (25 May, 25 May))

Status

CertificateScheme?

Member	Backend (GnuTLS)	Backend (NSS)	libpurple frontend
import_certificate	Written, untested, unexposed	Not started	Not started
destroy_certificate	Written, untested, unexposed	Not started	Not started

1 June 2007

Well, I'm not so sure about the API structure now. It seems so complex that I can't get a good handle on it or where to start. I need to think about this more; in the meantime, I am implementing some of the logic that I know that the SSL plugins will need to provide, such as functions to load certificates from files.

30 May 2007

I think that I have enough of the API planned out that I can begin implementing it. There may be some further separation of the CertificateScheme? structure, but I think that most of the backend functions are ready to be written into the SSL plugin.

29 May 2007

With some prodding from Ethan, a lot of stuff came together for me design-wise today. I got a substantial part of the API changes laid out.

25 May 2007

Divergence point reached. With the addition of purple_base16_encode_chunked, my changes will force at least a minor version increment. Slapped some code into the GnuTLS SSL plugin and looked at the certificate characteristics coming back. But why am I getting single-byte serial number values back? How large should these serial numbers be?

23 May 2007

Using "Document the SSL interface as it exists now" as an excuse to build a branch and learn Doxygen

17 May 2007

Reading documentation. Lots of it.