diff --git a/manual/acp/cmd_auth.md b/manual/acp/cmd_auth.md new file mode 100644 index 0000000..7a4f9f2 --- /dev/null +++ b/manual/acp/cmd_auth.md @@ -0,0 +1,72 @@ +# Policy Command Authentication + +In SourceHub, a Policy is defined alongside a set of relationships, which are used to derive authorization decisions for the Policy. +Relationships in a Policy are mutate (created, deleted or updated) through a Policy Command. +The command is created and sent by the Policy end users (actors) directly (as opposed to an administrator as is often the case in Access Control systems). + +In order to execute these commands, it's necessary to authenticate the entity sending them. +As it is the end user crafting said commands, actor authentication may be completely isolated from SourceHub and Tx authentcation. + +Currently, there are 3 supported authentication schemes for Policy Commands: direct, signed command and Bearer. + +## Direct +TODO + +## Signed +TODO + +## Bearer + +Bearer Authentication is done through a JWS. +A JWS is a signed JSON object containing "claims", which contain data identifying the user. + +ACP Bearer JWSs are different from commonly used JWS in that they are self signed (as opposed to generated by party A and used by party B). +The JWS MUST contain the following claims: `iss`, `exp`, `iat` and `authorized_account`, each claim will be detailed further on. +All the aforementioned claims MUST be present in the JWS. + +### Claims + +The `exp` (expires) and `isa` (issued at) claims are used as defined in the JWT RFC, an Unix time stamp (ie seconds since the epoch). + +The `iss` claim is as defined by the JWT RFC, it identifies the entity that issued the JWS through a string. +This string MUST be the DID of the Actor issuing the JWS. +The DID MUST resolve to a DID Document containing a Verification Method which is a Public Key. +This public key is used to validate the JWS signature. + +The `authorized_account` claim MUST contain a valid SourceHub address (ie a bech32 encoded string with the `source` prefix). +The address specified in this claim is used to limit which account can use the Bearer JWS. +A Policy Cmd is only accepted and processed if it is submitted in a Tx signed by the SAME account as the one set in the claim. +This is done to prevent mallicious actors from extracting Bearer JWSs from the public ledger and impersonating an Actor. + +The following is an example of a acceptable Bearer JWS payload: +```json + { + "iss": "did:key:z6MkkHsQbp3tXECqmUJoCJwyuxSKn1BDF1RHzwDGg9tHbXKw", + "authorized_account": "source12frvft2an4sjrdlvjhjunq9m7j0ygaev05crmh", + "iat": 1718814750, + "exp": 1718815650 +} +``` + +### JWS Signature and Serialization and Headers + +The JWS MUST be signed by a private key whose public key is resolvable through the did specified in the `iss` claim. + +The signed JWS MUST be serialized using the compact serialization format. +Bearer JWSs serialized following the JSON Serialization format will be rejected. + +All JOSE Header specified in the Bearer JWS are ignored (eg `jku`, `jwk`, `kid`, `x5u`). +The key used during validation is the one resolved from the issuer did. + +The following is an example of a valid Bearer JWS: + +``` +eyJhbGciOiJFZERTQSJ9.eyJpc3MiOiJkaWQ6a2V5Ono2TWtrSHNRYnAzdFhFQ3FtVUpvQ0p3eXV4U0tuMUJERjFSSHp3REdnOXRIYlhLdyIsImF1dGhvcml6ZWRfYWNjb3VudCI6InNvdXJjZTEyZnJ2ZnQyYW40c2pyZGx2amhqdW5xOW03ajB5Z2FldjA1Y3JtaCIsImlhdCI6MTcxODgxNDc1MCwiZXhwIjoxNzE4ODE1NjUwfQ.ZW0CLlDU2431FQrqNXxX-lI8aNnjTYPclj-QJVCc8Pqqs3vwqVxKPDSss9dTEcqLCrLxhlGr5kuIFblrhy8NDg +``` + +### Notes for SourceHub developers + +The Bearer JWS uses the standard timestamping mechanisms defined in JWT (`iat` and `exp`) to ease user adoption. +Note however that under no circumstance the validation must rely under the local time of the machine running sourcehub. +The `Block Time` (available through the sdk ctx) MUST be used as the reference time in the system. +Due to clock skew, this is necessary to maintain the deterministic execution of the blockchain. diff --git a/manual/acp/readme.md b/manual/acp/readme.md new file mode 100644 index 0000000..38f3284 --- /dev/null +++ b/manual/acp/readme.md @@ -0,0 +1 @@ +# ACP Module Manual \ No newline at end of file diff --git a/manual/readme.md b/manual/readme.md new file mode 100644 index 0000000..282d780 --- /dev/null +++ b/manual/readme.md @@ -0,0 +1 @@ +# SourceHub Manual \ No newline at end of file