diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/CredentialSafeRedirects.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/CredentialSafeRedirects.kt index 5c9e7db..9c6e6f4 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/CredentialSafeRedirects.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/CredentialSafeRedirects.kt @@ -184,8 +184,21 @@ class CredentialSafeRedirects( connectTimeout: Duration?, readTimeout: Duration?, credentialQueryParameters: Set, + ): ClientHttpRequestFactory = overJdkClient(connectTimeout, readTimeout, credentialQueryParameters, null) + + /** + * As [overJdkClient], trusting [trustedCertificates] in place of the JVM's own authorities: + * for an API signed by an authority no public trust store carries, such as a Kubernetes + * cluster's. PEM, PEM with `\n` for its line breaks, or Base64 of PEM or DER. Only this + * factory's calls trust them. Null or blank is the JVM's own trust. + */ + fun overJdkClient( + connectTimeout: Duration?, + readTimeout: Duration?, + credentialQueryParameters: Set, + trustedCertificates: String?, ): ClientHttpRequestFactory = - overClient(SharedHttpClients.redirectRefusing(connectTimeout), readTimeout, credentialQueryParameters) + overClient(SharedHttpClients.redirectRefusing(connectTimeout, trustedCertificates), readTimeout, credentialQueryParameters) /** * As [overJdkClient], over a [client] the caller owns and closes with its own lifecycle. diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/LearnedApiSpec.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/LearnedApiSpec.kt index 88f402f..cab7695 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/LearnedApiSpec.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/LearnedApiSpec.kt @@ -17,6 +17,7 @@ package com.embabel.agent.api.client import com.embabel.agent.api.client.graphql.GraphQlLearner import com.embabel.agent.api.client.model.ApiModel +import com.embabel.agent.api.client.openapi.OpenApiClientProperties import com.embabel.agent.api.client.openapi.OpenApiLearner import com.embabel.agent.api.tool.progressive.ProgressiveTool import com.fasterxml.jackson.annotation.JsonTypeInfo @@ -55,12 +56,16 @@ sealed interface LearnedApiSpec { * @param serverVariables values for the `{name}` variables in an OpenAPI * spec's `servers` URLs, overriding their defaults. Ignored by spec types * whose endpoint is not templated. + * @param clientProperties how the tools' HTTP client is built: its timeouts, and the + * certificate authorities it trusts when the API is signed by one the JVM does not. + * Ignored by spec types that build their client another way. */ fun toFactory( tags: Set? = null, operationIds: Set? = null, nameOverride: String? = null, serverVariables: Map = emptyMap(), + clientProperties: OpenApiClientProperties = OpenApiClientProperties(), ): (ApiCredentials) -> ProgressiveTool /** @@ -86,6 +91,7 @@ sealed interface LearnedApiSpec { operationIds: Set?, nameOverride: String?, serverVariables: Map, + clientProperties: OpenApiClientProperties, ): (ApiCredentials) -> ProgressiveTool = { credentials -> // Use the ref-preserving parse so each `OpenApiOperationTool` // can emit `{"$ref": "#/$defs/Foo"}` markers in its output @@ -95,6 +101,7 @@ sealed interface LearnedApiSpec { val openApi = OpenApiLearner.parseSpecPreservingRefs(source, rawSpec) OpenApiLearner.buildTool( source, openApi, credentials, tags, operationIds, nameOverride, + clientProperties = clientProperties, serverVariables = serverVariables, ) } @@ -128,6 +135,7 @@ sealed interface LearnedApiSpec { operationIds: Set?, nameOverride: String?, serverVariables: Map, + clientProperties: OpenApiClientProperties, ): (ApiCredentials) -> ProgressiveTool = { credentials -> // GraphQL doesn't have OpenAPI tags or operationIds — // ignored. Filtering by GraphQL field name is a separate diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/SharedHttpClients.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/SharedHttpClients.kt index 656c7ca..f221dc2 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/SharedHttpClients.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/SharedHttpClients.kt @@ -30,10 +30,11 @@ import java.util.concurrent.ConcurrentHashMap * (#51, #52). A client is thread-safe and carries no per-request state, so nothing is lost by * sharing it: credentials, query parameters and the read timeout all travel with the request. * - * What cannot travel with the request is the redirect policy and the connect timeout, which are - * fixed when a client is built. Those are the keys: one client that follows redirects, and one - * that never does per distinct connect timeout. Connect timeouts come from configuration, so the - * number of distinct values is the number of configurations, not the number of tools. + * What cannot travel with the request is the redirect policy, the connect timeout and the + * certificate authorities trusted, which are fixed when a client is built. Those are the keys: one + * client that follows redirects, and one that never does per distinct connect timeout and set of + * trusted certificates. Both come from configuration, so the number of distinct values is the + * number of configurations, not the number of tools. * * The clients are never closed. Their threads are daemons, and there is one per key for the life * of the JVM, which is the bound this exists to establish. @@ -50,18 +51,35 @@ internal object SharedHttpClients { .build() } - /* Optional, because ConcurrentHashMap refuses a null key and "no connect timeout" is a key. */ - private val nonFollowing = ConcurrentHashMap, HttpClient>() + /* + * Optional, because ConcurrentHashMap refuses a null key and "no connect timeout" is a key. + * [trust] is the fingerprint of the certificates the client trusts in place of the JVM's own; + * empty for a client that trusts what the JVM does. + */ + private data class Key(val connectTimeout: Optional, val trust: String) + + private val nonFollowing = ConcurrentHashMap() /** * For credentialed calls, which [CredentialSafeRedirects] follows itself. This client must * never follow a redirect: if it did, a credential header would go with it to another origin. */ - fun redirectRefusing(connectTimeout: Duration?): HttpClient = - nonFollowing.computeIfAbsent(Optional.ofNullable(connectTimeout)) { key -> + fun redirectRefusing(connectTimeout: Duration?): HttpClient = redirectRefusing(connectTimeout, null) + + /** + * As [redirectRefusing], for an API signed by an authority the JVM does not trust: + * [trustedCertificates] (see [TrustedCertificates] for the forms it takes) are the only + * authorities this client accepts. Null or blank is the JVM's own trust. + */ + fun redirectRefusing(connectTimeout: Duration?, trustedCertificates: String?): HttpClient { + val certificates = trustedCertificates?.takeIf { it.isNotBlank() }?.let(TrustedCertificates::parse) + val key = Key(Optional.ofNullable(connectTimeout), certificates?.let(TrustedCertificates::fingerprint).orEmpty()) + return nonFollowing.computeIfAbsent(key) { HttpClient.newBuilder() .followRedirects(HttpClient.Redirect.NEVER) - .apply { key.ifPresent { connectTimeout(it) } } + .apply { key.connectTimeout.ifPresent { connectTimeout(it) } } + .apply { certificates?.let { sslContext(TrustedCertificates.sslContext(it)) } } .build() } + } } diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/TrustedCertificates.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/TrustedCertificates.kt new file mode 100644 index 0000000..988adad --- /dev/null +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/TrustedCertificates.kt @@ -0,0 +1,84 @@ +/* + * Copyright 2024-2026 Embabel Pty Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.embabel.agent.api.client + +import java.io.ByteArrayInputStream +import java.security.KeyStore +import java.security.MessageDigest +import java.security.cert.CertificateException +import java.security.cert.CertificateFactory +import java.security.cert.X509Certificate +import java.util.Base64 +import java.util.HexFormat +import javax.net.ssl.SSLContext +import javax.net.ssl.TrustManagerFactory + +/** + * The certificate authorities ONE API's calls trust, in place of the JVM's own. + * + * An API inside an organisation is usually signed by an authority no public trust store carries: + * a Kubernetes cluster's own CA, a company's internal one. The choices otherwise are to add that + * authority to the JVM's trust store, which trusts it for every call the application makes, or + * to stop verifying, which trusts everybody. This trusts the given certificates for the one + * client built with them and nothing else: a call through that client is refused unless the + * server's certificate chains to one of them, and no other client is affected. + * + * The text is what an operator already has: + * - one or more PEM certificates (`-----BEGIN CERTIFICATE-----`), as a file holds them; + * - the same with its line breaks written as `\n`, as a single-line setting often carries it; + * - Base64 of either PEM or DER, which is what a kubeconfig's `certificate-authority-data` is. + */ +internal object TrustedCertificates { + + /** The certificates in [text]; refuses text that holds none. */ + fun parse(text: String): List { + val bytes = bytesOf(text) + val certificates = try { + CertificateFactory.getInstance("X.509").generateCertificates(ByteArrayInputStream(bytes)) + } catch (e: CertificateException) { + throw IllegalArgumentException("the trusted certificates could not be read: ${e.message}", e) + } + require(certificates.isNotEmpty()) { "the trusted certificates hold no certificate" } + return certificates.map { it as X509Certificate } + } + + /** An [SSLContext] that trusts [certificates] and no other authority. */ + fun sslContext(certificates: List): SSLContext { + val store = KeyStore.getInstance(KeyStore.getDefaultType()).apply { load(null, null) } + certificates.forEachIndexed { index, certificate -> store.setCertificateEntry("trusted-$index", certificate) } + val trust = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()).apply { init(store) } + return SSLContext.getInstance("TLS").apply { init(null, trust.trustManagers, null) } + } + + /** What tells two sets of certificates apart, whatever form each was written in. */ + fun fingerprint(certificates: List): String { + val digest = MessageDigest.getInstance("SHA-256") + certificates.map { it.encoded }.sortedBy { HexFormat.of().formatHex(it) }.forEach(digest::update) + return HexFormat.of().formatHex(digest.digest()) + } + + private fun bytesOf(text: String): ByteArray { + val unescaped = text.trim().replace("\\n", "\n") + if (PEM_HEADER in unescaped) return unescaped.toByteArray() + return try { + Base64.getMimeDecoder().decode(unescaped) + } catch (e: IllegalArgumentException) { + throw IllegalArgumentException("the trusted certificates are neither PEM nor Base64 of a certificate", e) + } + } + + private const val PEM_HEADER = "-----BEGIN CERTIFICATE-----" +} diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiClientProperties.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiClientProperties.kt index 9919ca1..698544f 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiClientProperties.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiClientProperties.kt @@ -28,9 +28,17 @@ import java.time.Duration * connect-timeout: 5s * read-timeout: 20s * ``` + * + * [trustedCertificates] is for an API signed by an authority the JVM does not trust, such as a + * Kubernetes cluster's own: one or more certificates as PEM, PEM with `\n` for its line breaks, or + * Base64 of PEM or DER (a kubeconfig's `certificate-authority-data`). The tools built with these + * properties trust those certificates IN PLACE OF the JVM's authorities, and nothing else does. + * It is set per API by the code that builds its tools rather than once in configuration, since + * it belongs to one API. */ @ConfigurationProperties(prefix = "embabel.api-client.openapi") -data class OpenApiClientProperties( +data class OpenApiClientProperties @JvmOverloads constructor( val connectTimeout: Duration = Duration.ofSeconds(5), val readTimeout: Duration = Duration.ofSeconds(20), + val trustedCertificates: String? = null, ) diff --git a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiLearner.kt b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiLearner.kt index 2d817ec..79cec01 100644 --- a/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiLearner.kt +++ b/embabel-api-client/src/main/kotlin/com/embabel/agent/api/client/openapi/OpenApiLearner.kt @@ -296,6 +296,7 @@ class OpenApiLearner( connectTimeout = clientProperties.connectTimeout, readTimeout = clientProperties.readTimeout, credentialQueryParameters = queryCredentialNames(openApi, credentials), + trustedCertificates = clientProperties.trustedCertificates, ) val builder = RestClient.builder().requestFactory(requestFactory) applyCredentials(builder, openApi, credentials) diff --git a/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/TrustedCertificatesTest.kt b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/TrustedCertificatesTest.kt new file mode 100644 index 0000000..9bc034e --- /dev/null +++ b/embabel-api-client/src/test/kotlin/com/embabel/agent/api/client/TrustedCertificatesTest.kt @@ -0,0 +1,164 @@ +/* + * Copyright 2024-2026 Embabel Pty Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.embabel.agent.api.client + +import com.embabel.agent.api.client.openapi.OpenApiClientProperties +import com.embabel.agent.api.tool.Tool +import com.embabel.agent.api.tool.progressive.ProgressiveTool +import com.sun.net.httpserver.HttpsConfigurator +import com.sun.net.httpserver.HttpsServer +import org.junit.jupiter.api.AfterEach +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Assertions.assertNotSame +import org.junit.jupiter.api.Assertions.assertSame +import org.junit.jupiter.api.Assertions.assertTrue +import org.junit.jupiter.api.BeforeEach +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.assertThrows +import org.junit.jupiter.api.io.TempDir +import org.springframework.web.client.ResourceAccessException +import org.springframework.web.client.RestClient +import java.net.InetSocketAddress +import java.net.URI +import java.nio.file.Files +import java.nio.file.Path +import java.security.KeyStore +import java.time.Duration +import java.util.Base64 +import java.util.concurrent.TimeUnit +import javax.net.ssl.KeyManagerFactory +import javax.net.ssl.SSLContext +import javax.net.ssl.SSLHandshakeException + +/** + * An API signed by an authority the JVM does not trust, which is what a Kubernetes cluster's API + * is, is reached by a client given that authority's certificate, and by no other. The server here + * holds a certificate made for the test by the JDK's own `keytool`, so no public authority vouches + * for it and nothing is checked in. + */ +class TrustedCertificatesTest { + + @TempDir + lateinit var dir: Path + + private lateinit var server: HttpsServer + private lateinit var pem: String + + @BeforeEach + fun start() { + val store = dir.resolve("server.p12") + keytool( + "-genkeypair", "-alias", "api", "-keyalg", "RSA", "-keysize", "2048", "-validity", "2", + "-dname", "CN=localhost", "-ext", "SAN=ip:127.0.0.1,dns:localhost", + "-keystore", store.toString(), "-storetype", "PKCS12", "-storepass", PASSWORD, "-keypass", PASSWORD, + ) + pem = keytool("-exportcert", "-alias", "api", "-rfc", "-keystore", store.toString(), "-storepass", PASSWORD) + val keys = KeyStore.getInstance("PKCS12").apply { Files.newInputStream(store).use { load(it, PASSWORD.toCharArray()) } } + val managers = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()).apply { init(keys, PASSWORD.toCharArray()) } + val context = SSLContext.getInstance("TLS").apply { init(managers.keyManagers, null, null) } + server = HttpsServer.create(InetSocketAddress("127.0.0.1", 0), 0).apply { + httpsConfigurator = HttpsConfigurator(context) + createContext("/pods") { exchange -> + val body = """{"items":[]}""".toByteArray() + exchange.sendResponseHeaders(200, body.size.toLong()) + exchange.responseBody.use { it.write(body) } + } + start() + } + } + + @AfterEach + fun stop() = server.stop(0) + + private fun get(trustedCertificates: String?): String? = + RestClient.builder() + .requestFactory(CredentialSafeRedirects.overJdkClient(TIMEOUT, TIMEOUT, emptySet(), trustedCertificates)) + .build() + .get().uri(URI("https://127.0.0.1:${server.address.port}/pods")).retrieve().body(String::class.java) + + @Test + fun `a client given the API's authority reaches it`() { + assertEquals("""{"items":[]}""", get(pem)) + } + + @Test + fun `a client not given it is refused, as the JVM's own trust refuses it`() { + val refused = assertThrows { get(null) } + assertTrue(generateSequence(refused) { it.cause }.any { it is SSLHandshakeException }, "refused for the certificate: $refused") + } + + @Test + fun `the authority is read as a setting carries it, on one line or as a kubeconfig's Base64`() { + assertEquals("""{"items":[]}""", get(pem.trim().replace("\n", "\\n"))) + assertEquals("""{"items":[]}""", get(Base64.getEncoder().encodeToString(pem.toByteArray()))) + val der = TrustedCertificates.parse(pem).single().encoded + assertEquals("""{"items":[]}""", get(Base64.getEncoder().encodeToString(der))) + } + + @Test + fun `text that holds no certificate is refused rather than trusted or ignored`() { + assertThrows { get("not a certificate") } + assertThrows { get("-----BEGIN CERTIFICATE-----\nAAAA\n-----END CERTIFICATE-----") } + } + + @Test + fun `one client is shared per authority, and it is not the client that trusts the JVM's`() { + val trusting = SharedHttpClients.redirectRefusing(TIMEOUT, pem) + assertSame(trusting, SharedHttpClients.redirectRefusing(TIMEOUT, Base64.getEncoder().encodeToString(pem.toByteArray()))) + assertNotSame(trusting, SharedHttpClients.redirectRefusing(TIMEOUT)) + assertSame(SharedHttpClients.redirectRefusing(TIMEOUT), SharedHttpClients.redirectRefusing(TIMEOUT, " ")) + } + + @Test + fun `the properties an API's tools are built with carry its authority`() { + val properties = OpenApiClientProperties(trustedCertificates = pem) + assertEquals(pem, properties.trustedCertificates) + assertEquals(null, OpenApiClientProperties().trustedCertificates) + } + + @Test + fun `tools rebuilt from a kept spec trust the authority too`() { + val spec = LearnedApiSpec.OpenApi( + source = "inline", + rawSpec = """{"openapi":"3.0.3","info":{"title":"cluster","version":"1"}, + "servers":[{"url":"https://127.0.0.1:${server.address.port}"}], + "paths":{"/pods":{"get":{"operationId":"listPods","responses":{"200":{"description":"ok"}}}}}}""", + ) + val trusting = leafTools(spec.toFactory(clientProperties = OpenApiClientProperties(trustedCertificates = pem))(ApiCredentials.None)).single() + assertTrue(trusting.call("").toString().contains("items"), "the call reached the server") + val unaware = leafTools(spec.toFactory()(ApiCredentials.None)).single() + assertTrue(!unaware.call("").toString().contains("\"items\""), "the default client is refused") + } + + private fun leafTools(tool: Tool): List = when (tool) { + is ProgressiveTool -> tool.innerTools(org.mockito.Mockito.mock(com.embabel.agent.core.AgentProcess::class.java)).flatMap(::leafTools) + else -> listOf(tool) + } + + /* The JDK's keytool, so the test needs no certificate library and keeps no key. Returns what it printed. */ + private fun keytool(vararg arguments: String): String { + val process = ProcessBuilder(listOf(Path.of(System.getProperty("java.home"), "bin", "keytool").toString()) + arguments) + .redirectErrorStream(true).start() + val printed = process.inputStream.bufferedReader().readText() + check(process.waitFor(60, TimeUnit.SECONDS) && process.exitValue() == 0) { "keytool failed: $printed" } + return printed + } + + private companion object { + const val PASSWORD = "changeit" + val TIMEOUT: Duration = Duration.ofSeconds(7) + } +}