DOCSEARCHbyAlgolia
Submit Docs

Message Security Layer (MSL)

repository·master·Indexed 20 days ago

https://github.com/netflix/msl

An extensible and flexible secure messaging framework designed to transport data between communicating entities, supporting confidentiality and non-replayable properties. MSL provides implementations for Java, JavaScript, and C++, featuring core abstractions like MslControl, MslContext, and MessageContext, as well as support for ECC, JWE, and RSA cryptography.

Tokens
9.1K
Snippets
29
Records
40
Agent score
66%

What's inside msl

  1. Core MSL Abstractions: MslControl, MslContext, and MessageContext

    master

    The MSL stack is built around three primary configuration and control abstractions that manage how entities communicate securely:

    • MslControl: The primary application interface to the MSL stack. An application should typically use only one instance of MslControl.
    • MslContext: Represents the configuration for a single MSL network. An application can participate in multiple MSL networks by maintaining multiple instances of MslContext.
    • MessageContext: Used for message-specific configuration. This allows you to specify properties like the user or specific security requirements for an individual message.

  2. Getting Started with Java MSL

    master

    To use MSL in a Java environment:

    1. Project Import: Import the Java MSL code as a Gradle project.
      • IntelliJ IDEA: Import directly as a Gradle project.
      • Eclipse: Use the Gradle IDE plugin and Web Tools Platform.
    2. Dependencies: Ensure you have org.json and Bouncy Castle libraries available.
    3. Cryptography: If using cryptographic keys larger than standard sizes, you may need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.
    4. Examples:
      • A simple server example is located at examples/simple/src/main/java/server/.
      • A command line client and server are available in examples/mslcli/src/main/java/.

  3. Getting Started with C++ MSL

    master

    To use MSL in a C++ environment:

    1. Requirements: You must have C++11 and CMake installed.
    2. Dependencies: The codebase requires OpenSSL.
    3. Build Configuration:
      • For macOS (Xcode 8 + Homebrew), use these compiler flags:
        -std=c++0x -DGTEST_DONT_DEFINE_FAIL=1 -DRAPIDJSON_HAS_STDSTRING=1
      • For iOS (Xcode 8), use these compiler flags:
        -std=gnu++11 -DGTEST_DONT_DEFINE_FAIL=1 -DRAPIDJSON_HAS_STDSTRING=1

  4. Getting Started with JavaScript MSL

    master

    To use MSL in a JavaScript environment:

    1. Environment Requirements: Your environment must support the Web Crypto API.
    2. Browser Compatibility & Flags:
      • Chrome 37+: For older versions, enable chrome://flags/#enable-experimental-web-platform-features. On Linux, libnss 3.16.2+ must be installed.
      • Firefox 34+: For older versions, set about:config dom.webcrypto.enabled to true.
      • Edge, IE 11+, Safari 8+ are supported, but check browser release notes if Web Crypto operations fail due to algorithm or key size limitations.
    3. Integration: You must include all MSL JavaScript source files required by your specific configuration. A reference list of required files is available in src/test/javascript/msltests.html.
    4. Example: A simple client web page is provided at src/examples/simple/src/main/javascript/client/.

  5. Configure the MSL Burp Extender

    master

    To inspect MSL messages through a Burp proxy, you must configure the MSL Burp Extender to match your specific MSL environment. Because messages use specific authentication schemes, key exchange schemes, and crypto keys, the extender must be provided with the same configuration (specifically the @MslContext@) used by your trusted services server.

    For an example of a compatible configuration, refer to msl/util/WiretapMslContext.java which is compatible with the integration test server.

  6. Run the MSL Simple Java Server

    master

    The MSL Simple server is a Java servlet project. You can run it directly from an IDE or compile it into a WAR file for deployment on a web server with a servlet container. To run the server locally using Jetty on port 8080, execute the following Gradle command from the top-level directory of the repository:

    ./gradlew :msl-example:appRun

  7. Set up MSL integration tests

    master

    MSL integration tests verify end-to-end communication between a trusted services client and server using Java servlets and TestNG classes.

    To run the tests, follow these steps:

    1. Deploy the Server: Build and deploy the servlets located in java/com/netflix/msl/server/ to a Java application server such as Tomcat.
    2. Configure the Endpoint: Ensure the server is accessible at http://localhost:8080/msl-integ-tests/.
    3. Run the Client Tests: Execute the TestNG classes found in java/com/netflix/msl/client/.

    Important: Tests must be run sequentially. Running them in parallel will cause them to fail.

  8. Use the MSL Simple JavaScript Client

    master

    The MSL Simple client is a web-based JavaScript application. To use it, open the _src/main/javascript/client/SimpleClient.html_ file in your web browser. For production or testing environments, these files can be hosted on any web server, including the same server running the Java servlet.

    Open _src/main/javascript/client/SimpleClient.html_ in your browser

  9. Build the MSL CLI client and server

    master

    The MSL CLI consists of a client and a server. You must build the client and its distribution first, as the server depends on the client's MSLCLI common library. All build commands should be executed from the top-level directory where the gradlew binary is located.

    Follow these steps to build both components:

    1. Build the client and create the distribution:

      ./gradlew -p examples/mslcli/client compileJava
