Certificate
***********

Parsing for Tor Ed25519 certificates, which are used to for a variety
of purposes…

   * validating the key used to sign server descriptors

   * validating the key used to sign hidden service v3 descriptors

   * signing and encrypting hidden service v3 indroductory points

New in version 1.6.0.

**Module Overview:**

   Ed25519Certificate - Ed25519 signing key certificate
     | +- Ed25519CertificateV1 - version 1 Ed25519 certificate
     |      |- is_expired - checks if certificate is presently expired
     |      |- signing_key - certificate signing key
     |      +- validate - validates a descriptor's signature
     |
     |- from_base64 - decodes a base64 encoded certificate
     |- to_base64 - base64 encoding of this certificate
     |
     |- unpack - decodes a byte encoded certificate
     +- pack - byte encoding of this certificate

   Ed25519Extension - extension included within an Ed25519Certificate

stem.descriptor.certificate.CertType(enum)

   Purpose of Ed25519 certificate. For more information see…

      * cert-spec.txt section A.1

      * rend-spec-v3.txt appendix E

   Deprecated since version 1.8.0: Replaced with
   "stem.client.datatype.CertType"

   +--------------------------+---------------------------------------------------------+
   | CertType                 | Description                                             |
   +==========================+=========================================================+
   | **SIGNING**              | signing key with an identity key                        |
   +--------------------------+---------------------------------------------------------+
   | **LINK_CERT**            | TLS link certificate signed with ed25519 signing key    |
   +--------------------------+---------------------------------------------------------+
   | **AUTH**                 | authentication key signed with ed25519 signing key      |
   +--------------------------+---------------------------------------------------------+
   | **HS_V3_DESC_SIGNING**   | hidden service v3 short-term descriptor signing key     |
   +--------------------------+---------------------------------------------------------+
   | **HS_V3_INTRO_AUTH**     | hidden service v3 introductory point authentication key |
   +--------------------------+---------------------------------------------------------+
   | **HS_V3_INTRO_ENCRYPT**  | hidden service v3 introductory point encryption key     |
   +--------------------------+---------------------------------------------------------+

stem.descriptor.certificate.ExtensionType(enum)

   Recognized exception types.

   +----------------------+-------------------------------------------+
   | ExtensionType        | Description                               |
   +======================+===========================================+
   | **HAS_SIGNING_KEY**  | includes key used to sign the certificate |
   +----------------------+-------------------------------------------+

stem.descriptor.certificate.ExtensionFlag(enum)

   Flags that can be assigned to Ed25519 certificate extensions.

   +------------------------+-----------------------------------------------------+
   | ExtensionFlag          | Description                                         |
   +========================+=====================================================+
   | **AFFECTS_VALIDATION** | extension affects whether the certificate is valid  |
   +------------------------+-----------------------------------------------------+
   | **UNKNOWN**            | extension includes flags not yet recognized by stem |
   +------------------------+-----------------------------------------------------+

class stem.descriptor.certificate.Ed25519Extension(ext_type, flag_val, data)

   Bases: "stem.client.datatype.Field"

   Extension within an Ed25519 certificate.

   Variables:
      * **type** (*stem.descriptor.certificate.ExtensionType*) –
        extension type

      * **flags** (*list*) – extension attribute flags

      * **flag_int** (*int*) – integer encoding of the extension
        attribute flags

      * **data** (*bytes*) – data the extension concerns

   pack()

      Encodes field into bytes.

      Returns:
         **bytes** that can be communicated over Tor’s ORPort

      Raises:
         **ValueError** if incorrect type or size

   static pop(content)

      Decodes bytes as this field type, providing it and the
      remainder.

      Parameters:
         **packed** (*bytes*) – content to decode

      Returns:
         tuple of the form (unpacked, remainder)

      Raises:
         **ValueError** if packed data is malformed

class stem.descriptor.certificate.Ed25519Certificate(version)

   Bases: "object"

   Base class for an Ed25519 certificate.

   Variables:
      * **version** (*int*) – certificate format version

      * **encoded** (*unicode*) – base64 encoded ed25519 certificate

   static unpack(content)

      Parses a byte encoded ED25519 certificate.

      Parameters:
         **content** (*bytes*) – encoded certificate

      Returns:
         "Ed25519Certificate" subclsss for the given certificate

      Raises:
         **ValueError** if certificate is malformed

   static from_base64(content)

      Parses a base64 encoded ED25519 certificate.

      Parameters:
         **content** (*str*) – base64 encoded certificate

      Returns:
         "Ed25519Certificate" subclsss for the given certificate

      Raises:
         **ValueError** if content is malformed

   pack()

      Encoded byte representation of our certificate.

      Returns:
         **bytes** for our encoded certificate representation

   to_base64(pem=False)

      Base64 encoded certificate data.

      Parameters:
         **pem** (*bool*) – include PEM header/footer, for more
         information see RFC 7468

      Returns:
         **unicode** for our encoded certificate representation

   static parse(content)

class stem.descriptor.certificate.Ed25519CertificateV1(cert_type=None, expiration=None, key_type=None, key=None, extensions=None, signature=None, signing_key=None)

   Bases: "stem.descriptor.certificate.Ed25519Certificate"

   Version 1 Ed25519 certificate, which are used for signing tor
   server descriptors.

   Variables:
      * **type** (*stem.client.datatype.CertType*) – certificate
        purpose

      * **type_int** (*int*) – integer value of the certificate
        purpose

      * **expiration** (*datetime*) – expiration of the certificate

      * **key_type** (*int*) – format of the key

      * **key** (*bytes*) – key content

      * **extensions** (*list*) – "Ed25519Extension" in this
        certificate

      * **signature** (*bytes*) – certificate signature

   Parameters:
      * **signature** (*bytes*) – pre-calculated certificate
        signature

      * **signing_key**
        (*cryptography.hazmat.primitives.asymmetric.e
        d25519.Ed25519PrivateKey*) – certificate signing key

   pack()

      Encoded byte representation of our certificate.

      Returns:
         **bytes** for our encoded certificate representation

   static unpack(content)

      Parses a byte encoded ED25519 certificate.

      Parameters:
         **content** (*bytes*) – encoded certificate

      Returns:
         "Ed25519Certificate" subclsss for the given certificate

      Raises:
         **ValueError** if certificate is malformed

   is_expired()

      Checks if this certificate is presently expired or not.

      Returns:
         **True** if the certificate has expired, **False** otherwise

   signing_key()

      Provides this certificate’s signing key.

      New in version 1.8.0.

      Returns:
         **bytes** with the first signing key on the certificate, None
         if not present

   validate(descriptor)

      Validate our descriptor content matches its ed25519 signature.
      Supported descriptor types include…

         * "RelayDescriptor"

         * "HiddenServiceDescriptorV3"

      Parameters:
         **descriptor** (*stem.descriptor.__init__.Descriptor*) –
         descriptor to validate

      Raises:
         * **ValueError** if signing key or descriptor are invalid

         * **TypeError** if descriptor type is unsupported

         * **ImportError** if cryptography module or ed25519 support
           unavailable
