Integrity & Non-repudiation
Previous page Environments
Next pageNotifications
Integrity & Non-repudiation are features Swift provides for APIs available through MV-SIPN. The integrity and non-repudiation evidences are built based on JSON Web Token standards. It enables specific claims to be protected through digital signature leveraging the Swift PKI infrastructure and Swift issued certificates. The integrity evidence is used to validate the data integrity through transit in the form of X-SWIFT-Integrity header. The non-repudiation evidence is used to ensure that requests are uniquely attributed to the sender in the form of X-SWIFT-Signature header.
When non-repudiation is required on the API request, then the presence of the X-SWIFT-Signature header is instrumented as indicated in the OpenAPI specifications. See how to generate the JWT next.
Keep in mind that the request must not be fully canonicalised. You must ensure that the API request has not been altered by the HTTP library used before it is sent. In particular, the element order must not be altered during the JSON parse and stringify functions. Example implementation: Reference Postman Collection
Example Postman code:
function base64AddPadding(str) {
return str + Array((4 - str.length % 4) % 4 + 1).join('=');
};
var bodyString = JSON.stringify(JSON.parse(request.body));
var b64urlString = base64AddPadding(pmlib.
The JWT structure has three parts: header, payload and signature. For more information about the JWT structure, see RFC7519.
| Headers | Descriptions |
|---|---|
| typ | Type. This parameter defines the media type of the complete JWT. Use JWT. |
| alg | Algorithm. This parameter defines the signing algorithm used for the JWT. For example, HS256 for business certificate and RS256 for channel certificate. |
| xmldsig | This parameter is the encoded xmldsig signature. Use this parameter ONLY if using business certificate. |
| x5c | This parameter is the public key used to verify the JWT. Use this parameter ONLY if using channel certificate. |
| Claims | Descriptions |
|---|---|
| sub | Subject. This is the subject DN of the certificate used to sign the JWT. |
| aud | Audience. This is the URL of the API request endpoint. |
| iat | Issued at. This is the time (in seconds) at which the JWT was issued. |
| exp | Expiration time. This is the expiration time (in seconds) on or after which the JWT MUST NOT be accepted for processing. |
| jti | JWT ID. This is the unique identifier for the JWT used to detect duplicates. The accepted character set is Base64 URL. See RFC 4648. |
| digest | This is a private claim. It is the SHA-256 digest, encoded in Base64, of the API request body. |
3Signature The signature is created by signing the header and payload with the private key of the Swift issued business certificate or channel certificate.
When integrity validation is required either on the API request or API response, then the presence of X-SWIFT-Integrity header is instrumented as indicated in the OpenAPI specifications. For example, if the API request payload is the data to be validated, then the X-SWIFT-Integrity header is a JWT which:
In another example, if the API response payload is the data to be validated, then the X-SWIFT-Integrity header is a JWT which:
To validate the origin and data integrity, the client application should verify the signature and compare its digest with the digest calculated from the API response received.
The JWT claims of the integrity header contain the following information.
| Claims | Descriptions |
|---|---|
| sub | Subject. This is the subject DN of the certificate used to sign the JWT. |
| aud | Audience. This is the subject DN of the certificate used by the application which sent the API request. |
| iat | Issued at. This is the time (in seconds) at which the JWT was issued. |
| exp | Expiration time. This is the expiration time (in seconds) on or after which the JWT MUST NOT be accepted for processing. |
| jti | JWT ID. This is the unique identifier for the JWT used to detect duplicates. The accepted character set is Base64 URL. See RFC 4648. |
| digestalg | This is a private claim. The algorithm used to compute the digest, which is SHA256. |
| digest | This is a private claim. This is the digest of the API Request Body after JSON canonicalisation in RFC 8785. Digest is encoded in Hex (Base 16). |