# KeyMaster Servlets

KeyMaster includes two example servlets:

* Standard KeyMaster servlet
* Poll servlet

## Standard KeyMaster servlet

The KeyMaster Java kit includes the `StandardKeyMasterServlet` token generator example servlet. You can use this example as the basis for your own custom token generator servlet.

This servlet can be configured via servlet parameters in the associated `web.xml`:

**Example web.xml config for StandardKeyMasterServlet**

```xml
<servlet>
  <servlet-name>StandardKeyMaster</servlet-name>
  <servlet-class>com.caplin.keymaster.servlet.StandardKeyMasterServlet</servlet-class>
  <init-param>
    <param-name>caplin.keymaster.privatekey.filename</param-name>
    <param-value>private.pem</param-value>
    <description>Name of the private key filename</description>
  </init-param>
</servlet>
```

The following servlet parameters can be specified in the `web.xml`:

| Parameter | Type | Description |
| --- | --- | --- |
| caplin.keymaster.privatekey.filename | Required | The location of the PEM PKCS#8 formatted private key file relative to the webapp. |
| caplin.keymaster.hashing.algorithm | Optional | Hashing algorithm name. See the [com.caplin.keymaster.KeyMasterHashingAlgorithm](https://docs.caplin.com/developer/api/keymaster/latest/com/caplin/keymaster/KeyMasterHashingAlgorithm.html) enumeration for valid algorithm names. The default algorithm is SHA256. |
| caplin.keymaster.security.provider.class.name | Optional | Class name of a security provider to add to those available. |
| caplin.keymaster.security.provider.name | Optional | Name of security provider to use for the token generation. |

## Poll Servlet

The KeyMaster Java kit includes a Poll servlet. The StreamLink library polls this servlet regularly to prevent the user’s session with the web application server from timing out.

**Example web.xml config for the Poll servlet**

```xml
<servlet>
  <servlet-name>Poll</servlet-name>
  <servlet-class>com.caplin.keymaster.servlet.Poll</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>Poll</servlet-name>
  <url-pattern>/servlet/Poll</url-pattern>
</servlet-mapping>
```

To configure StreamLink with the URL for the Poll servlet, set the `keymaster_keep_alive_url` property in the configuration object for the StreamLink connection:

**Specifying the URL of the KeyMaster Poll servlet**

```js
var streamlink = caplin.streamlink.StreamLinkFactory.create({
  liberator_urls: [
    "rttps://primary-liberator.example.com",
    "rttps://secondary-liberator.example.com"
  ],
  keymaster_url: "servlet/StandardKeyMaster",
  keymaster_keep_alive_url: "servlet/Poll"
});
```

To receive a callback after each call to the Poll servlet, set a value of [`KeymasterPollResponseListener`](https://docs.caplin.com/developer/api/streamlinkjs/latest/classes/KeymasterPollResponseListener.html) to the `keymaster_keep_alive_listener` property of the configuration object for the StreamLink connection.

**Specifying a callback handler for KeyMaster Poll servlet requests**

```js
caplin.streamlink.StreamLinkFactory.create({
  liberator_urls: [
    "rttps://primary-liberator.example.com",
    "rttps://secondary-liberator.example.com"
  ],
  keymaster_url: "servlet/StandardKeyMaster",
  keymaster_keep_alive_url: "servlet/Poll",
  keymaster_keep_alive_listener: {
    onKeymasterError: function(reason) {
      console.log("KeyMaster Failed due to : " + reason);
    },
    onKeymasterResponse : function(response) {
      console.log("KeyMaster Success. Response Message : " + response);
    }
  }
});
```

---

**See also:**

* [KeyMaster Concepts](keymaster-keymaster-concepts.md)
* [KeyMaster Java API](https://docs.caplin.com/developer/api/keymaster/latest/#overview_description)
* [StreamLink](../streamlink/index.md)