openapi: 3.0.0

info:
  version: '1.1.0.alpha-3'
  title: 'N32 Handshake API'
  description: |
   N32-c Handshake Service.
    © 2020, 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 V16.2.0; 5G System; Public Land Mobile Network (PLMN) Interconnection; Stage 3
  url: http://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'
        '400': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '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'
        '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'
        '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'
        '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'
        '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'
        '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'
        '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'
        '503': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          description: Unexpected error
components:
  schemas:
    SecurityCapability:
      anyOf:
        - type: string
          enum:
            - TLS
            - PRINS
        - type: string
    ApiSignature:
      oneOf:
        - $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        - $ref: '#/components/schemas/CallbackName'
    HttpMethod:
      anyOf:
        - type: string
          enum:
            - GET
            - PUT
            - POST
            - DELETE
            - PATCH
            - HEAD
            - OPTIONS
            - CONNECT
            - TRACE
        - type: string    
    
    IeType:
      anyOf:
        - type: string
          enum:
            - UEID
            - LOCATION
            - KEY_MATERIAL
            - AUTHENTICATION_MATERIAL
            - AUTHORIZATION_TOKEN
            - OTHER
            - NONSENSITIVE
        - type: string
    
    IeLocation:
      anyOf:
        - type: string
          enum:
            - URI_PARAM
            - HEADER
            - BODY
            - MULTIPART_BINARY
        - type: string
    
    IeInfo:
      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
  
    ApiIeMapping:
      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
  
    ProtectionPolicy:
      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:
      type: object
      required:
        - sender
        - supportedSecCapabilityList
      properties:
        sender:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
        supportedSecCapabilityList:
          type: array
          items:
            $ref: '#/components/schemas/SecurityCapability'
          minItems: 1

    SecNegotiateRspData:
      type: object
      required:
        - sender
        - selectedSecCapability
      properties:
        sender:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
        selectedSecCapability:
          $ref: '#/components/schemas/SecurityCapability'
  
    SecParamExchReqData:
      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'
        ipxProviderSecInfoList:
          type: array
          items:
            $ref: '#/components/schemas/IpxProviderSecInfo'
          minItems: 1
        sender:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
          
    SecParamExchRspData:
      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'
        ipxProviderSecInfoList:
          type: array
          items:
            $ref: '#/components/schemas/IpxProviderSecInfo'
          minItems: 1
        sender:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
    
    N32fContextInfo:
      type: object
      required:
        - n32fContextId
      properties:
        n32fContextId:
          type: string
          pattern: '^[A-Fa-f0-9]{16}$'
    CallbackName:
      type: object
      required:
        - callbackType
      properties:
        callbackType:
          type: string
    N32fErrorInfo:
      type: object
      required:
        - n32fMessageId
        - n32fErrorType
      properties:
        n32fMessageId:
          type: string
        n32fErrorType:
          $ref: '#/components/schemas/N32fErrorType'
        failedModificationList:
          type: array
          items:
            $ref: '#/components/schemas/FailedModificationInfo'
          minItems: 1
        errorDetailsList:
          type: array
          items:
            $ref: '#/components/schemas/N32fErrorDetail'
          minItems: 1
    FailedModificationInfo:
      type: object
      required:
        - ipxId
        - n32fErrorType
      properties:
        ipxId:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
        n32fErrorType:
          $ref: '#/components/schemas/N32fErrorType'
    N32fErrorDetail:
      type: object
      required:
        - attribute
        - msgReconstructFailReason
      properties:
        attribute:
          type: string
        msgReconstructFailReason:
          $ref: '#/components/schemas/FailureReason'
    IpxProviderSecInfo:
      type: object
      required:
        - ipxProviderId
      properties:
        ipxProviderId:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/Fqdn'
        rawPublicKeyList:
          type: array
          items: 
            type: string
          minItems: 1
        certificateList:
          type: array
          items: 
            type: string
          minItems: 1
    N32fErrorType:
      anyOf:
        - type: string
          enum:
            - INTEGRITY_CHECK_FAILED
            - INTEGRITY_CHECK_ON_MODIFICATIONS_FAILED
            - MODIFICATIONS_INSTRUCTIONS_FAILED
            - DECIPHERING_FAILED
            - MESSAGE_RECONSTRUCTION_FAILED
        - type: string
    FailureReason:
      anyOf:
        - type: string
          enum:
            - INVALID_JSON_POINTER
            - INVALID_INDEX_TO_ENCRYPTED_BLOCK
            - INVALID_HTTP_HEADER
        - type: string