A.2 N32 Handshake API
29.5733GPP5G SystemPublic Land Mobile Network (PLMN) InterconnectionRelease 18Stage 3TS
openapi: 3.0.0
info:
version: ‘1.3.0-alpha.2’
title: ‘N32 Handshake API’
description: |
N32-c Handshake Service.
© 2022, 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 V18.1.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’
‘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
/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
– OTHER
– NONSENSITIVE
– type: string
IeLocation:
description: Location of the IE in a HTTP message
anyOf:
– type: string
enum:
– URI_PARAM
– HEADER
– BODY
– MULTIPART_BINARY
– 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
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’
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’
senderN32fPort:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/Uinteger’
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’
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’
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’
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’
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
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 IPX
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
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
– 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
– type: string