leekspin.tls

Utilities for working with OpenSSL x509 certificates and their keypairs.

exception OpenSSLInvalidFormat

Bases: exceptions.Exception

Raised if the specified file format is unsupported by OpenSSL.

attachKey(key, cert, selfsign=True, digest='sha1', pem=False)

Attach a key to a cert and optionally self-sign the cert.

Parameters:

• key (OpenSSL.crypto.PKey) – A previously generated key, used to generate the other half of the keypair.
• cert (OpenSSL.crypto.X509) – A TLS certificate without a public key attached to it, such as one created with createTLSCert().
• selfsign (bool) –

  If True, use the key to self-sign the cert. Note that if bool=True, and you attempt to export the public key of a cert (e.g. in order to create another cert which only holds the public key), this function will raise several nasty OpenSSL errors. Instead, to get the only public key within an x509 certificate, use public_key and/or public_cert from this example:

  secret_key = createRSAKey()
  secret_cert = attachKey(secret_key, createTLSCert(selfsign=True))
  public_key = secret_cert.get_pubkey()
  public_cert = attachKey(public_key, createTLSCert, selfsign=False)
  

  Otherwise, if you only called this function once, i.e. if you use the secret_cert in the previous example, it would contain both halves of the RSA keypair. /me glares at the PyOpenSSL API designers Indempotence, bitches, it is a thing!

• digest (str) – The digest to use. Check your OpenSSL installation to see which are supported. We pretty much only care about 'sha1' and 'sha256' here.
• pem (bool) –

  If True, return a 3-tuple of PEM-encoded strings, one for each of (certificate, private_key, public_key), where:

  • certificate is the original cert with the key attached,
  • private_key is the private RSA modulus, primes, and exponents exported from the cert, and
  • public_key is the public RSA modulus exported from the cert.

Warning

Enabling the pem parameter when passing in a key which has only the public RSA modulus (as described above) will result in nasty OpenSSL errors. Trust me, you do not want to try to parse OpenSSL’s errors.

Raises:An infinite, labyrinthine mire of non-Euclidean OpenSSL errors with non-deterministic messages and self-referential errorcodes, tangled upon itself in contempt of sanity, hope, and decent software engineering practices. Returns:If pem is True, then the values described there are returned. Otherwise, returns the cert with the key attached to it.

createTLSCert(lifetime=None)

Create a TLS certificate.

Parameters:lifetime (int) – The time, in seconds, that the certificate should remain valid for. Return type:OpenSSL.crypto.X509 Returns:A certificate, unsigned, and without a key attached to it.

createTLSLinkCert(lifetime=7200)

Create a certificate for the TLS link layer.

The TLS certificate used for the link layer between Tor relays, and between clients and their bridges/guards, has a shorter lifetime than the other certificates. Currently, in Tor, these certificates expire after two hours.

Parameters:lifetime (int) – The time, in seconds, that the certificate should remain valid for. Return type:OpenSSL.crypto.X509 Returns:A certificate, unsigned, and without a key attached to it.

getPublicKey(cert, fileformat='PEM')

Retrieve the PEM public key, with Tor headers, from a certificate.

Parameters:

• cert (OpenSSL.crypto.X509) – A certificate with an attached key.
• fileformat (str) – One of 'PEM' or 'ASN1'.

Return type:

str

Returns:

The public key in the specified fileformat.

getPrivateKey(key, fileformat='PEM')

Retrieve the PEM public key, with Tor headers, from a certificate.

Parameters:

• key (OpenSSL.crypto.PKey) – A certificate with an attached key.
• fileformat (str) – One of 'PEM' or 'ASN1'.

Return type:

str

Returns:

The private key in the specified fileformat.