Add a short document that describes things to watch out for when writing Corda app code.

docs/source/index.rst

@@ -57,6 +57,7 @@ Read on to learn:
    protocol-state-machines
    oracles
    event-scheduling
+   secure-coding-guidelines
 
 .. toctree::
    :maxdepth: 2

docs/source/release-notes.rst

@@ -3,6 +3,16 @@ Release notes
 
 Here are brief summaries of what's changed between each snapshot release.
 
+Unreleased
+----------
+
+API changes:
+
+* The transaction types (Signed, Wire, LedgerTransaction) have moved to ``com.r3corda.core.transactions``. You can
+  update your code by just deleting the broken import lines and letting your IDE re-import them from the right
+  location.
+* AbstractStateReplacementProtocol.verifyProposal has changed its prototype in a minor way.
+
 Milestone 3
 -----------
 

docs/source/secure-coding-guidelines.rst

@@ -0,0 +1,47 @@
+Secure coding guidelines
+------------------------
+
+The platform does what it can to be secure by default and safe by design. Unfortunately the platform cannot
+prevent every kind of security mistake. This document describes what to think about when writing applications
+to block various kinds of attack. Whilst it may be tempting to just assume no reasonable counterparty would
+attempt to subvert your trades using protocol level attacks, relying on trust for software security makes it
+harder to scale up your operations later when you might want to add counterparties quickly and without
+extensive vetting.
+
+Protocols
+---------
+
+:doc:`protocol-state-machines` are how your app communicates with other parties on the network. Therefore they
+are the typical entry point for malicious data into your app and must be treated with care.
+
+The ``receive`` methods return data wrapped in the ``UntrustworthyData<T>`` marker type. This type doesn't add
+any functionality, it's only there to remind you to properly validate everything that you get from the network.
+Remember that the other side may *not* be running the code you provide to take part in the protocol: they are
+allowed to do anything! Things to watch out for:
+
+* A transaction that doesn't match a partial transaction built or proposed earlier in the protocol, for instance,
+  if you propose to trade a cash state worth $100 for an asset, and the transaction to sign comes back from the
+  other side, you must check that it points to the state you actually requested. Otherwise the attacker could
+  get you to sign a transaction that spends a much larger state to you, if they know the ID of one!
+* A transaction that isn't of the right type. There are two transaction types: general and notary change. If you
+  are expecting one type but get the other you may find yourself signing a transaction that transfers your assets
+  to the control of a hostile notary.
+* Unexpected changes in any part of the states in a transaction. If you have access to all the needed data, you
+  could re-run the builder logic and do a comparison of the resulting states to ensure that it's what you expected.
+  For instance if the data needed to construct the next state is available to both parties, the function to
+  calculate the transaction you want to mutually agree could be shared between both classes implementing both
+  sides of the protocol.
+
+The theme should be clear: signing is a very sensitive operation, so you need to be sure you know what it is you
+are about to sign, and that nothing has changed in the small print!
+
+Contracts
+---------
+
+Contracts are arbitrary functions inside a JVM sandbox and therefore they have a lot of leeway to shoot themselves
+in the foot. Things to watch out for:
+
+* Changes in states that should not be allowed by the current state transition. You will want to check that no
+  fields are changing except the intended fields!
+* Accidentally catching and discarding exceptions that might be thrown by validation logic.
+* Calling into other contracts via virtual methods if you don't know what those other contracts are or might do.