How can we express security constraints of an action execution?

[danaivach]

A possible way could be using the WoT Security (WoTSec) Ontology: https://www.w3.org/2019/wot/security. We should ensure that the vocabulary is not exclusive to WoT Things. The documentation of WoTSec does refer to TDs, but no TD vocabulary is used in the ontology itself.

Then, we should either define a new property, e.g. to establish a relation between an action execution and a wotsec:SecurityScheme (similar to td:hasSecurityConfiguration).

Alternatively, we can off-load the description of security constraints to hypermedia controls (e.g., see https://www.w3.org/2019/wot/hypermedia#Form).

Also, @NicoRobertIn, see here how to generally specify headers for HTTP requests: https://w3c.github.io/wot-binding-templates/bindings/protocols/http/index.html.

[NicoRobertIn]

For an endpoint with a authorization header we could expect the form to be formatted this way:

_:MyForm a hctl:Form ;
    hctl:hasTarget <https://link.to/my/endpoint> ;
    htv:methodName "GET" ;
    hctl:forContentType "application/json" ;
    htv:headers (
        [
            a htv:messageHeader ;
            http:fieldName "Authorization" ;
            http:fieldValue  "blablabla"
        ]
    ) .

And then on the ShaCL specification side we could expect the following:

_:MyEndpoint a sh:NodeShape ;
    sh:class hmas:ActionExecution ;
    sh:property [
        sh:path prov:used ;
        sh:minQualifiedShape 1 ;
        sh:maxQualifiedShape 1 ;
        sh:qualifiedValueShape [
            sh:class hctl:Form ;
            sh:property [
                sh:path hctl:forContentType ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue "application/json"
            ], [
                sh:path htv:methodName ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue "GET"
            ], [
                sh:path hctl:hasTarget ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue  <https://link.to/my/endpoint>
            ],
            [
                sh:path (
                    htv:headers
                    [sh:zeroOrMorePath rdf:rest]
                    rdf:first
                ) ;
                sh:minQualifiedShape 1;
                sh:maxQualifiedShape 1;
                sh:qualifiedValueShape [
                    sh:class htv:messageHeader ;
                    sh:property [
                        sh:path http:fieldName ;
                        sh:minCount 1 ;
                        sh:maxCount 1 ;
                        sh:hasValue "Authorization"
                    ] , [
                        sh:path http:fieldValue ;
                        sh:minCount 1 ;
                        sh:maxCount 1
                    ]
                ]
            ]
        ]
    ] .

What do you think?

[NicoRobertIn]

I made a commit in 182-uc-manufacturing with the proposed shapes and its simplification The above shape is equivalent to

_:MyEndpoint a _:ActionExecutionShape ;
    sh:property [
        a _:EndpointSpecification ;
        sh:qualifiedValueShape [
            a _:GetMethod, _:AcceptJson, _:Authorization ;
            sh:property [
                a _:TargetUrl ;
                sh:hasValue <https://link.to/my/endpoint>
            ]
        ]
    ] .

[danaivach]

@NicoRobertIn the approach is valid. Of course, it can only be used when the authorization requires the usage of headers. Should we also accept this alternative to allow usage of the WoTSec Ontology through the hctl:Form? It depends on https://www.w3.org/2019/wot/td#hasSecurityConfiguration:

<> sh:class hctl:Form ;
                sh:property [
                sh:path hctl:forContentType ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue "application/json"
            ], [
                sh:path htv:methodName ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue "GET"
            ], [
                sh:path hctl:hasTarget ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue  <https://link.to/my/endpoint>
            ] ,
            [
                sh:path td:hasSecurityConfiguration ;
                sh:minQualifiedShape 1;
                sh:maxQualifiedShape 1;
                sh:qualifiedValueShape [
                      sh:class wotsec:APIKeySecurityScheme ;
                      sh:property [
                             sh:path wotsec:in ;
                             sh:minCount 1 ;
                             sh:maxCount 1 ;
                             sh:hasValue  "HEADER"
                      ] ;
                     sh:property [
                             sh:path wotsec:name ;
                             sh:minCount 1 ;
                             sh:maxCount 1 ;
                             sh:hasValue  "Authentication"
                      ]
           ] .

cc @vcharpenay, @andreiciortea , @smnmyr

[FabienGandon]

In this issue you have identified two representations that essentially say we need to have an "Authorization" HEADER. But I can't find a criteria to say that one representation is better than the other and for me they actually end up documenting exactly the same constraint.

So I see at least three ways of proceeding:

• find a criteria to choose e.g. adoption, expressivity, easier, etc.
• write a shape that contains a disjunction and allows both
• have a battle to death between @danaivach and @NicoRobertIn (just joking)

[NicoRobertIn]

Since an artifact can validate a shape from the data and the wotsec/http/whatever shacl shape included in the resource profile, the way it is implemented does not really matter

In my opinion we should:

• implement a shortcut so that an authorization header shape is easy to do (the implementation detail does not matter)
• allow people to implement the authorization shape themselves if they are not satisfied with the ontology used for the project

[danaivach]

I agree with @NicoRobertIn that, given that security models are not on the central path of our investigation, it is better to allow for alternative representations of security schemes.

Some pros and cons of the 2 approaches: Approach 1 [+] fewer dependencies to 3rd-party ontologies (it only depends to the application-layer protocol ontology which is already needed for representing the hypermedia controls); [-] lacks expressivity and transparency: e.g., the same description in the given example could be used for the API key security scheme, but also for the Basic security scheme (it is not a good practice to not explicitly refer to the authorization type even in the case of human-readable APIs).

Approach 2 [+] uses the WoTSec ontology, which allows for explicitly specifying the authorization type for application-layer protocols that are officially supported by W3C WoT specifications (e.g. HTTPS+oauth2/bearer/basic/digest, CoAPS+psk, MQTTS+psk/basic); [-] depends on the TD ontology. This could be addressed if we define a property equivalent to td:hasSecurityConfiguration.

Neutral: Both approaches provide security details at the level of the hypermedia controls, and not at the level of the signified behavior. This could be interpreted as our intention to allocate security considerations more in the scope of the client and less in the scope of the agent.

[NicoRobertIn]

lacks expressivity and transparency: e.g., the same description in https://github.com/HyperAgents/hmas/issues/197#issuecomment-1838596561 could be used for the API key security scheme, but also for the Basic security scheme (it is not a good practice to not explicitly refer to the authorization type even in the case of human-readable APIs).

You have however a point on this. If the wotsec ontology allows to distinguish between these authentication methods, then default shortcuts should be implemented this way so that agent can capture more semantic on the authentication method and then we can also allow people to implement it the way they want