How to use HTTPS
HTTPS
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.
Currently, both the Gravitino server and Iceberg REST service can configure and support HTTPS.
Apache Gravitino server's 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's 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 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 for the list of protocols related to tlsProtocol. You can find the list of enableCipherAlgorithms
values for Java 8 in this document.
Example
You can follow the steps to set up an HTTPS server.
- 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.
- Generate the key store
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
- Generate the certificate
bin/keytool -export -alias localhost -keystore localhost.jks -file localhost.crt -storepass localhost
- Import the certificate
bin/keytool -import -alias localhost -keystore jre/lib/security/cacerts -file localhost.crt -storepass changeit -noprompt
- You can refer to the Configurations 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.
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
- Request the Gravitino server
- If you use Java, you can copy the code below to a file named Main.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:
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