{ "openapi": "3.1.1", "info": { "title": "TLS Cipher-Suite Simulator API", "version": "1.0.0", "summary": "See which TLS version, cipher and group browsers, Android, Java and OpenSSL get from your server.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://tlsciphersuitesimulator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "See which TLS version, cipher and group browsers, Android, Java and OpenSSL get from your server.", "description": "Pick a Mozilla server preset (modern, intermediate, old) or paste your own cipher list in OpenSSL or IANA names, and see what 34 recorded clients (browsers, Android, Java, OpenSSL, plus curl) would negotiate: protocol version, cipher suite, key-exchange group, signature algorithm, forward secrecy and AEAD, or why the handshake fails. Includes an IANA ↔ OpenSSL name table and a configuration grade. Offline simulation from documented data, no connection is made.\n\nMethodology:\n- Client data: the ClientHello bytes SSL Labs records for its handshake simulation (cipher suites in order, supported_versions, supported_groups, key_share, signature_algorithms), decoded by our own parser, plus SSL Labs’ DH-size limits. GREASE values and pre-standard TLS 1.3 draft versions (e.g. the draft-28 version sent by Firefox 62) are ignored. curl profiles reuse the default hello of the OpenSSL version curl is linked against (an approximation: curl distributions may set their own cipher lists).\n- Server data: Mozilla Server Side TLS guidelines 6.0 (modern, intermediate) and 5.7 (old, removed from 6.0): protocols, cipher suites, TLS 1.3 suites, curves, certificate types and DH size. Custom lists accept OpenSSL names, IANA names or hex codes.\n- Negotiation follows OpenSSL server behaviour: the highest common protocol version wins; TLS 1.3 chooses a shared suite and group (a missing key share costs a HelloRetryRequest) and needs ecdsa_secp256r1_sha256 or rsa_pss_rsae_* signatures. TLS ≤ 1.2 picks the first shared suite in client order (or server order if enabled) whose authentication matches the certificate and whose key exchange is possible (ECDHE needs a shared curve). Clients that reject large or small DH groups fail like they do in reality.\n- Grade: our own simple scale (A+ to F), not the SSL Labs rating: SSL 3.0, RC4, export, NULL, anonymous or DES suites → F; 3DES → C; TLS 1.0/1.1 or static RSA → B; CBC suites → A-; no TLS 1.3 → A.\n- Limitations: no real network connection is made; extensions such as ALPN, session resumption, OCSP stapling, Encrypted Client Hello and certificate chain validation are not simulated; client behaviour can differ by OS build and configuration.\n\nSimulation from recorded and documented data. Test your real server with a live scanner before relying on it.", "tags": [ "crypto" ], "x-mcp-tool": "tls_cipher_suite_simulator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlsCipherSuiteSimulatorInput" }, "examples": { "example1": { "summary": "Mozilla intermediate against all clients", "value": { "serverPreset": "intermediate" } }, "example2": { "summary": "Mozilla modern (TLS 1.3 only)", "value": { "serverPreset": "modern" } }, "example3": { "summary": "Mozilla old with RSA certificate", "value": { "serverPreset": "old", "clients": [ "java-6u45", "ie-8-xp", "android-2.3.7", "android-4.4.2", "chrome-131-win-10", "curl-openssl-1.0.2" ] } }, "example4": { "summary": "Custom OpenSSL list without ECDHE, server order", "value": { "serverPreset": "custom", "customSuites": "DHE-RSA-AES256-GCM-SHA384:AES128-SHA:DES-CBC3-SHA", "customProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ], "certificate": "rsa", "dhBits": 2048 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TlsCipherSuiteSimulatorResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "TlsCipherSuiteSimulatorInput": { "type": "object", "additionalProperties": false, "properties": { "serverPreset": { "title": "Server configuration", "type": "string", "enum": [ "modern", "intermediate", "old", "custom" ], "default": "intermediate" }, "customSuites": { "title": "Custom cipher suites (in server preference order)", "description": "OpenSSL names (ECDHE-RSA-AES128-GCM-SHA256), IANA names (TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) or hex codes (0xC02F), separated by colons, commas or new lines. OpenSSL keywords like HIGH or !aNULL are not expanded. Used only with \"Custom cipher list\".", "type": "string", "maxLength": 20000 }, "customProtocols": { "title": "Custom: enabled protocol versions", "type": "array", "items": { "type": "string", "enum": [ "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] }, "customGroups": { "title": "Custom: key-exchange groups", "description": "Curve/group names in preference order, e.g. X25519MLKEM768, X25519, prime256v1, secp384r1, ffdhe2048.", "type": "string", "default": "X25519, prime256v1, secp384r1" }, "certificate": { "title": "Server certificate", "type": "string", "enum": [ "preset", "ecdsa", "rsa", "both" ], "default": "preset" }, "rsaBits": { "title": "RSA key size", "type": "integer", "minimum": 512, "maximum": 16384, "default": 2048, "x-unit": "bits" }, "dhBits": { "title": "DHE parameter size", "description": "Optional. Defaults to the preset value (old: 1024, intermediate: 2048) or 2048 for custom lists.", "type": "integer", "minimum": 512, "maximum": 8192, "x-unit": "bits" }, "order": { "title": "Cipher order", "type": "string", "enum": [ "preset", "server", "client" ], "default": "preset" }, "clients": { "title": "Clients to simulate", "description": "Leave empty to simulate all clients.", "type": "array", "items": { "type": "string", "enum": [ "android-2.3.7", "android-4.4.2", "android-5.0.0", "android-7.0", "android-8.1", "android-9.0", "chrome-49-xp-sp3", "chrome-70-win-10", "chrome-80-win-10", "chrome-131-win-10", "firefox-31.3.0-esr-win-7", "firefox-62-win-7", "firefox-73-win-10", "firefox-135-win-10", "edge-15-win-10", "edge-131-win-10", "ie-8-xp", "ie-11-win-7", "ie-11-win-10", "safari-9-ios-9", "safari-10-os-x-10.12", "safari-12.1.2-macos-10.14.6-beta", "safari-12.1.1-ios-12.3.1", "java-6u45", "java-7u25", "java-8u31", "java-8u161", "java-11.0.3", "java-12.0.1", "openssl-0.9.8y", "openssl-1.0.1l", "openssl-1.0.2s", "openssl-1.1.0k", "openssl-1.1.1c", "curl-openssl-1.1.1", "curl-openssl-1.0.2" ] } } }, "required": [] }, "TlsCipherSuiteSimulatorResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "server", "grade", "gradeReasons", "clientsSimulated", "handshakesOk", "handshakesFailed", "results", "unknownSuites", "suiteTable", "datasetDate" ], "properties": { "server": { "type": "object", "additionalProperties": false, "required": [ "label", "protocols", "suites12", "suites13", "groups", "certificates", "rsaBits", "dhBits", "serverOrder" ], "properties": { "label": { "type": "string" }, "protocols": { "type": "array", "items": { "type": "string" } }, "suites12": { "type": "array", "items": { "type": "string" } }, "suites13": { "type": "array", "items": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } }, "certificates": { "type": "array", "items": { "type": "string" } }, "rsaBits": { "type": "integer" }, "dhBits": { "type": [ "integer", "null" ] }, "serverOrder": { "type": "boolean" } } }, "grade": { "type": "string" }, "gradeReasons": { "type": "array", "items": { "type": "string" } }, "clientsSimulated": { "type": "integer" }, "handshakesOk": { "type": "integer" }, "handshakesFailed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "client", "clientId", "ok", "protocol", "cipher", "cipherOpenssl", "keyExchange", "group", "signature", "certificate", "forwardSecrecy", "aead", "helloRetry", "failure", "notes" ], "properties": { "client": { "type": "string" }, "clientId": { "type": "string" }, "ok": { "type": "boolean" }, "protocol": { "type": [ "string", "null" ] }, "cipher": { "type": [ "string", "null" ] }, "cipherOpenssl": { "type": [ "string", "null" ] }, "keyExchange": { "type": [ "string", "null" ] }, "group": { "type": [ "string", "null" ] }, "signature": { "type": [ "string", "null" ] }, "certificate": { "type": [ "string", "null" ] }, "forwardSecrecy": { "type": [ "boolean", "null" ] }, "aead": { "type": [ "boolean", "null" ] }, "helloRetry": { "type": "boolean" }, "failure": { "type": [ "string", "null" ] }, "notes": { "type": "array", "items": { "type": "string" } } } } }, "unknownSuites": { "type": "array", "items": { "type": "string" } }, "suiteTable": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "iana", "openssl", "keyExchange", "auth", "aead", "forwardSecrecy", "minVersion", "ianaRecommended", "weakness" ], "properties": { "code": { "type": "string" }, "iana": { "type": "string" }, "openssl": { "type": [ "string", "null" ] }, "keyExchange": { "type": "string" }, "auth": { "type": "string" }, "aead": { "type": "boolean" }, "forwardSecrecy": { "type": "boolean" }, "minVersion": { "type": "string" }, "ianaRecommended": { "type": "string" }, "weakness": { "type": [ "string", "null" ] } } } }, "datasetDate": { "type": "string" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }