Answer: Secure Message is a stateless asymmetric primitive that encrypts or signs a single payload using your private key and the peer's public key, making it a natural fit for request/response APIs. Unlike Secure Session it needs no handshake, so each call is independent and works over plain stateless HTTP.

It operates in two distinct modes chosen at construction time. Encrypt mode gives confidentiality plus integrity and is readable only by the named peer. Sign/verify mode gives authenticity and integrity while leaving the payload readable — useful when an intermediary must inspect the body.

Code Example:

import themis

// Encrypt mode — only the holder of the peer's private key can read it.
let crypter = TSMessage(inEncryptModeWithPrivateKey: clientPrivateKey,
                        peerPublicKey: serverPublicKey)!
let encrypted = try crypter.wrap(jsonString.data(using: .utf8))
let decrypted = try crypter.unwrapData(responseData)

// Sign mode — payload stays readable, origin is provable.
let signer = TSMessage(inSignVerifyModeWithPrivateKey: clientPrivateKey,
                       peerPublicKey: nil)!
let signed = try signer.wrap(jsonString.data(using: .utf8))

Key Points:

• Stateless — no handshake, no session to keep alive.
• Sign mode takes peerPublicKey: nil when signing; verification supplies the signer's public key.
• Keys must be an EC/RSA pair generated by TSKeyGen, not arbitrary bytes.