Rob Behnke
May 2nd, 2023
A Daml application on a Daml ledger implements the legal architecture of a business model, and it also has to be operationally safe. This means that the platform must both a) enforce the rights and obligations stemming from the legal relationships between their users and b) prevent malicious use.
In the context of this post, we will call the former requirement “front door security”, and the latter “back door security”, by “security” meaning both authorization and privacy guarantees.
(As an analogy: a hotel’s IT system must make sure that all customers entering through the “front door”, meaning checking in at the front desk have access to precisely those services for which they are entitled, and also prevent malicious actors from circumventing the front desk and trying to access the hotel through the “back door”.)
The Daml/Canton platform shines on both sides. In this post, we will explain both the “front-door” and the “back-door” guarantees the system provides.
The Daml/Canton platform clearly separates real-life actors from their on-ledger representations. The link between the actors and their representations is the access token which must be attached to transaction requests. The advantage of this separation is that the tokens don’t penetrate deep into the system: they are checked at the edge of the ledger, and all authorization and privacy work is done by the Daml model.
Real-life actors are represented by ledger parties. Ledger parties are data objects, whose most important part is a unique id. Ledger parties are stored on the ledger independently from smart contracts. They must be allocated by an admin before their owners can perform any read or write actions against the ledger. (There are some additional details concerning ledger parties like distributed hosting and user management which we will ignore for now.)
The Daml/Canton platform outsources authentication to external OAuth service providers. As mentioned, every client application which wants to interact with a Daml ledger needs to attach a signed access token to the transaction request, containing the party id for the ledger party, on behalf of which it wants to read or write.
The Daml ledger will check:
a) the signature on the token against the public key of the OAuth service provider specified by the ledger operator
b) expiry
and c) authorization
For linking the ledger parties to some real-life entities, some KYC (know your customer) system might be needed. The KYC system may be represented by a special ledger party trusted by all users which signs identity contracts, containing the attributes of the linked real-life entities owning the ledger parties.
The authorization and visibility rules for the ledger parties are specified in the contract templates. The contract payload specifies (among other details) the roles ledger parties will fulfill in the legal relationship. Let’s review a simple example: A ticket embodies a legal relationship between the issuer and owner of the ticket, and the usher who will check its validity. The ledger parties corresponding to these roles are specified in the contract payload. The contract template then specifies the substitution rules for the stakeholder parties, telling that the owner and the issuer must be signatories, the usher will be an observer, the owner can give away the ticket specifying a new owner without waiting for the issuer’s consent, and the usher can “take” the ticket (invalidate it preventing further use when admitting the owner to the show).
The Daml ledger model guarantees that the handling of smart contracts conforms to the rules for contract formation in contract law, as described in this chapter of the Daml docs, and to the rules of need-to-know basis privacy, as described in this chapter. The certificates acquired by Digital Asset guarantee that the platform is a faithful implementation of the ledger model described in the docs.
But how can we make sure that a Daml ledger indeed represents the legal content intended by its users?
In order to know what rights and obligations for which ledger parties (and by extension, for the real-life owners of the ledger parties) are stored on the ledger, we have to look for two things: 1) contract instances on the ledger, and 2) the source code of the Daml model.
The contract instances, stored on the ledger, contain the data content (payload) of the contract, the id of the template, from which the contract was created (containing the unique id of the DAR package, the archive version of the Daml package containing said template), the signatories of the contract (ledger parties which authorized the creation of the contract, either directly or indirectly), and the observers of the contract (ledger parties which have the right to see the contract in their ledger projections).
Theoretically, every contract instance on the ledger could contain in the optional “agreement” field a parameterized legal prose formulation of the rights and obligations it represents. In practice though, this field is rarely (if ever) used, maybe because there is no automated way of checking if the agreement text template correctly formulates the rights and obligations implemented by the contract choices.
Without the agreement text, the contract instances on the ledger don’t tell what choices are present for which ledger parties and what are their consequences. In order to know this, we have to consult the source code of the Daml model, containing all the contract templates.
Together with a Daml ledger, this source code should be made available for inspection and download (as is the case with Daml Hub, the cloud-based platform for running Daml ledgers). Once we can put our hands on the Daml source code, we can build it, extract the package id from the resulting DAR file, and verify that the contract instances on the ledger were indeed created from that Daml model.
Admittedly, there is a gap between the Daml source code and the legal prose description of the legal relationships it represents. In order to fill in the gap, the collaborating parties using the ledger need to draft a traditional contract or GTC describing the legal content and have it audited by experts who know both law and Daml.
After this overview of the “front-door” guarantees provided by the platform, let’s see briefly what “back-door” guarantees the platform provides.
Back-door security is the responsibility of Canton. We won’t go into deep details about how this is achieved. Instead, we’ll refer you to some background material.
The current level of back-door privacy has been introduced with Daml SDK version 2.0, which made Canton generally available. The security features were summed up by Digital Asset in the release notes in the following way:
Security confidence regardless of the underlying infrastructure: Messages are encrypted at the participant level regardless of the underlying infrastructure—a relational database or a blockchain layer—requiring less trust in anyone who has access to information on the domain.
Increased privacy: Encrypting messages at the participant level means that the content of the transaction is hidden from anyone who has access to information on the domain.
The System Architecture FAQ / How does Canton ensure privacy? section of the docs explains in more detail how encryption exactly happens.
The enterprise edition of the Daml/Canton platform also offers the non-repudiation middleware (currently in alpha status) for making sure that the operator of a participant node cannot issue a command on behalf of any ledger user and that the user cannot repudiate the command.