SDK Architecture
This document presents the architecture and fundamental concepts of the Secure Exchanges SDK.
Overview
+---------------------+ +------------------------+
| Your Application | | Secure Exchanges |
| | | Cloud |
| +---------------+ | | +------------------+ |
| | SecureExch. | | <=> | | REST/SOAP API | |
| | SDK | | | +------------------+ |
| | (Client-side | | | +------------------+ |
| | encryption) | | | | Storage | |
| +---------------+ | | | (Encrypted | |
| | Signature SDK | | | | data only) | |
| +---------------+ | | +------------------+ |
+---------------------+ +------------------------+
Security Principles
Zero-Knowledge Architecture
IMPORTANT: Secure Exchanges NEVER has access to encryption keys or your message content.
The SDK implements a "Zero-Knowledge" architecture:
- Encryption happens client-side (in the SDK, on your server)
- Keys never leave your environment in clear text
- Secure Exchanges stores only already-encrypted data
- Only the sender and recipient can decrypt the content
+------------------+ +------------------+
| SENDER | | RECIPIENT |
| | | |
| 1. Generate AES | | |
| 2. Encrypt msg | Encrypted data | 5. Receive |
| 3. Encrypt key | ===================> | encrypted key |
| for recipient | (unreadable by | 6. Decrypt key |
| 4. Send | Secure Exchanges) | 7. Decrypt msg |
+------------------+ +------------------+
|
+------------------+
| SECURE EXCHANGES |
| |
| Stores ONLY |
| encrypted data |
| (cannot read it) |
+------------------+
End-to-End Encryption (E2E)
The SDK uses a hybrid encryption system:
- AES-256 for data encryption (symmetric) - generated client-side
- RSA for secure key exchange (asymmetric)
- SHA-512 for integrity verification
// Example: AES key generation (client-side only)
var keys = CryptoHelper.GenerateAESKeys();
// keys.Key : 256-bit AES key (stays on your server)
// keys.IV : 128-bit initialization vector
Message Encryption Flow
CLIENT-SIDE (Your application)
================================
1. Generate AES keys (sender) --> Key generated locally
|
v
2. Encrypt message with AES --> Message encrypted locally
|
v
3. Encrypt AES key with RSA (recipient's public key)
TRANSIT TO SECURE EXCHANGES
================================
4. Send: {encrypted_message, encrypted_AES_key}
--> Secure Exchanges receives ONLY encrypted data
--> Secure Exchanges does NOT have the private key to decrypt
RECIPIENT-SIDE
================================
5. Decrypt AES key with RSA (recipient's private key)
|
v
6. Decrypt message with AES --> Message readable only by recipient
Namespace Structure
SecureExchangesSDK
SecureExchangesSDK
├── Helpers/ # Main operation classes
│ ├── MessageHelper # Send/receive messages
│ ├── CryptoHelper # Cryptographic operations
│ ├── SignHelper # Digital signatures
│ ├── LicenceHelper # License management
│ ├── MessengingHelper # SESAR workflows
│ ├── LogsHelper # Logging
│ ├── FileHelper # File operations
│ ├── ContactHelper # Contact management
│ ├── EmailHelper # Email validation
│ ├── PhoneHelper # Phone validation
│ └── SerializationHelper # JSON/XML
│
├── Models/
│ ├── Args/ # Input parameters (56 classes)
│ │ ├── MutliRecipientArgs
│ │ ├── GetMessageArgs
│ │ ├── GetEnveloppeArgs
│ │ └── ...
│ │
│ ├── Answer/ # Responses (24 classes)
│ │ ├── BaseAnswer
│ │ ├── MultiRecipientAnswer
│ │ ├── GetMessageResponse
│ │ └── ...
│ │
│ ├── Entity/ # Business entities (31 classes)
│ │ ├── RecipientInfo
│ │ ├── FileArgs
│ │ ├── Licence
│ │ └── ...
│ │
│ ├── Transport/ # DTOs (46 classes)
│ │ ├── SecureExchangesMessage
│ │ ├── Keys
│ │ ├── FileMetaData
│ │ └── ...
│ │
│ └── Contract/ # Interfaces (14 interfaces)
│ ├── IEndPointConfiguration
│ └── ...
│
└── CallBack/ # Async callbacks
├── ISecureExchangesCallBack
└── CallBackObject
SecureExchangesSignatureSDK
SecureExchangesSignatureSDK
├── Helpers/
│ └── PkiFileHelper # PDF certification with PKI
│
└── Models/
├── Args/
│ └── CertifyPdfArgs # Certification parameters
├── Transport/
│ └── ZoneDetails # Signature zone details
└── Factory/
└── ZoneDetailsFactory # Zone creation
Main Classes
MessageHelper
Main entry point for sending and receiving messages.
public static class MessageHelper
{
// Send to multiple recipients
public static MultiRecipientAnswer MultiRecipientMessage(MutliRecipientArgs args);
// Retrieve a message
public static GetMessageResponse GetMessage(GetMessageArgs args);
// Create a reply envelope
public static GetEnveloppeResponse GetEnveloppe(GetEnveloppeArgs args);
// Parse a Secure Exchanges link
public static SecureExchangesMessage GetSecureExchangesMessageFromLink(string link);
}
CryptoHelper
Centralized cryptographic operations.
public static class CryptoHelper
{
// Key generation
public static Keys GenerateAESKeys();
public static byte[] GenerateSecureRandomByteArray(int length);
// Encryption/Decryption
public static byte[] EncryptBinary(byte[] data, byte[] key, byte[] iv);
public static byte[] DecryptBinary(byte[] data, byte[] key, byte[] iv);
// File encryption
public static bool EncryptSecfFile(string path, byte[] key, byte[] iv);
public static bool DecryptSecfFile(string path, byte[] key, byte[] iv);
// Hashing
public static string GetSHA512OfFile(string path);
public static string GetSHA512HashOfBytes(byte[] data);
public static string GetMD5HashOfFile(string path);
// RSA
public static byte[] EncryptRSAContent(string xmlPublicKey, string content);
public static string DecryptRSAContentToString(string xmlPrivateKey, byte[] data, bool useOAEP);
}
SignHelper
Electronic signature zone management and document integrity validation.
public static class SignHelper
{
// Zone creation helpers
public static SignZoneDetails CreateSignatureZone(string fieldName, int page,
float x, float y, float width, float height,
float pageWidth, float pageHeight, bool required = true);
public static SignZoneDetails CreateTextZone(string fieldName, int page,
float x, float y, float width, float height,
float pageWidth, float pageHeight,
string defaultValue = "", float fontSize = 12, bool required = true);
public static SignZoneDetails CreateDateZone(string fieldName, int page,
float x, float y, float width, float height,
float pageWidth, float pageHeight,
string dateFormat = "yyyy-MM-dd", bool required = true);
public static SignZoneDetails CreateCheckboxZone(string fieldName, int page,
float x, float y, float size,
float pageWidth, float pageHeight,
bool isChecked = false, bool required = false);
public static SignZoneDetails CreateInitialsZone(string fieldName, int page,
float x, float y, float width, float height,
float pageWidth, float pageHeight, bool required = true);
// Zone template conversion
public static Dictionary<RecipientInfo, List<FileZoneDefinition>> AddFileZoneDefToRecipientIndex(
Dictionary<RecipientInfo, List<FileZoneDefinition>> recipientIndex,
IEnumerable<SignTemplateRecipient> templateZones,
string SHA512,
params KeyValuePair<string, RecipientInfo>[] recipientsMatch);
// Recipient zone management
public static List<RecipientZoneDefinition> ConvertRecipientIndexToList(
Dictionary<RecipientInfo, List<FileZoneDefinition>> recipientIndex);
public static List<RecipientZoneDefinition> ConcatRecipientZoneDefinitionLists(
List<RecipientZoneDefinition> list1, List<RecipientZoneDefinition> list2);
// Document validation
public static ValidateDocumentSignatureIntegrityResponse ValidateDocumentSignatureIntegrity(
ValidateDocumentSignatureIntegrity_args args);
// PKI certification token
public static GetCertificationTokenResponse GetCertificationToken(
GetCertificationTokenSDKArgs args, CertificationMetadata metadata = null);
}
Key Data Models
MutliRecipientArgs
Arguments for multi-recipient message sending.
var args = new MutliRecipientArgs(
endPointConfigurationName, // Endpoint configuration
serial, // License serial number
apiUser, // API identifier
apiPassword, // API password
recipients, // RecipientInfo list
message, // Message body (HTML)
subject, // Subject
password, // Password (optional)
binaryFiles, // In-memory files
sendMethod, // Email, SMS, or hybrid
sendByMyOwnSMTPServer, // Use own SMTP
showSubject, // Show subject
getNotify, // Notification on opening
culture, // fr-CA or en-CA
maxOpeningTime, // Max opening count
expirationMinutes // Validity duration
);
// Additional properties
args.FilesPath = new List<string>(); // File paths
args.FileToSign = new List<SignFilesRequired>(); // Files to sign
args.CallBackParameters = "..."; // Callback parameters
MultiRecipientAnswer
Response after sending a message.
public class MultiRecipientAnswer : BaseAnswer
{
public int Status { get; set; } // Status code (200 = success)
public string Data { get; set; } // Error message if failed
public List<RecipientAnswer> RecipientsAnswer { get; set; }
}
public class RecipientAnswer
{
public SendMessageAnswer Answer { get; set; }
}
public class SendMessageAnswer
{
public int Status { get; set; }
public string URL { get; set; } // Message link
public string HtmlMsg { get; set; } // Notification HTML
public string DefaultOpeningCode { get; set; } // Opening code
}
Typical Workflows
Simple Send
Application -> MutliRecipientArgs -> MessageHelper.MultiRecipientMessage()
|
v
MultiRecipientAnswer
|
v
Message URL
Send with Signature
1. Prepare PDF files
|
v
2. Create signature zones with SignHelper
|
v
3. Configure MutliRecipientArgs with FileToSign
|
v
4. Send with MessageHelper.MultiRecipientMessage()
|
v
5. Recipient signs via web interface
|
v
6. Retrieve signed document via callback or API
SESAR Workflow (Messenging)
1. InitializeSesar() - Initialize session
|
v
2. CreateRestoreRequest() - Create restore request
|
v
3. GetMessenging() - Retrieve messages
|
v
4. Process encrypted callbacks
Endpoint Configuration
// Using the production environment
Uri endpoint = new Uri("https://www.secure-exchanges.com/_api/0217/0217.asmx");
var args = new MutliRecipientArgs(endpoint, serial, apiUser, apiPassword, ...);