Nextcloud PHP API (master)

ISignatureManager
in

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

Quick description of the signature, added to the headers { "(request-target)": "post /path", "content-length": 385, "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="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.

This interface can be used to inject SignatureManager in your code:

   public function __construct(
       private ISignatureManager $signatureManager,
   ) }

instead obtained from ISignatureManager::getIncomingSignedRequest.

Tags
since
33.0.0
Attributes
#[Consumable]
$since: '33.0.0'

Table of Contents

Methods

extractIdentityFromUri()  : string
returns hostname:port extracted from an uri
generateKeyIdFromConfig()  : string
returns a fully formatted keyId, based on a fix hostname and path
getIncomingSignedRequest()  : IIncomingSignedRequest
Extracting data from headers and body from the incoming request.
getOutgoingSignedRequest()  : IOutgoingSignedRequest
Preparing signature (and headers) to sign an outgoing request.
getSignatory()  : Signatory
returns remote signatory stored in local database, based on the remote host.
signOutgoingRequestIClientPayload()  : array<string|int, mixed>
Complete the full process of signing and filling headers from payload when generating an outgoing request with IClient

Methods

extractIdentityFromUri()

returns hostname:port extracted from an uri

public extractIdentityFromUri(string $uri) : string
Parameters
$uri : string
Tags
throws
IdentityNotFoundException

if identity cannot be extracted

since
33.0.0
Return values
string

generateKeyIdFromConfig()

returns a fully formatted keyId, based on a fix hostname and path

public generateKeyIdFromConfig(string $path) : string
Parameters
$path : string
Tags
throws
IdentityNotFoundException

if hostname is not set

since
33.0.0
Return values
string

getIncomingSignedRequest()

Extracting data from headers and body from the incoming request.

public getIncomingSignedRequest(ISignatoryManager $signatoryManager[, string|null $body = null ]) : IIncomingSignedRequest

Compare headers and body to confirm authenticity of remote instance. Returns details about the signed request or throws exception.

Should be called from Controller.

Parameters
$signatoryManager : ISignatoryManager

used to get details about remote instance

$body : string|null = null

if NULL, body will be extracted from php://input

Tags
throws
IncomingRequestException

if anything looks wrong with the incoming request

throws
SignatureNotFoundException

if incoming request is not signed

throws
SignatureException

if signature could not be confirmed

since
33.0.0
Return values
IIncomingSignedRequest

getOutgoingSignedRequest()

Preparing signature (and headers) to sign an outgoing request.

public getOutgoingSignedRequest(ISignatoryManager $signatoryManager, string $content, string $method, string $uri) : IOutgoingSignedRequest

Returns a IOutgoingSignedRequest containing all details to finalise the packaging of the whole payload

Parameters
$signatoryManager : ISignatoryManager
$content : string

body to be signed

$method : string

needed in the signature

$uri : string

needed in the signature

Tags
since
33.0.0
Return values
IOutgoingSignedRequest

getSignatory()

returns remote signatory stored in local database, based on the remote host.

public getSignatory(string $host[, string $account = '' ]) : Signatory
Parameters
$host : string

remote host

$account : string = ''

linked account, should be used when multiple signature can exist for the same host

Tags
throws
SignatoryNotFoundException

if entry does not exist in local database

since
33.0.0
Return values
Signatory

signOutgoingRequestIClientPayload()

Complete the full process of signing and filling headers from payload when generating an outgoing request with IClient

public signOutgoingRequestIClientPayload(ISignatoryManager $signatoryManager, array<string|int, mixed> $payload, string $method, string $uri) : array<string|int, mixed>
Parameters
$signatoryManager : ISignatoryManager
$payload : array<string|int, mixed>

original payload, will be used to sign and completed with new headers with signature elements

$method : string

needed in the signature

$uri : string

needed in the signature

Tags
since
33.0.0
Return values
array<string|int, mixed> —

new payload to be sent, including original payload and signature elements in headers


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results