{"id":13540103,"url":"https://github.com/tls-attacker/TLS-Attacker","last_synced_at":"2025-04-02T06:32:08.048Z","repository":{"id":37093370,"uuid":"56690117","full_name":"tls-attacker/TLS-Attacker","owner":"tls-attacker","description":"TLS-Attacker is a Java-based framework for analyzing TLS libraries. It can be used to manually test TLS clients and servers or as as a software library for more advanced tools.","archived":false,"fork":false,"pushed_at":"2024-04-16T18:26:53.000Z","size":30333,"stargazers_count":768,"open_issues_count":18,"forks_count":132,"subscribers_count":58,"default_branch":"main","last_synced_at":"2024-05-21T15:26:34.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tls-attacker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-20T13:40:59.000Z","updated_at":"2024-06-21T19:01:38.221Z","dependencies_parsed_at":"2024-06-21T19:01:30.615Z","dependency_job_id":"cc4ae0bf-07d1-47da-a675-0a758650dd30","html_url":"https://github.com/tls-attacker/TLS-Attacker","commit_stats":null,"previous_names":["rub-nds/tls-attacker"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tls-attacker%2FTLS-Attacker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tls-attacker%2FTLS-Attacker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tls-attacker%2FTLS-Attacker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tls-attacker%2FTLS-Attacker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tls-attacker","download_url":"https://codeload.github.com/tls-attacker/TLS-Attacker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246768364,"owners_count":20830653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T09:01:40.491Z","updated_at":"2025-04-02T06:32:08.033Z","avatar_url":"https://github.com/tls-attacker.png","language":"Java","funding_links":[],"categories":["\u003ca id=\"86d5daccb4ed597e85a0ec9c87f3c66f\"\u003e\u003c/a\u003eTLS\u0026\u0026SSL\u0026\u0026HTTPS","\u003ca id=\"43b0310ac54c147a62c545a2b0f4bce2\"\u003e\u003c/a\u003e辅助周边","安全"],"sub_categories":["\u003ca id=\"776c034543a65be69c061d1aafce3127\"\u003e\u003c/a\u003e新添加的","\u003ca id=\"86d5daccb4ed597e85a0ec9c87f3c66f\"\u003e\u003c/a\u003eTLS\u0026\u0026SSL\u0026\u0026HTTPS"],"readme":"# TLS-Attacker\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/tls-attacker/TLS-Attacker)\n![licence](https://img.shields.io/badge/License-Apachev2-brightgreen.svg)\n[![Build Status](https://hydrogen.cloud.nds.rub.de/buildStatus/icon.svg?job=TLS-Attacker)](https://hydrogen.cloud.nds.rub.de/job/TLS-Attacker/)\n\nTLS-Attacker is a Java-based framework for analyzing TLS libraries. It is able to send arbitrary protocol messages in an arbitrary order to the TLS peer, and define their modifications using a provided interface. This gives the developer an opportunity to easily define a custom TLS protocol flow and test it against his TLS library.\n\n**Please note:**  *TLS-Attacker is a research tool intended for TLS developers and pentesters. There is no GUI and no green/red lights.*\n\n## Compiling and Running\n\nIn order to compile and use TLS-Attacker, you need to have Java and Maven installed. On Ubuntu you can install Maven by running:\n\n```bash\n$ sudo apt-get install maven\n```\n\nTLS-Attacker currently needs Java JDK 21 to run.\n\nIf you have the correct Java version you can run the maven command from the TLS-Attacker directory:\n\n```bash\n$ git clone https://github.com/tls-attacker/TLS-Attacker.git\n$ cd TLS-Attacker\n$ mvn clean install\n```\n\nAlternatively, if you are in a hurry, you can skip the tests by using:\n\n```bash\n$ mvn clean install -DskipTests=true\n```\n\nThe resulting jar files are placed in the \"apps\" folder.\n\nIf you want to use this project as a dependency, you do not have to compile it yourself and can include it in your pom\n.xml as follows.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.rub.nds.tls.attacker\u003c/groupId\u003e\n    \u003cartifactId\u003etls-attacker\u003c/artifactId\u003e\n    \u003cversion\u003e7.0.0\u003c/version\u003e\n    \u003ctype\u003epom\u003c/type\u003e\n\u003c/dependency\u003e\n```\n\nTLS-Attacker ships with demo applications which provide you easy access to TLS-Attacker functionality.\n\nYou can run TLS-Attacker as a client with the following command:\n\n```bash\n$ cd apps\n$ java -jar TLS-Client.jar -connect [host:port]\n```\n\nor as a server with:\n\n```bash\n$ java -jar TLS-Server.jar -port [port]\n```\n\nTLS-Attacker also ships with some example attacks on TLS to show you how easy it is to implement an attack with TLS-Attacker.\nYou can run those examples with the following command:\n\n```bash\n$ java -jar Attacks.jar [Attack] -connect [host:port]\n```\n\nAlthough these example applications are very powerful in itself, TLS-Attacker unleashes its full potential when used as a programming library.\n\n## Code Structure\n\nTLS-Attacker consists of several (maven) projects:\n- TLS-Client: The client example application\n- TLS-Core: The protocol stack and heart of TLS-Attacker\n- TLS-Mitm: A prototype for MitM workflows\n- TLS-Server: The server example application\n- TLS-Proxy: Use TLS-Attacker for SSLSockets\n- TraceTool: Inspection and modification of TLS-Attacker workflow traces\n- Transport: Transport utilities for lower layers\n- Utils: A collection of utility classes\n\n![TLS-Attacker design](https://github.com/tls-attacker/TLS-Attacker/blob/master/resources/figures/design.png)\n\nYou can find more information about these modules in the Wiki.\n\n## Features\n\nCurrently, the following features are supported:\n- SSL 3, TLS versions 1.0 (RFC-2246), 1.1 (RFC-4346), 1.2 (RFC-5246), and 1.3 (RFC-8446)\n- SSL 2 (Partially supported)\n- (EC)DH(E), RSA, PSK, SRP, GOST and ANON key exchange algorithms\n- CBC, AEAD and Streamciphers (AES, CAMELLIA, DES, 3DES, IDEA, RC2, ARIA, GOST_28147_CNT_IMIT, RC4, SEED, NULL)\n- ~300 Cipher suites, ~30 Extensions\n- Client and Server\n- HTTPS\n- Workflows with more than two parties\n- Lots of extensions\n- Tokenbinding (EC) and Tokenbinding over HTTP\n- Sockets\n- TLS 1.3 0-RTT\n- STARTTLS\n- ...\n\n## Usage\n\nHere we present some very simple examples on using TLS-Attacker.\n\nFirst, you need to start a TLS server (*please do not use public servers*). Please run the keygen.sh script if not done before. For example, you can use an OpenSSL test server:\n\n```\n$ cd TLS-Attacker/resources\n$ openssl s_server -key rsa1024key.pem -cert rsa1024cert.pem\n```\n\nThis command starts a TLS server on a port 4433.\n\nIf you want to connect to a server, you can use this command:\n\n```bash\n$ cd TLS-Attacker/apps\n$ java -jar TLS-Client.jar -connect localhost:4433\n```\n\n*Note: If this Handshake fails, it is probably because you did not specify a concrete cipher suite. TLS-Attacker will not completely respect server selected cipher suites.*\n\nYou can use a different cipher suite, TLS version, or connect to a different port with the following parameters:\n\n```bash\n$ java -jar TLS-Client.jar -connect localhost:4433 -cipher TLS_RSA_WITH_AES_256_CBC_SHA -version TLS11\n```\n\nIn case you are a more experienced developer, you can create your own TLS message flow by writing Java code. For example:\n\n```java\nConfig config = Config.createConfig();\nWorkflowTrace trace = new WorkflowTrace();\ntrace.addTlsAction(new SendAction(new ClientHelloMessage()));\ntrace.addTlsAction(new ReceiveAction(new ServerHelloMessage()));\nState state = new State(config, trace);\nDefaultWorkflowExecutor executor = new DefaultWorkflowExecutor(state);\nexecutor.executeWorkflow();\n```\n\nTLS-Attacker uses the concept of WorkflowTraces to define a \"TLS message flow\". A WorkflowTrace consists of a list of actions which are then executed one after the other. Although for a typical \"TLS message flow\" only SendAction's and ReceiveAction's are needed, the framework does not stop here and implements a lot of different other actions which can be used to execute even more arbitrary message flows. A list of currently implemented actions with explanations can be found in the Wiki.\n\nWe know many of you hate Java. Therefore, you can also use an XML structure and run your customized TLS protocol from XML:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?\u003e\n\u003cworkflowTrace\u003e\n    \u003cSend\u003e\n        \u003cconfiguredMessages\u003e\n            \u003cClientHello\u003e\n                \u003cextensions\u003e\n                    \u003cECPointFormat/\u003e\n                    \u003cHeartbeatExtension/\u003e\n                    \u003cEllipticCurves/\u003e\n                \u003c/extensions\u003e\n            \u003c/ClientHello\u003e\n        \u003c/configuredMessages\u003e\n    \u003c/Send\u003e\n    \u003cReceive\u003e\n        \u003cexpectedMessages\u003e\n            \u003cServerHello\u003e\n                \u003cextensions\u003e\n                    \u003cECPointFormat/\u003e\n                \u003c/extensions\u003e\n            \u003c/ServerHello\u003e\n            \u003cCertificate/\u003e\n            \u003cServerHelloDone/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Receive\u003e\n    \u003cSend\u003e\n        \u003cconfiguredMessages\u003e\n            \u003cRSAClientKeyExchange\u003e\n                \u003ccomputations/\u003e\n            \u003c/RSAClientKeyExchange\u003e\n            \u003cChangeCipherSpec/\u003e\n            \u003cFinished/\u003e\n        \u003c/configuredMessages\u003e\n    \u003c/Send\u003e\n    \u003cReceive\u003e\n        \u003cexpectedMessages\u003e\n            \u003cChangeCipherSpec/\u003e\n            \u003cFinished/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Receive\u003e\n\u003c/workflowTrace\u003e\n```\n\nGiven this XML structure is located in TLS-Attacker/apps/workflow.xml, you would just need to execute:\n\n```bash\n$ java -jar TLS-Client.jar -connect [host]:[port] -workflow_input workflow.xml\n```\n\n## Protocol-Attacker/Layer System\n\nOriginally designed to attack the TLS protocol, TLS-Attacker is capable of supporting arbitrary protocols. To this end, TLS-Attacker assigns a layer stack to each connection. This layer stack consists of the different protocol layers the user wants to utilize. With the layer stack, the user can add layers like DTLS, or HTTP (more are WIP) in an arbitrary order.\n\nTo send and receive arbitrary messages using a layer stack, the user can define configurations for each layer. These configurations specifiy which messages to send or receive. This also allows the user to specify the layer specific messages/data containers for each layer. For example, one could specify the TLS messages and records TLS-Attacker should send. TLS-Attacker would encapsulate the given TLS messages into the records automatically.\n\n## Modifiable Variables\n\nTLS-Attacker uses the concept of Modifiable Variables to allow runtime modifications to predefined Workflows. Modifiable variables allow one to set modifications to basic types after or before their values are actually set. When their actual values are determined and one tries to access the value via getters the original value will be returned in a modified form accordingly. More details on this concept can be found at https://github.com/tls-attacker/ModifiableVariable.\n\n```java\nModifiableInteger i = new ModifiableInteger();\ni.setOriginalValue(30);\ni.setModification(new AddModification(20));\nSystem.out.println(i.getValue());  // 50\n```\n\nIn this example, we defined a new ModifiableInteger and set its value to 30. Next, we defined a new modification AddModification which simply returns a sum of two integers. We set its value to 20. If we execute the above program, the result 50 is printed.\n\nWe can of course use this concept by constructing our TLS workflows. Imagine you want to test a server for a heartbleed vulnerability. For this purpose, you need to increase the payload length in the heartbeat request. With TLS-Attacker, you can do this as follows:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?\u003e\n\u003cworkflowTrace\u003e\n    \u003cSend\u003e\n        \u003cconfiguredMessages\u003e\n            \u003cClientHello\u003e\n                \u003cextensions\u003e\n                    \u003cECPointFormat/\u003e\n                    \u003cHeartbeatExtension/\u003e\n                    \u003cEllipticCurves/\u003e\n                \u003c/extensions\u003e\n            \u003c/ClientHello\u003e\n        \u003c/configuredMessages\u003e\n    \u003c/Send\u003e\n    \u003cReceive\u003e\n        \u003cexpectedMessages\u003e\n            \u003cServerHello\u003e\n                \u003cextensions\u003e\n                    \u003cECPointFormat/\u003e\n                \u003c/extensions\u003e\n            \u003c/ServerHello\u003e\n            \u003cCertificate/\u003e\n            \u003cServerHelloDone/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Receive\u003e\n    \u003cSend\u003e\n        \u003cexpectedMessages\u003e\n            \u003cRSAClientKeyExchange\u003e\n                \u003ccomputations/\u003e\n            \u003c/RSAClientKeyExchange\u003e\n            \u003cChangeCipherSpec/\u003e\n            \u003cFinished/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Send\u003e\n    \u003cReceive\u003e\n        \u003cexpectedMessages\u003e\n            \u003cChangeCipherSpec/\u003e\n            \u003cFinished/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Receive\u003e\n    \u003cSend\u003e\n        \u003cexpectedMessages\u003e\n            \u003cHeartbeat\u003e\n                \u003cpayloadLength\u003e\n                    \u003cIntegerExplicitValueModification\u003e\n                        \u003cexplicitValue\u003e20000\u003c/explicitValue\u003e\n                    \u003c/IntegerExplicitValueModification\u003e\n                \u003c/payloadLength\u003e\n            \u003c/Heartbeat\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Send\u003e\n    \u003cReceive\u003e\n        \u003cexpectedMessages\u003e\n            \u003cHeartbeat/\u003e\n        \u003c/expectedMessages\u003e\n    \u003c/Receive\u003e\n\u003c/workflowTrace\u003e\n```\n\nAs you can see, we explicitly increased the payload length of the heartbeat message by 20000.\nIf you run the attack against the vulnerable server (e.g., OpenSSL 1.0.1f), you should see a valid heartbeat response.\n\nFurther examples on attacks and further explanations on TLS-Attacker can be found in the wiki.\n\n## Advanced Features\n\nSome actions require context, or configuration to be executed correctly. For example, if TLS-Attacker tries to send a ClientHello message, it needs to know which values to\nput into the message, e.g., which Cipher suites or which protocol version to use. TLS-Attacker draws this information\nfrom a configuration file (default located in TLS-Core/src/main/resources/default_config.xml).\nValues which are determined at runtime are stored in the TlsContext. When a value which is normally selected from the context is missing (because a message was not yet received), the default value from the Config is selected. You can specify your own configuration file from command line with the \"-config\" parameter. Note that if you do not explicitly define a default value in the config file, TLS-Attacker fills\nthis gap with hardcoded values (which are equal to the provided default config). More details on how to customize TLS-Attacker can be found in the wiki.\n\n## Acknowledgements\n\nWe would like to thank everyone who has contributed to the TLS-Attacker project.\n\nA special thanks goes to the following peoples for their notable contributions:\n\nMuhammad Abubakar, Fabian Albert, Panneer Selvam Annadurai, Nimrod Aviram, Philipp Brinkmann, Till Budde, Florian Bürger, Christoph Buttler, Jens Carl, Raphael Dietrich, Felix Dreissig, Bastian Ebach, Malena Ebert, Robert Engel, Nils Engelbertz, Paul Fiterau Brostean, Janis Fliegenschmidt, Alexander Freiherr von Buddenbrock, Matthias Manfred Geuchen, Alexander Glasfort, Nils Hanke, Lucas Hartmann, Bastian Haverkamp, Nico Heitmann, Jannik Hölling, Selami Hoxha, Kevin Jagla, Nils Kafka, Jan Kaiser, Anton Khristoforov, Felix Kleine-Wilde, Mario Korth, Sebastian Krois, Christian Krug, Florian Linsner, Christian Mainka, Jonas Moos, Simon Nachtigall, Simon Nattefort, Philipp Nieting, Niels Pahl, Christoph Penkert, Florian Pfützenreuter, Adrian Pinner, Malte Poll, Christian Pressler, Tim Reisach, Philip Riese, Nils Luca Rudminat, Henrik Schaefer, Marten Schmidt, Conrad Schmidt, Daniel Siegert, Tim Storm, Rigers Sulku, Bjarne Tempel, Matthias Terlinde, Jonas Thiele, Pierre Tilhaus, Joshua Waldner, Patrick Weixler, Philipp Wirth, Asli Yardim, Dennis Ziebart, David Ziemann, Philipp Ziemke\n\nFurther contributions and pull requests are welcome.\n\n## Scientific Papers\n\nThe basic concepts behind TLS-Attacker and several attacks are described in the following paper:\n- Juraj Somorovsky. Systematic Fuzzing and Testing of TLS Libraries. ACM CCS'16. https://www.nds.rub.de/research/publications/systematic-fuzzing-and-testing-tls-libraries\n\nBelow, we list recent scientific studies that utilized TLS-Attacker. You can find the full list in the [Wiki](https://github.com/tls-attacker/TLS-Attacker-Development/wiki/Scientific-Papers-and-Projects)\n- Michael Scott. 2023. On TLS for the Internet of Things, in a Post Quantum world.\nhttps://eprint.iacr.org/2023/095\n- Yong Wang, Rui Wang, Xin Liu, Donglan Liu, Hao Zhang, Lei Ma, Fangzhe Zhang,\nLili Sun, and Zhenghao Li. 2023. A Framework for TLS Implementation Vulnerability Testing in 5G. In Applied Cryptography and Network Security Workshops, ACNS 2023 Satellite Workshop https://link.springer.com/chapter/10.1007/978-3-031-41181-6_16\n- Diana Gratiela Berbecaru and Giuseppe Petraglia. 2023. TLS-Monitor: A Monitor\nfor TLS Attacks. In 2023 IEEE 20th Consumer Communications \u0026 Networking\nConference (CCNC). https://ieeexplore.ieee.org/document/10059989\n- Paul Fiterau-Brostean, Bengt Jonsson, Konstantinos Sagonas, and Fredrik Tåquist. 2023. Automata-Based Automated Detection of State Machine Bugs in Protocol\nImplementations. In 30th Annual Network and Distributed System Security Symposium, NDSS 2023 https://www.ndss-symposium.org/ndss-paper/automata-based-automated-detection-of-state-machine-bugs-in-protocol-implementations/\n- Sven Hebrok, Simon Nachtigall, Marcel Maehren, Nurullah Erinola, Robert Merget, Juraj Somorovsky, and Jörg Schwenk. 2023. We Really Need to Talk About\nSession Tickets: A Large-Scale Analysis of Cryptographic Dangers with TLS\nSession Tickets. In 32nd USENIX Security Symposium, USENIX Security 2023 https://www.usenix.org/conference/usenixsecurity23/presentation/hebrok\n- Nurullah Erinola, Marcel Maehren, Robert Merget, Juraj Somorovsky, and Jörg\nSchwenk. 2023. Exploring the Unknown DTLS Universe: Analysis of the DTLS\nServer Ecosystem on the Internet. In 32nd USENIX Security Symposium, USENIX\nSecurity 2023 https://www.usenix.org/conference/usenixsecurity23/presentation/erinola\n- Ka Lok Wu, Man Hong Hue, Ngai Man Poon, Kin Man Leung, Wai Yin Po,\nKin Ting Wong, Sze Ho Hui, and Sze Yiu Chau. 2023. Back to School: On the\n(In)Security of Academic VPNs. In 32nd USENIX Security Symposium, USENIX\nSecurity 2023 https://www.usenix.org/conference/usenixsecurity23/presentation/wu-ka-lok\n- Diana Gratiela Berbecaru and Antonio Lioy. 2024. Threat-TLS: A Tool for Threat\nIdentification in Weak, Malicious, or Suspicious TLS Connections. In Proceedings\nof the 19th International Conference on Availability, Reliability and Security (Vienna,\nAustria) (ARES ’24) https://dl.acm.org/doi/10.1145/3664476.3670945\n- Maximilian Radoy, Sven Hebrok, and Juraj Somorovsky. 2024. In Search of Partitioning Oracle Attacks Against TLS Session Tickets. In 29th European Symposium\non Research in Computer Security (ESORICS) https://link.springer.com/chapter/10.1007/978-3-031-70896-1_16\n- Martin Dunsche, Marcel Maehren, Nurullah Erinola, Robert Merget, Nicolai Bissantz, Juraj Somorovsky, and Jörg Schwenk. 2024. With Great Power Come Great\nSide Channels: Statistical Timing Side-Channel Analyses with Bounded Type-1\nErrors. In 33rd USENIX Security Symposium, USENIX Security 2024 https://www.usenix.org/conference/usenixsecurity24/presentation/dunsche\n\nIf you have any research ideas or need support feel free to contact us on Twitter (@ic0nz1 , @jurajsomorovsky , @marcelmaehren , @nerinola1 , @JonSnowWhite2) or at https://www.hackmanit.de/.\n\nIf TLS-Attacker helps you to find a bug in a TLS implementation, please acknowledge this tool. Thank you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftls-attacker%2FTLS-Attacker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftls-attacker%2FTLS-Attacker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftls-attacker%2FTLS-Attacker/lists"}