Skip to content

[stable32] docs(openapi): Fix documentation what data is verified #18450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nickvergessen merged 2 commits into from
Jun 26, 2026
Merged

[stable32] docs(openapi): Fix documentation what data is verified #18450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1e4814b
docs(openapi): Fix documentation what data is verified
nickvergessen Jun 26, 2026
f722b7b
chore(assets): Recompile assets
nickvergessen Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions lib/Controller/BotController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,8 +136,8 @@ protected function getBotFromHeaders(string $token, string $message, string $ran
#[BruteForceProtection(action: 'bot')]
#[OpenAPI(scope: 'bots')]
#[PublicPage]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the request body, signed with the shared bot secret, to verify authenticity')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the message to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the message, signed with the shared bot secret, to verify authenticity')]
public function sendMessage(string $token, string $message, string $referenceId = '', int $replyTo = 0, bool $silent = false, string $threadTitle = '', int $threadId = 0): DataResponse {
if (trim($message) === '') {
return new DataResponse(null, Http::STATUS_BAD_REQUEST);
Expand Down Expand Up @@ -227,8 +227,8 @@ public function sendMessage(string $token, string $message, string $referenceId
#[BruteForceProtection(action: 'bot')]
#[OpenAPI(scope: 'bots')]
#[PublicPage]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the request body, signed with the shared bot secret, to verify authenticity')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the reaction to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the reaction, signed with the shared bot secret, to verify authenticity')]
public function react(string $token, int $messageId, string $reaction): DataResponse {
$random = $this->request->getHeader('x-nextcloud-talk-bot-random');
$checksum = $this->request->getHeader('x-nextcloud-talk-bot-signature');
Expand Down Expand Up @@ -286,8 +286,8 @@ public function react(string $token, int $messageId, string $reaction): DataResp
#[BruteForceProtection(action: 'bot')]
#[OpenAPI(scope: 'bots')]
#[PublicPage]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the request body, signed with the shared bot secret, to verify authenticity')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-random', description: 'Random seed (at least 32 bytes) used together with the reaction to generate the SHA256-HMAC request signature')]
#[RequestHeader(name: 'x-nextcloud-talk-bot-signature', description: 'SHA256-HMAC signature over the concatenation of the random seed and the reaction, signed with the shared bot secret, to verify authenticity')]
public function deleteReaction(string $token, int $messageId, string $reaction): DataResponse {
$random = $this->request->getHeader('x-nextcloud-talk-bot-random');
$checksum = $this->request->getHeader('x-nextcloud-talk-bot-signature');
Expand Down
9 changes: 4 additions & 5 deletions lib/Controller/RecordingController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -405,8 +405,8 @@ public function stop(): DataResponse {
#[BruteForceProtection(action: 'talkRecordingSecret')]
#[OpenAPI(scope: 'backend-recording')]
#[RequireRoom]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed used to generate the request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'Checksum over the request body to verify authenticity from the recording backend', indirect: true)]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared recording secret, to verify authenticity from the recording backend', indirect: true)]
#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/recording/{token}/request-upload', requirements: [
'apiVersion' => '(v1)',
'token' => '[a-z0-9]{4,30}',
Expand Down Expand Up @@ -441,7 +441,6 @@ public function requestUpload(string $owner, string $fileName): DataResponse {
* {@see self::requestUpload()}, and only the post-processing is run.
* Otherwise the recording is read from the multipart `file` upload.
*
*
* Required capability: `recording-v1`
*
* @param ?string $owner User that will own the recording file. `null` is actually not allowed and will always result in a "400 Bad Request". It's only allowed code-wise to handle requests where the post data exceeded the limits, so we can return a proper error instead of "500 Internal Server Error".
Expand All @@ -456,8 +455,8 @@ public function requestUpload(string $owner, string $fileName): DataResponse {
#[BruteForceProtection(action: 'talkRecordingSecret')]
#[OpenAPI(scope: 'backend-recording')]
#[RequireRoom]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared recording secret, to verify authenticity from the recording backend', indirect: true)]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared recording secret, to verify authenticity from the recording backend', indirect: true)]
public function store(?string $owner, ?string $fileName = null): DataResponse {
$data = $this->room->getToken();
if (!$this->validateBackendRequest($data)) {
Expand Down
24 changes: 12 additions & 12 deletions lib/Controller/RoomController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -415,8 +415,8 @@ public function getBreakoutRooms(): DataResponse {
#[OpenAPI]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequestHeader(name: 'x-nextcloud-federation', description: 'Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function getSingleRoom(string $token): DataResponse {
try {
$isSIPBridgeRequest = $this->validateSIPBridgeRequest($token);
Expand Down Expand Up @@ -2135,8 +2135,8 @@ public function joinFederatedRoom(string $token, ?string $sessionId): DataRespon
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequireRoom]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function verifyDialInPin(string $pin): DataResponse {
if (!$this->talkConfig->isSIPConfigured()) {
return new DataResponse(null, Http::STATUS_NOT_IMPLEMENTED);
Expand Down Expand Up @@ -2181,8 +2181,8 @@ public function verifyDialInPin(string $pin): DataResponse {
#[PublicPage]
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the phone number to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the phone number, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function directDialIn(string $phoneNumber, string $caller): DataResponse {
if (!$this->talkConfig->isSIPConfigured()) {
return new DataResponse(null, Http::STATUS_NOT_IMPLEMENTED);
Expand Down Expand Up @@ -2245,8 +2245,8 @@ public function directDialIn(string $phoneNumber, string $caller): DataResponse
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequireRoom]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function verifyDialOutNumber(string $number, array $options = []): DataResponse {
if (!$this->talkConfig->isSIPConfigured() || !$this->talkConfig->isSIPDialOutEnabled()) {
return new DataResponse(null, Http::STATUS_NOT_IMPLEMENTED);
Expand Down Expand Up @@ -2294,8 +2294,8 @@ public function verifyDialOutNumber(string $number, array $options = []): DataRe
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequireRoom]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function createGuestByDialIn(): DataResponse {
try {
if (!$this->validateSIPBridgeRequest($this->room->getToken())) {
Expand Down Expand Up @@ -2335,8 +2335,8 @@ public function createGuestByDialIn(): DataResponse {
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[OpenAPI(scope: 'backend-sipbridge')]
#[RequireRoom]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function rejectedDialOutRequest(string $callId, array $options = []): DataResponse {
if (!$this->talkConfig->isSIPConfigured() || !$this->talkConfig->isSIPDialOutEnabled()) {
return new DataResponse(null, Http::STATUS_NOT_IMPLEMENTED);
Expand Down
4 changes: 2 additions & 2 deletions lib/Controller/SignalingController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,8 +140,8 @@ private function validateSIPBridgeRequest(string $data): bool {
#[BruteForceProtection(action: 'talkSipBridgeSecret')]
#[BruteForceProtection(action: 'talkFederationAccess')]
#[OpenAPI(tags: ['internal_signaling', 'external_signaling'])]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared recording secret, to verify authenticity from the recording backend', indirect: true)]
#[RequestHeader(name: 'talk-recording-random', description: 'Random seed (at least 32 bytes) used to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-recording-checksum', description: 'SHA256-HMAC checksum over the random seed, signed with the shared recording secret, to verify authenticity from the recording backend', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-random', description: 'Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum', indirect: true)]
#[RequestHeader(name: 'talk-sipbridge-checksum', description: 'SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared SIP bridge secret, to verify authenticity from the SIP bridge', indirect: true)]
public function getSettings(string $token = ''): DataResponse {
Expand Down
8 changes: 4 additions & 4 deletions openapi-backend-recording.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -726,15 +726,15 @@
{
"name": "talk-recording-random",
"in": "header",
"description": "Random seed (at least 32 bytes) used together with the request body to generate the SHA256-HMAC request checksum",
"description": "Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum",
"schema": {
"type": "string"
}
},
{
"name": "talk-recording-checksum",
"in": "header",
"description": "SHA256-HMAC checksum over the concatenation of the random seed and the request body, signed with the shared recording secret, to verify authenticity from the recording backend",
"description": "SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared recording secret, to verify authenticity from the recording backend",
"schema": {
"type": "string"
}
Expand Down Expand Up @@ -942,15 +942,15 @@
{
"name": "talk-recording-random",
"in": "header",
"description": "Random seed used to generate the request checksum",
"description": "Random seed (at least 32 bytes) used together with the room token to generate the SHA256-HMAC request checksum",
"schema": {
"type": "string"
}
},
{
"name": "talk-recording-checksum",
"in": "header",
"description": "Checksum over the request body to verify authenticity from the recording backend",
"description": "SHA256-HMAC checksum over the concatenation of the random seed and the room token, signed with the shared recording secret, to verify authenticity from the recording backend",
"schema": {
"type": "string"
}
Expand Down
Loading
Loading