Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
19 changes: 19 additions & 0 deletions java-spiffe-core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -22,12 +21,6 @@
*/
public final class X509Bundle implements BundleSource<X509Bundle> {

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<X509Certificate> x509Authorities;

Expand Down Expand Up @@ -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();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -66,6 +81,21 @@ public static List<X509Certificate> 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.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -27,6 +29,8 @@
*/
public class X509Svid {

private static final String PKCS8_FORMAT = "PKCS#8";

SpiffeId spiffeId;

/**
Expand Down Expand Up @@ -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.
* <p>
* 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}).
* <p>
* 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)}.
* <p>
* 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.
* <p>
* 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.
* <p>
* Together with {@link #marshalRawCertificates()}, the result can be parsed back into an X.509-SVID with
* {@link #parseRaw(byte[], byte[])}.
* <p>
* 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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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<List<?>> subjectAlternativeNames;

Expand Down
Loading
Loading