diff --git a/CHANGELOG.md b/CHANGELOG.md index 3854f7c2..ad58a1dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ * Add `X509Bundle.marshal()` and `JwtBundle.marshal()` to serialize bundles as PEM certificates and as a JWKS document, the formats read by `parse` * Publish a `java-spiffe-bom` Bill of Materials to align the versions of the java-spiffe modules. +* Add `X509Svid.marshalCertificates()` and `X509Svid.marshalPrivateKey()` to serialize an X.509-SVID as PEM certificates and a PEM PKCS#8 private key, the formats read by `parse` and `load`, and `marshalRawCertificates()` and `marshalRawPrivateKey()` for the ASN.1 DER formats read by `parseRaw` (#515) ### Fixed diff --git a/java-spiffe-core/README.md b/java-spiffe-core/README.md index 8e88355c..db866ab7 100644 --- a/java-spiffe-core/README.md +++ b/java-spiffe-core/README.md @@ -107,6 +107,25 @@ using a System property: The `timeout` duration is expressed in `ISO-8601` format. +## Marshal X.509-SVIDs + +An `X509Svid` can be marshaled into PEM-encoded certificates and a PEM-encoded PKCS#8 private key, the formats that +`X509Svid.load` and `X509Svid.parse` read. This lets a workload hand its SVID to a process or tool that takes +certificate and key files: + +``` + X509Svid svid = x509Source.getX509Svid(); + Files.write(Paths.get("/tmp/svid.pem"), svid.marshalCertificates()); + Path keyPath = Files.createFile(Paths.get("/tmp/svid.key"), + PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rw-------"))); + Files.write(keyPath, svid.marshalPrivateKey()); + X509Svid loadedSvid = X509Svid.load(Paths.get("/tmp/svid.pem"), keyPath); +``` + +The certificate chain is written leaf first. The private key is not encrypted, so store it where only the workload +can read it. The SVID hint is not marshaled; pass it to `X509Svid.parse` to keep it. `marshalRawCertificates` and `marshalRawPrivateKey` return the same material as ASN.1 DER, which +`X509Svid.parseRaw` reads. + ## Marshal bundles An `X509Bundle` can be marshaled into PEM-encoded certificates, and a `JwtBundle` into a standard RFC 7517 JWKS diff --git a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java index c9aa95b2..a16f141c 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java +++ b/java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java @@ -8,7 +8,6 @@ import java.io.ByteArrayOutputStream; import java.io.IOException; -import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.security.cert.CertificateEncodingException; @@ -22,12 +21,6 @@ */ public final class X509Bundle implements BundleSource { - private static final byte[] PEM_CERTIFICATE_HEADER = "-----BEGIN CERTIFICATE-----\n".getBytes(StandardCharsets.US_ASCII); - private static final byte[] PEM_CERTIFICATE_FOOTER = "\n-----END CERTIFICATE-----\n".getBytes(StandardCharsets.US_ASCII); - // PEM (RFC 7468) wraps the base64 text at 64 characters per line - private static final Base64.Encoder PEM_ENCODER = - Base64.getMimeEncoder(64, "\n".getBytes(StandardCharsets.US_ASCII)); - private final TrustDomain trustDomain; private final Set x509Authorities; @@ -179,10 +172,8 @@ public byte[] marshal() throws X509BundleException { } catch (CertificateEncodingException e) { throw new X509BundleException("X.509 authority could not be encoded", e); } - pem.write(PEM_CERTIFICATE_HEADER, 0, PEM_CERTIFICATE_HEADER.length); - byte[] base64 = PEM_ENCODER.encode(der); - pem.write(base64, 0, base64.length); - pem.write(PEM_CERTIFICATE_FOOTER, 0, PEM_CERTIFICATE_FOOTER.length); + byte[] pemBlock = CertificateUtils.toPemBlock(CertificateUtils.PEM_CERTIFICATE_LABEL, der); + pem.write(pemBlock, 0, pemBlock.length); } return pem.toByteArray(); } diff --git a/java-spiffe-core/src/main/java/io/spiffe/internal/CertificateUtils.java b/java-spiffe-core/src/main/java/io/spiffe/internal/CertificateUtils.java index 54c8e1f6..c8a2b25e 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/internal/CertificateUtils.java +++ b/java-spiffe-core/src/main/java/io/spiffe/internal/CertificateUtils.java @@ -5,6 +5,7 @@ import io.spiffe.spiffeid.TrustDomain; import java.io.ByteArrayInputStream; +import java.nio.charset.StandardCharsets; import java.security.InvalidAlgorithmParameterException; import java.security.InvalidKeyException; import java.security.KeyFactory; @@ -31,6 +32,20 @@ */ public class CertificateUtils { + /** + * PEM label of an X.509 certificate (RFC 7468, section 5). + */ + public static final String PEM_CERTIFICATE_LABEL = "CERTIFICATE"; + + /** + * PEM label of an unencrypted PKCS#8 private key (RFC 7468, section 10). + */ + public static final String PEM_PRIVATE_KEY_LABEL = "PRIVATE KEY"; + + // PEM (RFC 7468) wraps the base64 text at 64 characters per line + private static final Base64.Encoder PEM_ENCODER = + Base64.getMimeEncoder(64, "\n".getBytes(StandardCharsets.US_ASCII)); + private static final String SPIFFE_PREFIX = "spiffe://"; private static final int SAN_TYPE_INDEX = 0; private static final int SAN_VALUE_INDEX = 1; @@ -66,6 +81,21 @@ public static List generateCertificates(final byte[] input) thr .collect(Collectors.toList()); } + /** + * Encodes DER bytes as a PEM block (RFC 7468) with the given label. The base64 text is wrapped + * at 64 characters per line and the block ends with a line break. + * + * @param label the label of the PEM block, for example {@link #PEM_CERTIFICATE_LABEL} + * @param der the DER bytes to encode + * @return the PEM block as US-ASCII bytes + */ + public static byte[] toPemBlock(final String label, final byte[] der) { + String pem = "-----BEGIN " + label + "-----\n" + + PEM_ENCODER.encodeToString(der) + + "\n-----END " + label + "-----\n"; + return pem.getBytes(StandardCharsets.US_ASCII); + } + /** * Generates a private key from an array of bytes. * diff --git a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java index 91e4e5c1..d13fc68d 100644 --- a/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java +++ b/java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java @@ -6,12 +6,14 @@ import io.spiffe.internal.KeyFileFormat; import io.spiffe.spiffeid.SpiffeId; +import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.file.Files; import java.nio.file.Path; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.PrivateKey; +import java.security.cert.CertificateEncodingException; import java.security.cert.CertificateException; import java.security.cert.CertificateParsingException; import java.security.cert.X509Certificate; @@ -27,6 +29,8 @@ */ public class X509Svid { + private static final String PKCS8_FORMAT = "PKCS#8"; + SpiffeId spiffeId; /** @@ -208,6 +212,96 @@ public X509Certificate[] getChainArray() { return chain.toArray(new X509Certificate[0]); } + /** + * Marshals the certificate chain of the X.509-SVID into PEM-encoded certificate blocks, one block + * for each certificate, with the leaf certificate first. + *

