docs: def verifyCertificateAllowed(self,
                                   ourAddress,
                                   theirAddress):
          """
          Check that the cert currently in use by this transport is valid to
          claim that the connection offers authorization for this host speaking
          for C{ourAddress}, to a host speaking for C{theirAddress}.  The remote
          host (the one claiming to use theirAddress) may have a certificate
          which is issued for the domain for theirAddress or the full address
          given in theirAddress.
  
          This method runs B{after} cryptographic verification of the validity of
          certificates, although it does not perform any cryptographic checks
          itself.  It depends on SSL connection handshaking - *and* the
          particular certificate lookup logic which prevents spoofed Issuer
          fields, to work properly.  However, all it checks is the X509 names
          present in the certificates matching with the application-level
          security claims being made by our peer.
  
          An example of successful verification, because both parties have
          properly signed certificates for their usage from the domain they
          have been issued::
  
              our current certficate:
                  issuer: divmod.com
                  subject: glyph@divmod.com
              their current certificate:
                  issuer: twistedmatrix.com
                  subject: exarkun@twistedmatrix.com
              Arguments to verifyCertificateAllowed:
                  ourAddress: glyph@divmod.com
                  theirAddress: exarkun@twistedmatrix.com
              Result of verifyCertificateAllowed: None
  
          An example of rejected verification, because domain certificates are
          always B{self}-signed in Q2Q; verisign is not a trusted certificate
          authority for the entire internet as with some other TLS
          implementations::
  
              our current certificate:
                  issuer: divmod.com
                  subject: divmod.com
              their current certificate:
                  issuer: verisign.com
                  subject: twistedmatrix.com
              Arguments to verifyCertificateAllowed:
                  ourAddress: divmod.com
                  theirAddress: twistedmatrix.com
              Result of verifyCertificateAllowed: exception VerifyError raised
  
          Another example of successful verification, because we assume our
          current certificate is under the control of this side of the
          connection, so *any* claimed subject is considered acceptable::
  
              our current certificate:
                  issuer: divmod.com
                  subject: divmod.com
              their current certificate:
                  issuer: divmod.com
                  subject: glyph@twistedmatrix.com
              Arguments to verifyCertificateAllowed:
                  ourAddress: divmod.com
                  theirAddress: glyph@twistedmatrix.com
              Result of verifyCertificateAllowed: None
  
          Another example of successful verification, because the user is
          claiming to be anonymous; there is also a somewhat looser
          cryptographic check applied to signatures for anonymous
          connections::
  
              our current certificate:
                  issuer: divmod.com
                  subject: divmod.com
              their current certificate:
                  issuer: @
                  subject: @
              arguments to verifyCertificateAllowed:
                  ourAddress: divmod.com
                  theirAddress: @
              Result of verifyCertificateAllowed: None
  
          Accept anonymous connections with caution.
  
          @param ourAddress: a L{Q2QAddress} representing the address that we are
          supposed to have authority for, requested by our peer.
  
          @param theirAddress: a L{Q2QAddress} representing the address that our
          network peer claims to be communicating on behalf of.  For example, if
          our peer is foobar.com they may claim to be operating on behalf of any
          user @foobar.com.
  
          @raise: L{VerifyError} if the certificates do not match the
          claimed addresses.
          """
  
          # XXX TODO: Somehow, it's got to be possible for a single cluster to
          # internally claim to be agents of any other host when issuing a
          # CONNECT; in other words, we always implicitly trust ourselves.  Also,
          # we might want to issue anonymous CONNECTs over unencrypted
          # connections.
  
          # IOW: *we* can sign a certificate to be whoever, but the *peer* can
          # only sign the certificate to be the peer.
  
          # The easiest way to make this work is to issue ourselves a wildcard
          # certificate.
  
          if not self.authorized:
              if theirAddress.domain == '':
                  # XXX TODO: document this rule, anonymous connections are
                  # allowed to not be authorized because they are not making any
                  # claims about who they are
  
                  # XXX also TODO: make it so that anonymous connections are
                  # disabled by default for most protocols
                  return True
              raise VerifyError("No official negotiation has taken place.")
  
          peerCert = Certificate.peerFromTransport(self.transport)
          ourCert = self.hostCertificate
  
          ourClaimedDomain = ourAddress.domainAddress()
          theirClaimedDomain = theirAddress.domainAddress()
  
          # Sanity check #1: did we pick the right certificate on our end?
          if not ourClaimedDomain.claimedAsIssuerOf(ourCert):
              raise VerifyError(
                  "Something has gone horribly wrong: local domain mismatch "
                  "claim: %s actual: %s" % (ourClaimedDomain,
                                            ourCert.getIssuer()))
          if theirClaimedDomain.claimedAsIssuerOf(peerCert):
              # Their domain issued their certificate.
              if (theirAddress.claimedAsSubjectOf(peerCert) or
                  theirClaimedDomain.claimedAsSubjectOf(peerCert)):
                  return
          elif ourClaimedDomain.claimedAsIssuerOf(peerCert):
              # *our* domain can spoof *anything*
              return
          elif ourAddress.claimedAsIssuerOf(peerCert):
              # Neither our domain nor their domain signed this.  Did *we*?
              # (Useful in peer-to-peer persistent transactions where we don't
              # want the server involved: exarkun@twistedmatrix.com can sign
              # glyph@divmod.com's certificate).
              return
  
          raise VerifyError(
              "Us: %s Them: %s "
              "TheyClaimWeAre: %s TheyClaimTheyAre: %s" %
              (ourCert, peerCert,
               ourAddress, theirAddress))