DOCSEARCHbyAlgolia
Submit Docs

MochiWeb Documentation

repository·main·Indexed 23 days ago

https://github.com/mochi/mochiweb

MochiWeb is an Erlang library for building lightweight, fast, and robust HTTP servers, specifically designed for resource-constrained environments. The documentation covers project scaffolding, Erlang OTP compatibility warnings, and a reference implementation for an Amazon-style HMAC authentication exchange for machine-to-machine communication.

Tokens
1.2K
Snippets
2
Records
6
Agent score
34%

What's inside MochiWeb

  1. Get started with MochiWeb

    main

    MochiWeb is an Erlang library for building lightweight, fast, and robust HTTP servers. To get started, ensure you have Erlang OTP installed. You can clone the repository and use the provided make command to scaffold a new project.

    1. Clone the repository

    $ git clone git://github.com/mochi/mochiweb.git.

    2. Create a new project

    Navigate into the cloned directory and use the make app command, specifying your desired project name with the PROJECT variable:

    $ cd mochiweb
$ make app PROJECT=exampleName

    3. Run the project

    Navigate to your newly created project directory, build it, and run the development script:

    $ cd ../exampleName/
$ make
$ ./start-dev.sh

    By default, the application is accessible at http://localhost:8080.

    $ git clone git://github.com/mochi/mochiweb.git.
$ cd mochiweb
$ make app PROJECT=exampleName
$ cd ../exampleName/
$ make
$ ./start-dev.sh

  2. Understand the Amazon-style HMAC authentication exchange

    main

    This authentication schema is designed for machine-to-machine communication using a public/private key pair. It is suitable for non-SSL API requests but is vulnerable to replay attacks within a short time window (typically 15 minutes) due to allowed clock skew.

    The Exchange Process

    1. Key Issuance: The client is issued a public key (identity) and a private key (secret). The private key is never sent over the wire.
    2. Canonicalization: The client prepares a request (URL, time, action, content type, body, etc.) and converts it into a standardized string called the canonical form. This ensures that different HTTP representations of the same request result in the same string.
    3. Signing: The client creates a hash of the canonical form using the private key.
    4. Request: The client sends the request with an Authorization header in the format: <schema name><space><public key><colon><signature> Example: Authorization: AWS 0PN5J17HBGZHT7JJ3X82:frJIUN8DYpKDtOLCwo//yllqDzg=
    5. Verification: The server:
      • Extracts the public key from the header and looks up the corresponding private key.
      • Reconstructs the canonical form from the received request.
      • Signs the reconstructed form with the private key.
      • Compares its generated signature with the one in the request.
      • Checks the request timestamp against the server time (allowing for a 'clock skew' window).

    Preventing Replay Attacks

    To prevent replay attacks, the schema can be extended using a nonce token. The server issues a random string (nonce) which must be included in the signature. The server then tracks used tokens to ensure a request cannot be replayed. The client receives the next nonce in the response of a successful request.

  3. Customize the HMAC API implementation

    main

    You can create a custom API implementation by modifying the constants defined in hmac_api.hrl.

    Simple Customization

    To change the identity of your API, modify these three constants:

    • schema
    • headerprefix
    • dateheader

    Note: If you want to maintain compatibility with existing client libraries, use the values currently commented out in hmac_api.hrl.

    Advanced Customization

    For more complex requirements, you may need to modify the canonicalization functions to change how the request string is constructed. Using a generic schema is recommended to facilitate easier reuse of client libraries across different platforms.

  4. Set up the HMAC API reference implementation

    main

    To run the reference implementation provided in this example, follow these steps:

    1. Initialize Project: Create a new mochiweb project:
      make app PROJECT=project_name
    2. Copy Files: Move the example files into your project structure:
      • Copy hmac_api_lib.erl and hmac_api_client.erl into project_name/src.
      • Copy hmac_api.hrl into project_name/include.
    3. Integrate Authorization: Edit project_name_web.erl to call hmac_api_lib:authorize_request/1 within the request loop:
      loop(Req, DocRoot) ->
        Auth = hmac_api_lib:authorize_request(Req),
        io:format("Auth is ~p~n", [Auth]),
        "/" ++ Path = mochiweb_request:get(path, Req),
        ...
    4. Build and Run:
      • Run make in project_name/ to build the Erlang application.
      • Start the server using ./start-dev.sh in project_name/.
    5. Test: In the resulting Erlang shell, execute:
      hmac_api_client:fire().
    make app PROJECT=project_name