+ * Together with {@link #marshalPrivateKey()}, the result can be parsed back into an X.509-SVID with + * {@link #parse(byte[], byte[])} or {@link #load(Path, Path)}. The hint is not part of the marshaled + * material: pass it to {@link #parse(byte[], byte[], String)} to keep it. + * + * @return an array of bytes with the certificate chain encoded as PEM certificates + * @throws X509SvidException if a certificate of the chain cannot be encoded + */ + public byte[] marshalCertificates() throws X509SvidException { + ByteArrayOutputStream pem = new ByteArrayOutputStream(); + for (X509Certificate certificate : chain) { + byte[] der = encodeCertificate(certificate); + byte[] pemBlock = CertificateUtils.toPemBlock(CertificateUtils.PEM_CERTIFICATE_LABEL, der); + pem.write(pemBlock, 0, pemBlock.length); + } + return pem.toByteArray(); + } + + /** + * Marshals the private key of the X.509-SVID into a PEM-encoded PKCS#8 private key block + * ({@code PRIVATE KEY}). + *

+ * Together with {@link #marshalCertificates()}, the result can be parsed back into an X.509-SVID with + * {@link #parse(byte[], byte[])} or {@link #load(Path, Path)}. + *

+ * The result contains the unencrypted private key: protect it accordingly, for example by writing it + * to a file that only the workload can read. + * + * @return an array of bytes with the private key encoded as a PEM PKCS#8 private key + * @throws X509SvidException if the private key cannot be encoded as PKCS#8 + */ + public byte[] marshalPrivateKey() throws X509SvidException { + return CertificateUtils.toPemBlock(CertificateUtils.PEM_PRIVATE_KEY_LABEL, encodePrivateKey()); + } + + /** + * Marshals the certificate chain of the X.509-SVID into ASN.1 DER-encoded certificates, + * concatenated with no intermediate padding, with the leaf certificate first. + *

+ * Together with {@link #marshalRawPrivateKey()}, the result can be parsed back into an X.509-SVID with + * {@link #parseRaw(byte[], byte[])}. The hint is not part of the marshaled material: pass it to + * {@link #parseRaw(byte[], byte[], String)} to keep it. + * + * @return an array of bytes with the certificate chain encoded as concatenated ASN.1 DER certificates + * @throws X509SvidException if a certificate of the chain cannot be encoded + */ + public byte[] marshalRawCertificates() throws X509SvidException { + ByteArrayOutputStream der = new ByteArrayOutputStream(); + for (X509Certificate certificate : chain) { + byte[] encoded = encodeCertificate(certificate); + der.write(encoded, 0, encoded.length); + } + return der.toByteArray(); + } + + /** + * Marshals the private key of the X.509-SVID into a PKCS#8 ASN.1 DER-encoded private key. + *

+ * Together with {@link #marshalRawCertificates()}, the result can be parsed back into an X.509-SVID with + * {@link #parseRaw(byte[], byte[])}. + *

+ * The result contains the unencrypted private key: protect it accordingly, for example by writing it + * to a file that only the workload can read. + * + * @return an array of bytes with the private key encoded as a PKCS#8 ASN.1 DER private key + * @throws X509SvidException if the private key cannot be encoded as PKCS#8 + */ + public byte[] marshalRawPrivateKey() throws X509SvidException { + return encodePrivateKey(); + } + + private static byte[] encodeCertificate(final X509Certificate certificate) throws X509SvidException { + try { + return certificate.getEncoded(); + } catch (CertificateEncodingException e) { + throw new X509SvidException("Certificate could not be encoded", e); + } + } + + private byte[] encodePrivateKey() throws X509SvidException { + final byte[] encoded = PKCS8_FORMAT.equals(privateKey.getFormat()) ? privateKey.getEncoded() : null; + if (encoded == null) { + throw new X509SvidException("Private key could not be encoded as PKCS#8"); + } + return encoded; + } + private static X509Svid createX509Svid(final byte[] certsBytes, final byte[] privateKeyBytes, final KeyFileFormat keyFileFormat, diff --git a/java-spiffe-core/src/test/java/io/spiffe/internal/CertificateUtilsTest.java b/java-spiffe-core/src/test/java/io/spiffe/internal/CertificateUtilsTest.java index bf3cbe9e..a73ec1a9 100644 --- a/java-spiffe-core/src/test/java/io/spiffe/internal/CertificateUtilsTest.java +++ b/java-spiffe-core/src/test/java/io/spiffe/internal/CertificateUtilsTest.java @@ -9,6 +9,7 @@ import java.io.IOException; import java.net.URISyntaxException; +import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; @@ -22,6 +23,7 @@ import java.security.cert.X509Certificate; import java.security.spec.InvalidKeySpecException; import java.util.Arrays; +import java.util.Base64; import java.util.Collection; import java.util.Collections; import java.util.List; @@ -256,6 +258,23 @@ void keyUsageChecks_noKeyUsageExtension() throws Exception { assertFalse(CertificateUtils.hasKeyUsageCRLSign(certificate)); } + @Test + void toPemBlock_wrapsBase64At64CharactersBetweenLabeledBoundaries() { + byte[] der = new byte[60]; + for (int i = 0; i < der.length; i++) { + der[i] = (byte) i; + } + String base64 = Base64.getEncoder().encodeToString(der); + + String pem = new String(CertificateUtils.toPemBlock("TEST LABEL", der), StandardCharsets.US_ASCII); + + String expected = "-----BEGIN TEST LABEL-----\n" + + base64.substring(0, 64) + "\n" + + base64.substring(64) + "\n" + + "-----END TEST LABEL-----\n"; + assertEquals(expected, pem); + } + private static class CertificateWithSubjectAlternativeNames extends DummyX509Certificate { private final Collection> subjectAlternativeNames; diff --git a/java-spiffe-core/src/test/java/io/spiffe/svid/x509svid/X509SvidTest.java b/java-spiffe-core/src/test/java/io/spiffe/svid/x509svid/X509SvidTest.java index 2dbf01ef..ab2e1ec0 100644 --- a/java-spiffe-core/src/test/java/io/spiffe/svid/x509svid/X509SvidTest.java +++ b/java-spiffe-core/src/test/java/io/spiffe/svid/x509svid/X509SvidTest.java @@ -2,33 +2,45 @@ import io.spiffe.exception.InvalidSpiffeIdException; import io.spiffe.exception.X509SvidException; +import io.spiffe.internal.DummyX509Certificate; import io.spiffe.spiffeid.SpiffeId; import io.spiffe.spiffeid.TrustDomain; import io.spiffe.utils.CertAndKeyPair; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.Arguments; import org.junit.jupiter.params.provider.MethodSource; import org.junit.platform.commons.util.StringUtils; +import java.io.ByteArrayInputStream; import java.io.IOException; import java.net.URISyntaxException; +import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; +import java.security.PrivateKey; +import java.security.cert.CertificateEncodingException; import java.security.cert.CertificateException; +import java.security.cert.CertificateFactory; import java.security.cert.X509Certificate; import java.util.Arrays; +import java.util.Base64; +import java.util.Collections; import java.util.stream.Stream; import static io.spiffe.utils.TestUtils.toUri; import static io.spiffe.utils.X509CertificateTestUtils.createCertificate; import static io.spiffe.utils.X509CertificateTestUtils.createCertificateWithUriSans; import static io.spiffe.utils.X509CertificateTestUtils.createRootCA; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.fail; class X509SvidTest { @@ -381,6 +393,159 @@ void parseRaw_leafWithMultipleUriSans_isRejected() throws Exception { assertEquals("Leaf certificate must contain exactly one URI SAN", exception.getMessage()); } + static Stream provideMarshalScenarios() { + return Stream.of( + Arguments.of(certSingle, keyRSA), + Arguments.of(certMultiple, keyECDSA) + ); + } + + @ParameterizedTest + @MethodSource("provideMarshalScenarios") + void testMarshal_roundTripsThroughParse(String certsPath, String keyPath) throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certsPath)), Paths.get(toUri(keyPath))); + + X509Svid parsed = X509Svid.parse(x509Svid.marshalCertificates(), x509Svid.marshalPrivateKey()); + + assertSameSvid(x509Svid, parsed); + } + + @ParameterizedTest + @MethodSource("provideMarshalScenarios") + void testMarshal_roundTripsThroughLoad(String certsPath, String keyPath, @TempDir Path tempDir) throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certsPath)), Paths.get(toUri(keyPath))); + Path marshaledCertsPath = Files.write(tempDir.resolve("svid.pem"), x509Svid.marshalCertificates()); + Path marshaledKeyPath = Files.write(tempDir.resolve("svid.key"), x509Svid.marshalPrivateKey()); + + X509Svid loaded = X509Svid.load(marshaledCertsPath, marshaledKeyPath); + + assertSameSvid(x509Svid, loaded); + } + + @ParameterizedTest + @MethodSource("provideMarshalScenarios") + void testMarshalRaw_roundTripsThroughParseRaw(String certsPath, String keyPath) throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certsPath)), Paths.get(toUri(keyPath))); + + X509Svid parsed = X509Svid.parseRaw(x509Svid.marshalRawCertificates(), x509Svid.marshalRawPrivateKey()); + + assertSameSvid(x509Svid, parsed); + } + + @Test + void testMarshalRaw_returnsDerEncoding() throws Exception { + byte[] certBytes = Files.readAllBytes(Paths.get(toUri(certDER))); + byte[] keyBytes = Files.readAllBytes(Paths.get(toUri(keyDER))); + X509Svid x509Svid = X509Svid.parseRaw(certBytes, keyBytes); + + assertArrayEquals(certBytes, x509Svid.marshalRawCertificates()); + assertArrayEquals(x509Svid.getPrivateKey().getEncoded(), x509Svid.marshalRawPrivateKey()); + } + + @Test + void testMarshalCertificates_writesOnePemBlockPerCertificateLeafFirst() throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certMultiple)), Paths.get(toUri(keyECDSA))); + + String pem = new String(x509Svid.marshalCertificates(), StandardCharsets.US_ASCII); + + String[] blocks = pem.split("(?<=-----END CERTIFICATE-----\n)"); + assertEquals(2, blocks.length); + for (int i = 0; i < blocks.length; i++) { + assertTrue(blocks[i].startsWith("-----BEGIN CERTIFICATE-----\n")); + assertTrue(blocks[i].endsWith("\n-----END CERTIFICATE-----\n")); + X509Certificate certificate = (X509Certificate) CertificateFactory.getInstance("X.509") + .generateCertificate(new ByteArrayInputStream(blocks[i].getBytes(StandardCharsets.US_ASCII))); + assertEquals(x509Svid.getChain().get(i), certificate); + } + assertPemLinesAreWrapped(pem); + } + + @Test + void testMarshalPrivateKey_writesPkcs8PemBlock() throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certSingle)), Paths.get(toUri(keyRSA))); + + String pem = new String(x509Svid.marshalPrivateKey(), StandardCharsets.US_ASCII); + + assertTrue(pem.startsWith("-----BEGIN PRIVATE KEY-----\n")); + assertTrue(pem.endsWith("\n-----END PRIVATE KEY-----\n")); + String base64 = pem + .replace("-----BEGIN PRIVATE KEY-----", "") + .replace("-----END PRIVATE KEY-----", "") + .replace("\n", ""); + assertArrayEquals(x509Svid.getPrivateKey().getEncoded(), Base64.getDecoder().decode(base64)); + assertPemLinesAreWrapped(pem); + } + + @Test + void testMarshal_certificateCannotBeEncoded_throwsX509SvidException() throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certSingle)), Paths.get(toUri(keyRSA))); + CertificateEncodingException encodingException = new CertificateEncodingException("encoding error"); + x509Svid.chain = Collections.singletonList(new DummyX509Certificate() { + @Override + public byte[] getEncoded() throws CertificateEncodingException { + throw encodingException; + } + }); + + X509SvidException pemException = assertThrows(X509SvidException.class, x509Svid::marshalCertificates); + assertEquals("Certificate could not be encoded", pemException.getMessage()); + assertSame(encodingException, pemException.getCause()); + + X509SvidException derException = assertThrows(X509SvidException.class, x509Svid::marshalRawCertificates); + assertEquals("Certificate could not be encoded", derException.getMessage()); + assertSame(encodingException, derException.getCause()); + } + + static Stream provideNonPkcs8PrivateKeys() { + return Stream.of( + Arguments.of("RAW", new byte[]{1, 2, 3}), + Arguments.of(null, null), + Arguments.of("PKCS#8", null) + ); + } + + @ParameterizedTest + @MethodSource("provideNonPkcs8PrivateKeys") + void testMarshal_privateKeyCannotBeEncodedAsPkcs8_throwsX509SvidException(String format, byte[] encoded) + throws Exception { + X509Svid x509Svid = X509Svid.load(Paths.get(toUri(certSingle)), Paths.get(toUri(keyRSA))); + x509Svid.privateKey = new PrivateKey() { + @Override + public String getAlgorithm() { + return "RSA"; + } + + @Override + public String getFormat() { + return format; + } + + @Override + public byte[] getEncoded() { + return encoded; + } + }; + + X509SvidException pemException = assertThrows(X509SvidException.class, x509Svid::marshalPrivateKey); + assertEquals("Private key could not be encoded as PKCS#8", pemException.getMessage()); + + X509SvidException derException = assertThrows(X509SvidException.class, x509Svid::marshalRawPrivateKey); + assertEquals("Private key could not be encoded as PKCS#8", derException.getMessage()); + } + + private static void assertSameSvid(X509Svid expected, X509Svid actual) { + assertEquals(expected.getSpiffeId(), actual.getSpiffeId()); + assertEquals(expected.getChain(), actual.getChain()); + assertEquals(expected.getPrivateKey().getAlgorithm(), actual.getPrivateKey().getAlgorithm()); + assertArrayEquals(expected.getPrivateKey().getEncoded(), actual.getPrivateKey().getEncoded()); + } + + private static void assertPemLinesAreWrapped(String pem) { + for (String line : pem.split("\n")) { + assertTrue(line.length() <= 64, "PEM line longer than 64 characters: " + line); + } + } + @ParameterizedTest @MethodSource("provideX509SvidScenarios") void parseX509Svid(TestCase testCase) {