X509 interfaces

Replaces #1267.

**Update: simplified interfaces so the below questions are irrelevant until we expand them in future PRs**

Two outstanding questions:

- Do we want to blow up when an X509Name has multiple identical OIDs in a single Name?
- Do we want to blow up when an X509Certificate has multiple extensions with the same OID?

These are both things you Should Not Do™, but since it's all ASN.1 under the hood nothing technically prohibits the existence of certificates and names that do this.

A bit more detail than is in the PR:

- `version` will return an enum object that will correspond to v1 or v3. Leaving it an integer is a mistake many other APIs have made to their sorrow.

I've decided to go down the path of keeping the interface small and having `get_extension` and `get_item`. When the requested OID is not available we will raise the exceptions that are added here.
On Nov 24, 2014, at 2:17 PM, Paul Kehrer <notifications@github.com> wrote:
> In docs/hazmat/primitives/interfaces.rst:
> > +
> > +    .. versionadded:: 0.7
> > +
> > +    .. method:: fingerprint(algorithm)
> > +
> > +        :param algorithm: A
> > +            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
> > +            that will be used by this context.
> > +
> > +        :return: The fingerprint using the supplied hash algorithm as bytes.
> > +
> > +    .. attribute:: serial
> > +
> > +        :type: int
> > +
> > +        The serial as a Python integer.
> Serials are usually represented as hexadecimal or decimal by parsing libraries. We could return the bytes but I think we'd just end up causing a new class of bugs as people tried to convert it into what they expect.
> 

This can potentially be argued both ways. If serial numbers are taken or returned in integer form but are really stored in the certificate as bytes, you’re basically enforcing a specific encoding of that integer. In particular, you’re choosing at least endianness, and potentially also other things like either choosing a fixed integer size or choosing how you calculate the number of bytes needed. For instance, is serial number 128 encoded as ‘\x80’, ‘\x80\x00’, ‘\x00\x80’, or some other even longer value with more null bytes? I could see an argument against ‘\x80’ because it might be decoded as -128 later instead of 128 unless serial numbers are explicitly defined as unsigned, but going to multiple bytes immediately raises the endianness problem.

Leaving the serial number as a byte string avoids all of these concerns, and leaves it up to the caller to decide how to convert their serial number into a byte string. It also allows for odd encoding like binary-coded-decimal, ASCII decimal, or even non-numeric values.
-- 
Ron Frederick
ronf@timeheart.net