./gradlew -p examples/mslcli/client distZip

    2. Build the server and create the distribution:

      ./gradlew -p examples/mslcli/server compileJava
./gradlew -p examples/mslcli/server distZip

    3. Extract the distributions: Navigate to the respective build directories and unzip the generated files.

      cd examples/mslcli/client/build
unzip distributions/*.zip
cd ../../../../examples/mslcli/server/build
unzip distributions/*.zip
    # Build client
./gradlew -p examples/mslcli/client compileJava
./gradlew -p examples/mslcli/client distZip

# Build server
./gradlew -p examples/mslcli/server compileJava
./gradlew -p examples/mslcli/server distZip

# Extract distributions
cd examples/mslcli/client/build
unzip distributions/*.zip
cd ../../../../examples/mslcli/server/build
unzip distributions/*.zip

  10. Install and use the MSL Burp Extender with Burp Suite

    master

    Follow these steps to integrate the MSL Burp Extender into your security testing workflow:

    1. Start Burp Suite.
    2. Install the Extender: Create a JAR file from the MSL Burp Extender and install it into Burp Suite.
    3. Configure Proxy Settings: In Burp Suite, navigate to Proxy > Options to find the proxy URL that the client should use.
    4. Enable Invisible Proxying: In the Proxy > Options view, go to the Request Handling tab and enable Support Invisible Proxying.
    5. Set Up Connection: In Burp Suite, navigate to Options > Connections and set it to point to the real MSL server.

  11. Run the MSL CLI client and server

    master

    To test the MSL implementation, run the server and client in separate terminal sessions. The MSL server acts as a simple ECHO server that accepts arbitrary inputs.

    1. Start the Server: In one terminal, run the server script:

      ./server/build/distributions/*/bin/mslserver.sh

      To terminate the server, press Ctrl-C.

    2. Start the Client: In a second terminal, run the client script. You can view available options using the help command:

      ./client/build/distributions/*/bin/mslclient.sh help
# Or run with options
./client/build/distributions/*/bin/mslclient.sh [options]
    # Terminal 1: Start Server
./server/build/distributions/*/bin/mslserver.sh

# Terminal 2: Start Client
./client/build/distributions/*/bin/mslclient.sh help

  12. Use EntityAuthenticationScheme to identify authentication methods

    master

    The EntityAuthenticationScheme class in the netflix::msl::entityauth namespace is used to uniquely identify and describe different entity authentication methods. Each scheme is characterized by its name and whether it provides encryption and integrity protection.

    Commonly used static schemes include:

    • PSK: Pre-shared keys.
    • PSK_PROFILE: Pre-shared keys with entity profiles.
    • X509: X.509 public/private key pair.
    • RSA: RSA public/private key pair.
    • ECC: ECC public/private key pair.
    • NONE: Unauthenticated.
    • NONE_SUFFIXED: Unauthenticated suffixed.
    • MT_PROTECTED: Master token protected.
    • PROVISIONED: Provisioned.
    • INVALID: Invalid scheme.
    #include <entityauth/EntityAuthenticationScheme.h>

using namespace netflix::msl::entityauth;

// Accessing a predefined scheme
EntityAuthenticationScheme scheme = EntityAuthenticationScheme::X509;

// Checking properties
if (scheme.encrypts()) {
    // Handle encrypted communication
}

if (scheme.protectsIntegrity()) {
    // Handle integrity-protected communication
}