---
title: "HTTPS"
slug: "/security/how-to-use-https"
keyword: "security HTTPS protocol"
license: "This software is licensed under the Apache License version 2."
---

## Introduction

For users choosing OAuth 2.0 as the authentication method, it is recommended to use HTTPS instead of HTTP. HTTPS encrypts the request headers, offering better protection against smuggling attacks.

Note that Gravitino cannot simultaneously support both HTTP and HTTPS within a single server instance. If HTTPS is enabled, Gravitino will no longer provide HTTP service.

Both the Gravitino server and Iceberg REST service can configure and support HTTPS.

### Apache Gravitino Server Configuration

| Configuration item                                  | Description                                                        | Default value       | Required                                          | Since version |
|-----------------------------------------------------|--------------------------------------------------------------------|---------------------|---------------------------------------------------|---------------|
| `gravitino.server.webserver.enableHttps`            | Enables HTTPS.                                                     | `false`             | No                                                | 0.3.0         |
| `gravitino.server.webserver.httpsPort`              | The HTTPS port number of the Jetty web server.                     | `8433`              | No                                                | 0.3.0         |
| `gravitino.server.webserver.keyStorePath`           | Path to the key store file.                                        | (none)              | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.server.webserver.keyStorePassword`       | Password to the key store.                                         | (none)              | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.server.webserver.keyStoreType`           | The type to the key store.                                         | `JKS`               | No                                                | 0.3.0         |
| `gravitino.server.webserver.managerPassword`        | Manager password to the key store.                                 | (none)              | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.server.webserver.tlsProtocol`            | TLS protocol to use. The JVM must support the TLS protocol to use. | (none)              | No                                                | 0.3.0         |
| `gravitino.server.webserver.enableCipherAlgorithms` | The collection of enabled cipher algorithms.                       | '' (empty string)   | No                                                | 0.3.0         |
| `gravitino.server.webserver.enableClientAuth`       | Enables the authentication of the client.                          | `false`             | No                                                | 0.3.0         |
| `gravitino.server.webserver.trustStorePath`         | Path to the trust store file.                                      | (none)              | Yes if use HTTPS and the authentication of client | 0.3.0         |
| `gravitino.server.webserver.trustStorePassword`     | Password to the trust store.                                       | (none)              | Yes if use HTTPS and the authentication of client | 0.3.0         |
| `gravitino.server.webserver.trustStoreType`         | The type to the trust store.                                       | `JKS`               | No                                                | 0.3.0         |

### Apache Iceberg REST Service Configuration

| Configuration item                              | Description                                                        | Default value     | Required                                          | Since version |
|-------------------------------------------------|--------------------------------------------------------------------|-------------------|---------------------------------------------------|---------------|
| `gravitino.iceberg-rest.enableHttps`            | Enables HTTPS.                                                     | `false`           | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.httpsPort`              | The HTTPS port number of the Jetty web server.                     | `9433`            | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.keyStorePath`           | Path to the key store file.                                        | (none)            | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.iceberg-rest.keyStorePassword`       | Password to the key store.                                         | (none)            | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.iceberg-rest.keyStoreType`           | The type to the key store.                                         | `JKS`             | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.managerPassword`        | Manager password to the key store.                                 | (none)            | Yes if use HTTPS                                  | 0.3.0         |
| `gravitino.iceberg-rest.tlsProtocol`            | TLS protocol to use. The JVM must support the TLS protocol to use. | (none)            | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.enableCipherAlgorithms` | The collection of enabled cipher algorithms.                       | '' (empty string) | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.enableClientAuth`       | Enables the authentication of the client.                          | `false`           | No                                                | 0.3.0         |
| `gravitino.iceberg-rest.trustStorePath`         | Path to the trust store file.                                      | (none)            | Yes if use HTTPS and the authentication of client | 0.3.0         |
| `gravitino.iceberg-rest.trustStorePassword`     | Password to the trust store.                                       | (none)            | Yes if use HTTPS and the authentication of client | 0.3.0         |
| `gravitino.iceberg-rest.trustStoreType`         | The type to the trust store.                                       | `JKS`             | No                                                | 0.3.0         |

Refer to the "Additional JSSE Standard Names" section of the [Java security guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#jssenames) for the list of protocols related to tlsProtocol. You can find the list of `tlsProtocol` values for Java 8 in this document.

Refer to the "Additional JSSE Standard Names" section of the [Java security guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites) for the list of protocols related to tlsProtocol. You can find the list of `enableCipherAlgorithms` values for Java 8 in this document.

### Example

Follow these steps to set up an HTTPS server:

1. Prerequisite
   - You need to install the JDK8, wget, and set the environment JAVA_HOME.
   - If you want to use the command `curl` to request the Gravitino server, you should install openSSL.
2. Generate the key store

```shell
cd $JAVA_HOME
bin/keytool -genkeypair  -alias localhost \
-keyalg RSA -keysize 4096 -keypass localhost \
-sigalg SHA256withRSA \
-keystore localhost.jks -storetype JKS -storepass localhost \
-dname "cn=localhost,ou=localhost,o=localhost,l=beijing,st=beijing,c=cn" \
-validity 36500
```

3. Generate the certificate

```shell
bin/keytool -export -alias localhost -keystore localhost.jks -file  localhost.crt -storepass localhost
```

4. Import the certificate

```shell
bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts -file localhost.crt -storepass changeit -noprompt
```

5. Refer to the [Configurations](../gravitino-server-config.md) and append the configuration to the conf/gravitino.conf.
   Configuration doesn't support resolving environment variables, so you should replace `${JAVA_HOME}` with the actual value.
   Then, You can start the Gravitino server.

```text
gravitino.server.webserver.host = localhost
gravitino.server.webserver.enableHttps = true
gravitino.server.webserver.keyStorePath = ${JAVA_HOME}/localhost.jks
gravitino.server.webserver.keyStorePassword = localhost
gravitino.server.webserver.managerPassword = localhost
```

6. Request the Gravitino server

- If you use Java, you can copy the code below to a file named Main.java

```java
import org.apache.gravitino.client.GravitinoClient;
import org.apache.gravitino.client.GravitinoVersion;

public class Main {
    public static void main(String[] args) {
        String uri = "https://localhost:8433";
        GravitinoClient client = GravitinoClient.builder(uri).withMetalake("metalake").build();
        GravitinoVersion gravitinoVersion = client.getVersion();
        System.out.println(gravitinoVersion);
    }
}
```

- If you want to use the command `curl`, you can follow the commands:

```shell
openssl x509 -inform der -in $JAVA_HOME/localhost.crt -out certificate.pem
curl -v -X GET --cacert ./certificate.pem -H "Accept: application/vnd.gravitino.v1+json" -H "Content-Type: application/json" https://localhost:8433/api/version
```
