openapi: 3.0.0

info:
  version: '1.4.0'
  title: 'N32 Handshake API'
  description: |
    N32-c Handshake Service.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
servers:
  - url: '{apiRoot}/n32c-handshake/v1'
    variables:
      apiRoot:
        default: https://example.com
        description:  apiRoot as defined in clause 4.4 of 3GPP TS 29.501.
externalDocs:
  description: 3GPP TS 29.573 V19.5.0; 5G System; Public Land Mobile Network (PLMN) Interconnection; Stage 3
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.573/

paths:
  /exchange-capability:
    post:
      summary:  Security Capability Negotiation
      tags:
        - Security Capability Negotiation
      operationId: PostExchangeCapability
      requestBody:
        description: Custom operation for security capability negotiation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecNegotiateReqData'
      responses:
        '200':
          description: OK (Successful negitiation of security capabilities)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecNegotiateRspData'
        '307':
          description: redirection
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ExtRedirectResponse'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '409':
          $ref: 'TS29571_CommonData.yaml#/components/responses/409'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          description: Unexpected error
  /exchange-params:
    post:
      summary: Parameter Exchange
      tags:
        - Parameter Exchange
      operationId: PostExchangeParams
      requestBody:
        description: Custom operation for parameter exchange
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecParamExchReqData'
      responses:
        '200':
          description: OK (Successful exchange of parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecParamExchRspData'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '409':
          $ref: 'TS29571_CommonData.yaml#/components/responses/409'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          description: Unexpected error
  /n32f-terminate:
    post:
      summary: N32-f Context Terminate
      tags:
        - N32-f Context Terminate
      operationId: PostN32fTerminate
      requestBody:
        description: Custom operation for n32-f context termination
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/N32fContextInfo'
      responses:
        '200':
          description: OK (Successful exchange of parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/N32fContextInfo'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          description: Unexpected error
  /n32f-error:
    post:
      summary: N32-f Error Reporting Procedure
      tags:
        - N32-f Error Report
      operationId: PostN32fError
      requestBody:
        description: Custom operation for n32-f error reporting procedure
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/N32fErrorInfo'
      responses:
        '204':
          description: successful error reporting
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          description: Unexpected error
components:
  schemas:
    SecurityCapability:
      description: Enumeration of security capabilities
      anyOf:
        - type: string
          enum:
            - TLS
            - PRINS
            - NONE
        - type: string
    ApiSignature:
      description: API URI of the service operation
      oneOf:
        - $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        - $ref: '#/components/schemas/CallbackName'
    HttpMethod:
      description: Enumeration of HTTP methods
      anyOf:
        - type: string
          enum:
            - GET
            - PUT
            - POST
            - DELETE
            - PATCH
            - HEAD
            - OPTIONS
            - CONNECT
            - TRACE
        - type: string

    IeType:
      description: Enumeration of types of IEs (i.e kind of IE) to specify the protection policy
      anyOf:
        - type: string
          enum:
            - UEID
            - LOCATION
            - KEY_MATERIAL
            - AUTHENTICATION_MATERIAL
            - AUTHORIZATION_TOKEN
            - RECURSIVE_NON_LEAF
            - OTHER
            - NONSENSITIVE
        - type: string

    IeLocation:
      description: Location of the IE in a HTTP message
      anyOf:
        - type: string
          enum:
            - URI_PARAM
            - HEADER
            - BODY
            - MULTIPART_BINARY
            - URI_PATH
        - type: string

    IeInfo:
      description: Protection and modification policy for the IE
      type: object
      required:
        - ieLoc
        - ieType
      properties:
        ieLoc:
          $ref: '#/components/schemas/IeLocation'
        ieType:
          $ref: '#/components/schemas/IeType'
        reqIe:
          type: string
        rspIe:
          type: string
        isModifiable:
          type: boolean
        isModifiableByIpx:
          type: object
          additionalProperties:
            type: boolean
          minProperties: 1
        ancestorIe:
          type: string

    ApiIeMapping:
      description: API URI to IE mapping on which the protection policy needs to be applied
      type: object
      required:
        - apiSignature
        - apiMethod
        - IeList
      properties:
        apiSignature:
          $ref: '#/components/schemas/ApiSignature'
        apiMethod:
          $ref: '#/components/schemas/HttpMethod'
        IeList:
          type: array
          items:
            $ref: '#/components/schemas/IeInfo'
          minItems: 1
# The attribute name does not follow the naming conventions specified in 3GPP TS 29.501. The attribute name is kept though as defined in the current specification for backward compatibility reason.

    ProtectionPolicy:
      description: The protection policy to be negotiated between the SEPPs
      type: object
      required:
        - apiIeMappingList
      properties:
        apiIeMappingList:
          type: array
          items:
            $ref: '#/components/schemas/ApiIeMapping'
          minItems: 1
        dataTypeEncPolicy:
          type: array
          items:
            $ref: '#/components/schemas/IeType'
          minItems: 1

    SecNegotiateReqData:
      description: Defines the security capabilities of a SEPP sent to a receiving SEPP
      type: object
      required:
        - sender
        - supportedSecCapabilityList
      properties:
        sender:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        n32HandshakeId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
        supportedSecCapabilityList:
          type: array
          items:
            $ref: '#/components/schemas/SecurityCapability'
          minItems: 1
        3GppSbiTargetApiRootSupported:
          type: boolean
          default: false
# The attribute name does not follow the naming conventions specified in 3GPP TS 29.501. The attribute name is kept though as defined in the current specification for backward compatibility reason.
        plmnIdList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnId'
          minItems: 1
        snpnIdList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnIdNid'
          minItems: 1
        targetPlmnId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnId'
        targetSnpnId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnIdNid'
        intendedUsagePurpose:
          type: array
          items:
            $ref: '#/components/schemas/IntendedN32Purpose'
          minItems: 1
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        senderN32fFqdn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        senderN32fPortList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
          minItems: 1
        n32KeepaliveTimer:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DurationSec'

    SecNegotiateRspData:
      description: Defines the selected security capabilities by a SEPP
      type: object
      required:
        - sender
        - selectedSecCapability
      properties:
        sender:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        selectedSecCapability:
          $ref: '#/components/schemas/SecurityCapability'
        n32HandshakeId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
        3GppSbiTargetApiRootSupported:
          type: boolean
          default: false
# The attribute name does not follow the naming conventions specified in 3GPP TS 29.501. The attribute name is kept though as defined in the current specification for backward compatibility reason.
        plmnIdList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnId'
          minItems: 1
        snpnIdList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/PlmnIdNid'
          minItems: 1
        allowedUsagePurpose:
          type: array
          items:
            $ref: '#/components/schemas/IntendedN32Purpose'
          minItems: 1
        rejectedUsagePurpose:
          type: array
          items:
            $ref: '#/components/schemas/IntendedN32Purpose'
          minItems: 1
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        senderN32fFqdn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        senderN32fPort:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        n32KeepaliveTimer:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DurationSec'

    SecParamExchReqData:
      description: Request data structure for parameter exchange
      type: object
      required:
        - n32fContextId
      properties:
        n32fContextId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
        jweCipherSuiteList:
          type: array
          items:
            type: string
          minItems: 1
        jwsCipherSuiteList:
          type: array
          items:
            type: string
          minItems: 1
        protectionPolicyInfo:
          $ref: '#/components/schemas/ProtectionPolicy'
        secProfiles:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 256
        ipxProviderSecInfoList:
          type: array
          items:
            $ref: '#/components/schemas/IpxProviderSecInfo'
          minItems: 1
        sender:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'

    SecParamExchRspData:
      description: Response data structure for parameter exchange
      type: object
      required:
        - n32fContextId
      properties:
        n32fContextId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
        selectedJweCipherSuite:
          type: string
        selectedJwsCipherSuite:
          type: string
        selProtectionPolicyInfo:
          $ref: '#/components/schemas/ProtectionPolicy'
        selSecProfiles:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 256
        ipxProviderSecInfoList:
          type: array
          items:
            $ref: '#/components/schemas/IpxProviderSecInfo'
          minItems: 1
        sender:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'

    N32fContextInfo:
      description: N32-f context information
      type: object
      required:
        - n32fContextId
      properties:
        n32fContextId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
    CallbackName:
      description: Callback Name
      type: object
      required:
        - callbackType
      properties:
        callbackType:
          type: string
    N32fErrorInfo:
      description: N32-f error information
      type: object
      required:
        - n32fMessageId
        - n32fErrorType
      properties:
        n32fMessageId:
          type: string
        n32fErrorType:
          $ref: '#/components/schemas/N32fErrorType'
        n32fContextId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
        failedModificationList:
          type: array
          items:
            $ref: '#/components/schemas/FailedModificationInfo'
          minItems: 1
        errorDetailsList:
          type: array
          items:
            $ref: '#/components/schemas/N32fErrorDetail'
          minItems: 1
        policyMismatchList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/InvalidParam'
          minItems: 1
        riErrorInformation:
          $ref: '#/components/schemas/RiErrorInformation'

    FailedModificationInfo:
      description: Information on N32-f modifications block that failed to process
      type: object
      required:
        - ipxId
        - n32fErrorType
      properties:
        ipxId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        n32fErrorType:
          $ref: '#/components/schemas/N32fErrorType'
    N32fErrorDetail:
      description: Details about the N32f error
      type: object
      required:
        - attribute
        - msgReconstructFailReason
      properties:
        attribute:
          type: string
        msgReconstructFailReason:
          $ref: '#/components/schemas/FailureReason'
    IpxProviderSecInfo:
      description: Defines the security information list of an RI
      type: object
      required:
        - ipxProviderId
      properties:
        ipxProviderId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'
        rawPublicKeyList:
          type: array
          items:
            type: string
          minItems: 1
        certificateList:
          type: array
          items:
            type: string
          minItems: 1

    IntendedN32Purpose:
      description: Indicates the intended N32 establishment purpose
      type: object
      required:
        - usagePurpose
      properties:
        usagePurpose:
          $ref: '#/components/schemas/N32Purpose'
        additionalInfo:
          type: string
        cause:
          type: string

    RiErrorInformation:
      description: RI error information
      type: object
      properties:
        n32fConnectionRelInd:
          $ref: '#/components/schemas/N32ReleaseIndication'
        n32fContextRelInd:
          $ref: '#/components/schemas/N32ReleaseIndication'
        alternativeRi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'

    N32fErrorType:
      description: Type of error while processing N32-f message
      anyOf:
        - type: string
          enum:
            - INTEGRITY_CHECK_FAILED
            - INTEGRITY_CHECK_ON_MODIFICATIONS_FAILED
            - MODIFICATIONS_INSTRUCTIONS_FAILED
            - DECIPHERING_FAILED
            - MESSAGE_RECONSTRUCTION_FAILED
            - CONTEXT_NOT_FOUND
            - INTEGRITY_KEY_EXPIRED
            - ENCRYPTION_KEY_EXPIRED
            - POLICY_MISMATCH
            - NETWORK_MAINTENANCE
            - INSUFFICIENT_RESOURCES
            - NO_CONNECTION_DUE_TO_CONTRACT
            - IDLE_N32F_CONNECTION
            - SWITCHING_TO_ANOTHER_RI
            - NO_CONNECTION_DUE_TO_CONNECTIVITY
        - type: string

    FailureReason:
      description: Reason for failure to reconstruct a HTTP/2 message from N32-f message
      anyOf:
        - type: string
          enum:
            - INVALID_JSON_POINTER
            - INVALID_INDEX_TO_ENCRYPTED_BLOCK
            - INVALID_HTTP_HEADER
        - type: string

    N32Purpose:
      description: Usage purpose of establishing N32 connectivity
      anyOf:
        - type: string
          enum:
            - ROAMING
            - INTER_PLMN_MOBILITY
            - SMS_INTERCONNECT
            - ROAMING_TEST
            - INTER_PLMN_MOBILITY_TEST
            - SMS_INTERCONNECT_TEST
            - SNPN_INTERCONNECT
            - SNPN_INTERCONNECT_TEST
            - DISASTER_ROAMING
            - DISASTER_ROAMING_TEST
            - DATA_ANALYTICS_EXCHANGE
            - DATA_ANALYTICS_EXCHANGE_TEST
        - type: string

    N32ReleaseIndication:
      description: N32-f connection/context release indication
      anyOf:
        - type: string
          enum:
            - RELEASE_REESTABLISHMENT_ALLOWED
            - RELEASE_REESTABLISHMENT_NOT_ALLOWED
            - REESTABLISH
        - type: string

    ExtRedirectResponse:
      description: Extension of the redirection response
      allOf:
        - $ref: 'TS29571_CommonData.yaml#/components/schemas/RedirectResponse'
        - $ref: '#/components/schemas/RedirectResponseAddInfo'

    RedirectResponseAddInfo:
      description: Additional information in the redirection response
      type: object
      properties:
        seppFqdnForDiscovery:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'