Signed requests

[ArtificialOwl]

Signed Request

Signing request allows to confirm the identity of the sender.
Signing request does not encrypt nor affect its payload.
Signing request only adds metadata to the headers of the request.

Signature

The concept is to add unique metadata and sign them using a private/public key pair.
The location of the public key used to verify the signature will confirm the origin of the request.

Signature does not affect the data of the request, it only adds headers to it:

 {
     "(request-target)": "post /path",
     "content-length": 380,
     "date": "Mon, 08 Jul 2024 14:16:20 GMT",
     "digest": "SHA-256=U7gNVUQiixe5BRbp4Tg0xCZMTcSWXXUZI2\\/xtHM40S0=",
     "host": "hostname.of.the.recipient",
     "Signature": "keyId=\"https://author.hostname/key\",algorithm=\"ras-sha256\",headers=\"content-length date digest host\",signature=\"DzN12OCS1rsA[...]o0VmxjQooRo6HHabg==\""
 }

• 'content-length' is the total length of the data/content
• 'date' is the datetime the request have been initiated
• 'digest' is a checksum of the data/content
• 'host' is the hostname of the recipient of the request (remote when signing outgoing request, local on incoming request)
• 'Signature' contains the signature generated using the private key, and metadata:
  • 'keyId' is a unique id, formatted as an url. hostname is used to retrieve the public key via custom discovery
  • 'algorithm' define the algorithm used to generate signature
  • 'headers' contains a list of element used during the generation of the signature
  • 'signature' is the encrypted string, using local private key, of an array containing elements
    listed in 'headers' and their value. Some elements (content-length date digest host) are mandatory
    to ensure authenticity override protection.

(Those are the minimum required headers, some can be added via options during the process)

ISignatoryManager

Because each protocol have different ways to obtain the public key of a remote instance or entity, some part of the signing/verifying process is managed by a custom provider, one for each protocol.

• getProviderId should returns a unique string

• getOptions should returns an array that can contains those entries:

  • 'ttl' (300) is the lifetime (in secondes) of the signature
  • 'ttlSignatory' (86400*3) the cache lifetime on a remote signatory
  • 'extraSignatureHeaders' ([]) (list of extra headers to include to the signature)
  • 'algorithm' ('sha256') is the algorithm used to generate the signature
  • 'dateHeader' ("D, d M Y H:i:s T") the format of the 'date' header

• getLocalSignatory should return the local signatory, including the full (public+private) key pair.

• getRemoteSignatory should returns a remote signatory based on the requested data, must at least contains key id and public key

IKeyPairManager

IKeyPairManager contains a group of method to create/manage/store internal public/private key pair, stored as sensitive data using a lazy loaded IAppConfig variable. 2 strings app id and name are used to identify key pairs.

• generateKeyPair generate and store public/private key pair.
• hasKeyPair return if key pair is known in database.
• getKeyPair return key pair from database based on app id and name.
• deleteKeyPair delete key pair from database.

ISignatureManager

ISignatureManager is a service integrated to core that provide tools to set/get authenticity of/from outgoing/incoming requests.

• getIncomingSignedRequest extract data from the incoming request and compare headers to confirm authenticity of remote instance
• getOutgoingSignedRequest prep signature to sign an outgoing request.
• signOutgoingRequestIClientPayload is the one method to call to fully process of signing and fulfilling the payload for an outgoing request using IClient
• searchSignatory get a remote signatory from the database

[nickvergessen]

sharedSecret inside the notification is already used by some OCM messages. So this would break it. Can you take another key? Or maybe you prefix with '$#$' or something alike?

[ArtificialOwl]

this would not break it as I send the exception for the exact same reason of a missing 'sharedSecret' entry in the notifications request. The only thing is that I do this check earlier than others but I can add a prefix if you want (while I dont feel like necessary myself)

[nickvergessen]

this would not break it as I send the exception for the exact same reason of a missing 'sharedSecret' entry in the notifications request.

Nextcloud Talk is sending a data field 'sharedSecret' and you either overwrite that and it breaks Talk Federation with older servers or you need to use a different key

[nickvergessen]

By now our Entity+QBMapper pattern is widely adapted. Any reason why you didn't go for it and instead went back to doing all this manually again?

[ArtificialOwl]

no real reason other that personal preference