--- swagger: "2.0" info: title: Mobile End to End Encryption description: 'This API will be used to exchange Symmetric Session keys between Mobile APP & Server ' version: 2.0.0 x-ibm-name: mobile-end-to-end-encryption host: basePath: /api/v1 schemes: - https paths: /security/e2e/key: post: summary: Exchange the session key with the server. tags: - E2E-Cipher description: This API accepts the session key in the request and cache them in the session. This key will be used for all E2E cryptographic operations between client and server. Below is the details of the request format.

1. Generate 32 byte/256 bit AES encryption key and convert to HexString(64 chars) - EK
2. Generate IV and convert to HexString 32 chars - IV
3. Generate 32 byte/256 bit AES Hmac key and convert to HexString (64 chars) - HK
4. Concatenate {EK+IV+HK} and do RSA encryption with the public key. Convert the output to HexString. - Hex[PubKey{EK+IV+HK}]-encryptedPayload
5. Generate check digit of EK - encKeyCheckDigit
6. Generate check digit of HK - hmacKeyCheckDigit

For every success scenario, this api sends an encrypted server random/eventId in the response headers. Eventid will be in below format

1. Generate a 32 char secure random - SR
2. Encrypt SR with EK using IV - CipherSRBytes
3. Encode CipherSRBytes with Base64 - CipherSR_B64
4. Calculate HMAC of CipherSRBytes using HK and convert to Base64 encoded - SRHmac_B64
5. eventId in the response header will be in the form of { CipherSR_B64.SRHmac_B64 } with a dot delimiter. responses: 200: description: Session keys are exchanged successfully 400: description: (BAD REQUEST) - Request was not processed
TypeCodeDetails
invalidinvalidRequestMissing Parameters
errorchkDigitNotMatchCheck digits do not match
errorcannotDecryptDataCannot decrypt, please re-check the encrypted value
schema: $ref: '#/definitions/ErrorResponse' 401: description: ' Unauthorized - Client must authenticate itself to get the requested response
TypeCodeDetails
errorunAuthorizedAuthorization credentials are missing or invalid
' schema: $ref: '#/definitions/ErrorResponse' 403: description: (FORBIDDEN) - Unauthorized to perform the requested operation on resource
TypeCodeDetailsMore Info
invalidaccessNotConfiguredThe request operation is not configured to access this resourceChannel/Country/Business provided in the request is not supported currently
schema: $ref: '#/definitions/ErrorResponse' 404: description: (Not Found) - The requested resource could not be found but may be available in the future.
TypeCodeDetailsMore Info
errorresourceNotFoundThe requested resource was not foundEmpty resource/resource not found
schema: $ref: '#/definitions/ErrorResponse' 500: description: (INTERNAL SERVER ERROR) - API Server Error
TypeCodeDetails
fatalserverUnavailableThe request failed due to an internal error/server unavailability
schema: $ref: '#/definitions/ErrorResponse' consumes: - application/json produces: - application/json parameters: - name: uuid default: a7d1e304-83a9-4413-af97-62615e57eae66807840 in: header description: A 128 bit universally unique identifier (UUID) that you generate for every request and is used for tracking. It is recommended to use the output from Java UUID class or an equivalent. If not provided by APP, PSG will generate it. required: true type: string - name: Accept default: application/json in: header description: Content-Types that are acceptable for the response. Currently we support application/json.If not provided by APP, PSG will generate it. required: true type: string - name: Content-Type default: application/json in: header description: This is the HTTP Content-Type.If not provided by APP, PSG will generate it. required: true type: string - name: Accept-Language default: en-US in: header description: HTTP Accept-Language header.If not provided by APP, PSG will add default. required: true type: string - name: countryCode default: US in: header description: 2 character ISO country code.If not provided by APP, PSG will add default(MX) required: true type: string - name: businessCode default: GCB in: header description: business code.If not provided by APP, PSG will add default(GCB) required: true type: string - name: channelId default: MOB in: header description: Channel Id identifies the consumer from where the request comes required: true type: string - name: sid default: abbb4837-8343-418c-93d8-77a8519dff9e in: header description: sid required: true type: string - name: Authorization default: asdfkjsaldfjasfiewetowtllasgflasfspfwerfjwejrowglklasdfaslf in: header description: The Authorization Token received during login.The scope will be limited till APIGateway. required: false type: string - name: client_id default: 29738e5a-fbbf-4b55-981d-d2f3d2a60605 in: header description: The client ID you received during application registration in the developer portal.The scope will be limited till APIGateway. required: true type: string - name: SessionKeyDetails in: body description: Session key details for exchanging with the server. required: true schema: $ref: '#/definitions/SessionKeyDetails' get: responses: 200: description: 200 OK tags: - E2E-Cipher parameters: - name: uuid default: a7d1e304-83a9-4413-af97-62615e57eae66807840 in: header description: A 128 bit universally unique identifier (UUID) that you generate for every request and is used for tracking. It is recommended to use the output from Java UUID class or an equivalent. If not provided by APP, PSG will generate it. required: false type: string - name: Accept default: application/json in: header description: Content-Types that are acceptable for the response. Currently we support application/json.If not provided by APP, PSG will generate it. required: false type: string - name: Content-Type default: application/json in: header description: This is the HTTP Content-Type.If not provided by APP, PSG will generate it. required: false type: string - name: Accept-Language default: en-US in: header description: HTTP Accept-Language header.If not provided by APP, PSG will add default. required: false type: string - name: countryCode default: US in: header description: 2 character ISO country code.If not provided by APP, PSG will add default(MX) required: false type: string - name: businessCode default: GCB in: header description: business code.If not provided by APP, PSG will add default(GCB) required: false type: string - name: channelId default: MOB in: header description: Channel Id identifies the consumer from where the request comes required: false type: string - name: sid default: abbb4837-8343-418c-93d8-77a8519dff9e in: header description: sid required: false type: string - name: Authorization default: asdfkjsaldfjasfiewetowtllasgflasfspfwerfjwejrowglklasdfaslf in: header description: The Authorization Token received during login.The scope will be limited till APIGateway. required: false type: string - name: client_id default: 29738e5a-fbbf-4b55-981d-d2f3d2a60605 in: header description: The client ID you received during application registration in the developer portal.The scope will be limited till APIGateway. required: false type: string - name: SessionKeyDetails in: body description: Session key details for exchanging with the server. required: false schema: $ref: '#/definitions/SessionKeyDetails' definitions: SessionKeyDetails: required: - encryptedPayload - encKeyCheckDigit - hmacKeyCheckDigit - algorithm type: object properties: encryptedPayload: description: Session Key exchange payload example: jlijsdifjosigjojoierowjgoijwogwehwengwijeojowjoegj encKeyCheckDigit: type: string description: Check digit of encryption key. example: 2CD345 hmacKeyCheckDigit: type: string description: Check digit of HMAC key. example: 5T0985 algorithm: type: string description: Algorthm of the session keys. Currently only AES is supported. example: AES ErrorResponse: required: - type - code properties: type: type: string enum: - error - warn - invalid - fatal description:
invalid - Request did not confirm to the specification and was unprocessed & rejected. Please fix the value and try again

warn - Request was partially processed. E.g. some of the fields are missing in response to the system issues, request was accepted successfully but will be processed asynchronously

error - The request was accepted but could not be processed successfully

fatal - There was an internal system error while processing the request. These are technical errors and will be resolved by Citi, and the consumer should retry after some time. Business errors will not be categorized as fatal
code: type: string description: Error code which qualifies the error details: type: string description: Human readable explanation specific to the occurrence of the problem location: type: string description: The name of the field that resulted in the error moreInfo: type: string description: URI to human readable documentation of the error x-ibm-configuration: enforced: true testable: true phase: realized securityDefinitions: Client ID: type: apiKey description: "" in: header name: X-IBM-Client-Id security: - Client ID: [] x-ibm-endpoints: - endpointUrl: https://perf.api.externalapib2b.wlb.lac.nsroot.net:7100/mx-gcgapi/perfext type: - production - development ...