security.html

<h2>Security Considerations</h2>
<section>
    <h3>Secure communication</h3>
    <p>All the messages in this protocol (except for a connection invitation that requires no security, by design)
        must be sent encrypted, using the encryption format specified in <a target="aries"
                href="https://github.com/hyperledger/aries-rfcs/blob/master/features/0019-encryption-envelope/README.md">
            DIDComm's encryption envelope</a>. This gives strong guarantees about the confidentiality and integrity of
        exchanged data, regardless of the transport mechanism used to transmit the messages.</p>
</section>
<section>
    <h3>Proof of Control</h3>
    <p>Because peer DIDs are generated from an <a href="#namestring-generation-method">algorithm</a> that includes the values of their initial public key(s)
        as input, they cannot be created without the creator controlling them. As mentioned earlier, this prevents
        man-in-the-middle attacks at the time of creation. A man-in-the-middle attacker might still try to exchange 
		the public key(s) in a DID Doc, while keeping the DID the same. If unnoticed, this would bind a DID generated
		by an honest party to the attacker's public key(s). To prevent this, the receiver of a freshly generated peer
		DID and DID Doc must verify that the DID was properly generated using the <a href="#namestring-generation-method">algorithm</a>.
		This check is required when the received (DID, DID Doc) pair was not otherwise authenticated, which is the case
		for the exchange request during <a href="#create-register">peer DID Exchange</a>.
    </p>
</section>
<section>
    <h3>Entropy</h3>
    <p>
        Since keys must be created from keys generated by a secure random number generator, they are guaranteed
        to be unpredictable and globally unique at creation time.</p>
</section>
<section>
    <h3>Key Management</h3>
    <p>Keys used to control peer DIDs, or keys authorized to communicate and update the DID docs
        for peer DIDs, should be managed according to best practices for DKMS, as described in
        <a target="aries" href="https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0051-dkms/dkms-v4.md">
        the DKMS spec</a>. See the <a href="#static-and-key-rotation">note about key rotation and static-DID-only
        support</a> in the <a href="#impl">Implementation section</a>.
    </p>
    <p><a target="sgl" href="https://evernym.github.io/sgl/docs/reference.html#rules">SGL rules</a> are powerful and
        flexible, and should be used to implement best practices.</p>
</section>

<section>
    <h4>Handling the trust-on-first-use (TOFU) problem</h4>
    <p>
        The trust-on-first-use is described in detail in its
        <a target="wikipedia" href="https://en.wikipedia.org/wiki/Trust_on_first_use">Wikipedia article</a>.
        In brief, the TOFU problem occurs because it's not possible to verify, with only a public key,
        who is the owner of a private key. This lack of knowledge enables MITM attacks.
    </p>
    <p>
        There are two separate ways to handle the TOFU problem with the peer DID method spec. The more common
        variant is to bootstrap based upon a trusted third party channel. The second approach is made
        possible by verifiable credentials.
    </p>

    <section>
    <h5>Bootstrap from Trusted Third Party Channel</h5>
    <p>
        The core premise of using an out of band channel based solution is to be able to bootstrap the new
        channel of communication from a third party trusted channel of communication. In many cases this is an
        adequette solution, and in others it may require additional pieces of information in order to establish
        trust, such as a verifiable credential exchange.
    </p>
    <p>
        This method has been used in previous systems to rely on in person interactions to verify some piece of
        information. For example, in some end to end messaging apps, they rely on key fingerprinting which
        require a use to verify that a key fingerprint sent over a trusted communication channel or viewed in
        person (usually a number) matches between the two parties. This method allows user to verify that the
        channel hasn't been Man in the Middle (MITM) attacked.
    </p>
    <p>
        There's also ways that the user experience could be improved using this same security process. For
        example, a <a target="superuser" href="https://superuser.com/questions/22535/
                what-is-randomart-produced-by-ssh-keygen">randomart image</a> could be embedded into a QR code and then
        the randomart image could be displayed on the users device as well. The user would then be required to
        verify the image displayed on the user's device is the same as the one embedded in the QR code. This is
        a great way to handle short-lived, ephemeral connections such as unlocking a door while being sure the
        connection has not been MITM attacked.
    </p>
    </section>

    <section>
    <h5>Binding Verifiable Credentials with Public Keys</h5>
    <p>
        A verifiable credential method is a new approach to bootstrapping trust entirely within the connection.
        The idea behind this is that a verifiable credential issued by a third party can be combined with a
        self-attested attribute in a credential proof to link the possession of the key to a verifiable
        credential.
    </p>
    <p>
        The reason this works is because the cryptographic proof generated by the holder binds the attributes
        provided from a verifiable credential with the self-attested public key attribute. This is done in a way
        that only the holder could generate this proof and therefore the recipient can identify all keys
        recognized by the sender while also being able to identify attributes about the sender in a way that a
        trust decision can be made. If Bob detects that the key that Alice
        provides in the DID Document is different than the key he received in the Credential Proof, then he’s
        able to detect that some aspect of the setup was done incorrectly or was tampered with. This is good
        enough indication that Bob SHOULD NOT trust this connection and SHOULD scrap it and reset.
    </p>
    <p>
        One thing of particular importance in this method is that the credential requested must be unique enough
        such that a malicious party cannot also generate a satisfactory proof. If a malicious party does holder
        a credential which is not unique enough then the malicious party could conduct a MITM attack. This
        attack would require a malicious party to first intercept the plaintext DID Document sent in the
        invitation during the create operation, change the key, endpoint, and signature of the invitation. Then
        the malicious party must generate a proof that meets the request of the verifier and impersonate the
        sender.
    </p>
    <p>
        In the majority of security threat models the use of a unique proof which includes all public keys
        listed in the DID Document as self attested attributes in the proof. As recommendation, a unique proof
        SHOULD include proof attributes issued by at least 2 unique issuers. This method SHOULD be satisfactory
        for high value financial transactions while accommdating for internet wide scale. If a threat model
        needs greater assurances, the parties SHOULD meet in person for a connection setup.
    </p>
    </section>
</section>