According to RFC 7296, for an initial IKE SA negotiation, no SPI is included in SA * Proposal. IKE library, as a client, only supports requesting this initial negotiation. * * @param saProposals the array of all SA Proposals. */ public static IkeSaPayload createInitialIkeSaPayload(IkeSaProposal[] saProposals) throws IOException { return new IkeSaPayload( false /* isResp */, SPI_LEN_NOT_INCLUDED, saProposals, null /* ikeSpiGenerator unused */, null /* localAddress unused */); } /** * Construct an instance of IkeSaPayload for building an outbound request for Rekey IKE. * * @param saProposals the array of all IKE SA Proposals. * @param ikeSpiGenerator the IKE SPI generator. * @param localAddress the local address assigned on-device. */ public static IkeSaPayload createRekeyIkeSaRequestPayload( IkeSaProposal[] saProposals, IkeSpiGenerator ikeSpiGenerator, InetAddress localAddress) throws IOException { return new IkeSaPayload( false /* isResp */, SPI_LEN_IKE, saProposals, ikeSpiGenerator, localAddress); } /** * Construct an instance of IkeSaPayload for building an outbound response for Rekey IKE. * * @param respProposalNumber the selected proposal's number. * @param saProposal the expected selected IKE SA Proposal. * @param ikeSpiGenerator the IKE SPI generator. * @param localAddress the local address assigned on-device. */ public static IkeSaPayload createRekeyIkeSaResponsePayload( byte respProposalNumber, IkeSaProposal saProposal, IkeSpiGenerator ikeSpiGenerator, InetAddress localAddress) throws IOException { return new IkeSaPayload( true /* isResp */, SPI_LEN_IKE, respProposalNumber, saProposal, ikeSpiGenerator, localAddress); } /** * Construct an instance of IkeSaPayload for building an outbound request for Child SA * negotiation. * * @param saProposals the array of all Child SA Proposals. * @param ipSecSpiGenerator the IPsec SPI generator. * @param localAddress the local address assigned on-device. * @throws ResourceUnavailableException if too many SPIs are currently allocated for this user. */ public static IkeSaPayload createChildSaRequestPayload( ChildSaProposal[] saProposals, IpSecSpiGenerator ipSecSpiGenerator, InetAddress localAddress) throws SpiUnavailableException, ResourceUnavailableException { return new IkeSaPayload(saProposals, ipSecSpiGenerator, localAddress); } /** * Construct an instance of IkeSaPayload for building an outbound response for Child SA * negotiation. * * @param respProposalNumber the selected proposal's number. * @param saProposal the expected selected Child SA Proposal. * @param ipSecSpiGenerator the IPsec SPI generator. * @param localAddress the local address assigned on-device. */ public static IkeSaPayload createChildSaResponsePayload( byte respProposalNumber, ChildSaProposal saProposal, IpSecSpiGenerator ipSecSpiGenerator, InetAddress localAddress) throws SpiUnavailableException, ResourceUnavailableException { return new IkeSaPayload(respProposalNumber, saProposal, ipSecSpiGenerator, localAddress); } /** * Finds the proposal in this (request) payload that matches the response proposal. * * @param respProposal the Proposal to match against. * @return the byte-value proposal number of the selected proposal * @throws NoValidProposalChosenException if no matching proposal was found. */ public byte getNegotiatedProposalNumber(SaProposal respProposal) throws NoValidProposalChosenException { for (int i = 0; i < proposalList.size(); i++) { Proposal reqProposal = proposalList.get(i); if (respProposal.isNegotiatedFrom(reqProposal.getSaProposal()) && reqProposal.getSaProposal().getProtocolId() == respProposal.getProtocolId()) { return reqProposal.number; } } throw new NoValidProposalChosenException("No remotely proposed protocol acceptable"); } /** * Finds or builds the negotiated Child proposal when there is a key exchange. * *
This method will be used in Remote Rekey Child. For better interoperability, IKE library
* allows the server to set up new Child SA with a different DH group if (1) caller has
* configured that DH group in the Child SA Proposal, or (2) that DH group is the DH group
* negotiated as part of IKE Session.
*
* @param currentProposal the current negotiated Child SA Proposal
* @param callerConfiguredProposals all caller configured Child SA Proposals
* @param reqKePayloadDh the DH group in the request KE payload
* @param ikeDh the DH group negotiated as part of IKE Session
* @return the negotiated Child SA Proposal
* @throws NoValidProposalChosenException when there is no acceptable proposal in the SA payload
* @throws InvalidKeException when the request KE payload has a mismatched DH group
*/
public ChildSaProposal getNegotiatedChildProposalWithDh(
ChildSaProposal currentProposal,
List Caller is able to extract the negotiated IKE SA Proposal from the response Proposal and
* the IKE SPI pair generated by both sides.
*
* In a locally-initiated case all IKE SA proposals (from users in initial creation or from
* previously negotiated proposal in rekey creation) in the locally generated reqSaPayload have
* been validated during building and are unmodified. All Transform combinations in these SA
* proposals are valid for IKE SA negotiation. It means each IKE SA request proposal MUST have
* Encryption algorithms, DH group configurations and PRFs. Integrity algorithms can only be
* omitted when AEAD is used.
*
* In a remotely-initiated case the locally generated respSaPayload has exactly one SA
* proposal. It is validated during building and are unmodified. This proposal has a valid
* Transform combination for an IKE SA and has at most one value for each Transform type.
*
* The response IKE SA proposal is validated against one of the request IKE SA proposals. It
* is guaranteed that for each Transform type that the request proposal has provided options,
* the response proposal has exact one Transform value.
*
* @param reqSaPayload the request payload.
* @param respSaPayload the response payload.
* @param remoteAddress the address of the remote IKE peer.
* @return the Pair of selected IkeProposal in request and the IkeProposal in response.
* @throws NoValidProposalChosenException if the response SA Payload cannot be negotiated from
* the request SA Payload.
*/
public static Pair Caller is able to extract the negotiated SA Proposal from the response Proposal and the
* IPsec SPI pair generated by both sides.
*
* In a locally-initiated case all Child SA proposals (from users in initial creation or from
* previously negotiated proposal in rekey creation) in the locally generated reqSaPayload have
* been validated during building and are unmodified. All Transform combinations in these SA
* proposals are valid for Child SA negotiation. It means each request SA proposal MUST have
* Encryption algorithms and ESN configurations.
*
* In a remotely-initiated case the locally generated respSapayload has exactly one SA
* proposal. It is validated during building and are unmodified. This proposal has a valid
* Transform combination for an Child SA and has at most one value for each Transform type.
*
* The response Child SA proposal is validated against one of the request SA proposals. It is
* guaranteed that for each Transform type that the request proposal has provided options, the
* response proposal has exact one Transform value.
*
* @param reqSaPayload the request payload.
* @param respSaPayload the response payload.
* @param ipSecSpiGenerator the SPI generator to allocate SPI resource for the Proposal in this
* inbound SA Payload.
* @param remoteAddress the address of the remote IKE peer.
* @return the Pair of selected ChildProposal in the locally generated request and the
* ChildProposal in this response.
* @throws NoValidProposalChosenException if the response SA Payload cannot be negotiated from
* the request SA Payload.
* @throws ResourceUnavailableException if too many SPIs are currently allocated for this user.
* @throws SpiUnavailableException if the remotely generated SPI is in use.
*/
public static Pair This method is usually called when an IKE library fails to receive a Create IKE/Child
* response before it is terminated. It is also safe to call after the Create IKE/Child exchange
* has succeeded because the newly created IkeSaRecord or ChildSaRecord (IpSecTransform pair)
* will hold the SPI resource.
*/
public void releaseSpiResources() {
for (Proposal proposal : proposalList) {
proposal.releaseSpiResourceIfExists();
}
}
/**
* This class represents the common information of an IKE Proposal and a Child Proposal.
*
* Proposal represents a set contains cryptographic algorithms and key generating materials.
* It contains multiple {@link Transform}.
*
* @see RFC 7296, Internet Key
* Exchange Protocol Version 2 (IKEv2)
* Proposals with an unrecognized Protocol ID, containing an unrecognized Transform Type
* or lacking a necessary Transform Type shall be ignored when processing a received SA
* Payload.
*/
public abstract static class Proposal {
private static final byte LAST_PROPOSAL = 0;
private static final byte NOT_LAST_PROPOSAL = 2;
private static final int PROPOSAL_RESERVED_FIELD_LEN = 1;
private static final int PROPOSAL_HEADER_LEN = 8;
private static TransformDecoder sTransformDecoder = new TransformDecoderImpl();
public final byte number;
/** All supported protocol will fall into {@link ProtocolId} */
public final int protocolId;
public final byte spiSize;
public final long spi;
public final boolean hasUnrecognizedTransform;
@VisibleForTesting
Proposal(
byte number,
int protocolId,
byte spiSize,
long spi,
boolean hasUnrecognizedTransform) {
this.number = number;
this.protocolId = protocolId;
this.spiSize = spiSize;
this.spi = spi;
this.hasUnrecognizedTransform = hasUnrecognizedTransform;
}
@VisibleForTesting
static Proposal readFrom(ByteBuffer inputBuffer) throws IkeProtocolException {
byte isLast = inputBuffer.get();
if (isLast != LAST_PROPOSAL && isLast != NOT_LAST_PROPOSAL) {
throw new InvalidSyntaxException(
"Invalid value of Last Proposal Substructure: " + isLast);
}
// Skip RESERVED byte
inputBuffer.get(new byte[PROPOSAL_RESERVED_FIELD_LEN]);
int length = Short.toUnsignedInt(inputBuffer.getShort());
byte number = inputBuffer.get();
int protocolId = Byte.toUnsignedInt(inputBuffer.get());
byte spiSize = inputBuffer.get();
int transformCount = Byte.toUnsignedInt(inputBuffer.get());
// TODO: Add check: spiSize must be 0 in initial IKE SA negotiation
// spiSize should be either 8 for IKE or 4 for IPsec.
long spi = SPI_NOT_INCLUDED;
switch (spiSize) {
case SPI_LEN_NOT_INCLUDED:
// No SPI attached for IKE initial exchange.
break;
case SPI_LEN_IPSEC:
spi = Integer.toUnsignedLong(inputBuffer.getInt());
break;
case SPI_LEN_IKE:
spi = inputBuffer.getLong();
break;
default:
throw new InvalidSyntaxException(
"Invalid value of spiSize in Proposal Substructure: " + spiSize);
}
Transform[] transformArray =
sTransformDecoder.decodeTransforms(transformCount, inputBuffer);
// TODO: Validate that sum of all Transforms' lengths plus Proposal header length equals
// to Proposal's length.
List Package private
*/
IkeProposal(
byte number,
byte spiSize,
long spi,
IkeSaProposal saProposal,
boolean hasUnrecognizedTransform) {
super(number, PROTOCOL_ID_IKE, spiSize, spi, hasUnrecognizedTransform);
this.saProposal = saProposal;
}
/** Construct IkeProposal for an outbound message for IKE negotiation. */
private IkeProposal(
byte number,
byte spiSize,
IkeSecurityParameterIndex ikeSpiResource,
IkeSaProposal saProposal) {
super(
number,
PROTOCOL_ID_IKE,
spiSize,
ikeSpiResource == null ? SPI_NOT_INCLUDED : ikeSpiResource.getSpi(),
false /* hasUnrecognizedTransform */);
mIkeSpiResource = ikeSpiResource;
this.saProposal = saProposal;
}
/**
* Construct IkeProposal for an outbound message for IKE negotiation.
*
* Package private
*/
@VisibleForTesting
static IkeProposal createIkeProposal(
byte number,
byte spiSize,
IkeSaProposal saProposal,
IkeSpiGenerator ikeSpiGenerator,
InetAddress localAddress)
throws IOException {
// IKE_INIT uses SPI_LEN_NOT_INCLUDED, while rekeys use SPI_LEN_IKE
IkeSecurityParameterIndex spiResource =
(spiSize == SPI_LEN_NOT_INCLUDED
? null
: ikeSpiGenerator.allocateSpi(localAddress));
return new IkeProposal(number, spiSize, spiResource, saProposal);
}
/** Package private method for releasing SPI resource in this unselected Proposal. */
void releaseSpiResourceIfExists() {
// mIkeSpiResource is null when doing IKE initial exchanges.
if (mIkeSpiResource == null) return;
mIkeSpiResource.close();
mIkeSpiResource = null;
}
/**
* Package private method for allocating SPI resource for a validated remotely generated IKE
* SA proposal.
*/
void allocateResourceForRemoteIkeSpi(
IkeSpiGenerator ikeSpiGenerator, InetAddress remoteAddress) throws IOException {
mIkeSpiResource = ikeSpiGenerator.allocateSpi(remoteAddress, spi);
}
@Override
public SaProposal getSaProposal() {
return saProposal;
}
/**
* Get the IKE SPI resource.
*
* @return the IKE SPI resource or null for IKE initial exchanges.
*/
public IkeSecurityParameterIndex getIkeSpiResource() {
return mIkeSpiResource;
}
}
/** This class represents a Proposal for Child SA negotiation. */
public static final class ChildProposal extends Proposal {
private SecurityParameterIndex mChildSpiResource;
public final ChildSaProposal saProposal;
/**
* Construct ChildProposal from a decoded inbound message for Child SA negotiation.
*
* Package private
*/
ChildProposal(
byte number,
long spi,
ChildSaProposal saProposal,
boolean hasUnrecognizedTransform) {
super(
number,
PROTOCOL_ID_ESP,
SPI_LEN_IPSEC,
spi,
hasUnrecognizedTransform);
this.saProposal = saProposal;
}
/** Construct ChildProposal for an outbound message for Child SA negotiation. */
private ChildProposal(
byte number, SecurityParameterIndex childSpiResource, ChildSaProposal saProposal) {
super(
number,
PROTOCOL_ID_ESP,
SPI_LEN_IPSEC,
(long) childSpiResource.getSpi(),
false /* hasUnrecognizedTransform */);
mChildSpiResource = childSpiResource;
this.saProposal = saProposal;
}
/**
* Construct ChildProposal for an outbound message for Child SA negotiation.
*
* Package private
*/
@VisibleForTesting
static ChildProposal createChildProposal(
byte number,
ChildSaProposal saProposal,
IpSecSpiGenerator ipSecSpiGenerator,
InetAddress localAddress)
throws SpiUnavailableException, ResourceUnavailableException {
return new ChildProposal(
number, ipSecSpiGenerator.allocateSpi(localAddress), saProposal);
}
/** Package private method for releasing SPI resource in this unselected Proposal. */
void releaseSpiResourceIfExists() {
if (mChildSpiResource == null) return;
mChildSpiResource.close();
mChildSpiResource = null;
}
/**
* Package private method for allocating SPI resource for a validated remotely generated
* Child SA proposal.
*/
void allocateResourceForRemoteChildSpi(
IpSecSpiGenerator ipSecSpiGenerator, InetAddress remoteAddress)
throws ResourceUnavailableException, SpiUnavailableException {
mChildSpiResource = ipSecSpiGenerator.allocateSpi(remoteAddress, (int) spi);
}
@Override
public SaProposal getSaProposal() {
return saProposal;
}
/**
* Get the IPsec SPI resource.
*
* @return the IPsec SPI resource.
*/
public SecurityParameterIndex getChildSpiResource() {
return mChildSpiResource;
}
}
@VisibleForTesting
interface AttributeDecoder {
List Transforms with unrecognized Transform ID or containing unrecognized Attribute Type
* shall be ignored when processing received SA payload.
*/
public abstract static class Transform {
@Retention(RetentionPolicy.SOURCE)
@IntDef({
TRANSFORM_TYPE_ENCR,
TRANSFORM_TYPE_PRF,
TRANSFORM_TYPE_INTEG,
TRANSFORM_TYPE_DH,
TRANSFORM_TYPE_ESN
})
public @interface TransformType {}
public static final int TRANSFORM_TYPE_ENCR = 1;
public static final int TRANSFORM_TYPE_PRF = 2;
public static final int TRANSFORM_TYPE_INTEG = 3;
public static final int TRANSFORM_TYPE_DH = 4;
public static final int TRANSFORM_TYPE_ESN = 5;
private static final byte LAST_TRANSFORM = 0;
private static final byte NOT_LAST_TRANSFORM = 3;
// Length of reserved field of a Transform.
private static final int TRANSFORM_RESERVED_FIELD_LEN = 1;
// Length of the Transform that with no Attribute.
protected static final int BASIC_TRANSFORM_LEN = 8;
// TODO: Add constants for supported algorithms
private static AttributeDecoder sAttributeDecoder = new AttributeDecoderImpl();
// Only supported type falls into {@link TransformType}
public final int type;
public final int id;
public final boolean isSupported;
/** Construct an instance of Transform for building an outbound packet. */
protected Transform(int type, int id) {
this.type = type;
this.id = id;
if (!isSupportedTransformId(id)) {
throw new IllegalArgumentException(
"Unsupported " + getTransformTypeString() + " Algorithm ID: " + id);
}
this.isSupported = true;
}
/** Construct an instance of Transform for decoding an inbound packet. */
protected Transform(int type, int id, List Proposing integrity algorithm for ESP SA is optional. Omitting the IntegrityTransform is
* equivalent to including it with a value of NONE. When multiple integrity algorithms are
* provided, choosing any of them are acceptable.
*
* @see RFC 7296, Internet Key
* Exchange Protocol Version 2 (IKEv2)
*/
public static final class IntegrityTransform extends Transform {
/**
* Contruct an instance of IntegrityTransform for building an outbound packet.
*
* @param id the IKE standard Transform ID.
*/
public IntegrityTransform(@IntegrityAlgorithm int id) {
super(Transform.TRANSFORM_TYPE_INTEG, id);
}
/**
* Contruct an instance of IntegrityTransform for decoding an inbound packet.
*
* @param id the IKE standard Transform ID.
* @param attributeList the decoded list of Attribute.
* @throws InvalidSyntaxException for syntax error.
*/
protected IntegrityTransform(int id, List Proposing DH group for non-first Child SA is optional. Omitting the DhGroupTransform is
* equivalent to including it with a value of NONE. When multiple DH groups are provided,
* choosing any of them are acceptable.
*
* @see RFC 7296, Internet Key
* Exchange Protocol Version 2 (IKEv2)
*/
public static final class DhGroupTransform extends Transform {
/**
* Contruct an instance of DhGroupTransform for building an outbound packet.
*
* @param id the IKE standard Transform ID.
*/
public DhGroupTransform(@DhGroup int id) {
super(Transform.TRANSFORM_TYPE_DH, id);
}
/**
* Contruct an instance of DhGroupTransform for decoding an inbound packet.
*
* @param id the IKE standard Transform ID.
* @param attributeList the decoded list of Attribute.
* @throws InvalidSyntaxException for syntax error.
*/
protected DhGroupTransform(int id, List Currently IKE library only supports negotiating IPsec SA that do not use extended sequence
* numbers. The Transform ID of EsnTransform in outbound packets is not user configurable.
*
* @see RFC 7296, Internet Key
* Exchange Protocol Version 2 (IKEv2)
*/
public static final class EsnTransform extends Transform {
@Retention(RetentionPolicy.SOURCE)
@IntDef({ESN_POLICY_NO_EXTENDED, ESN_POLICY_EXTENDED})
public @interface EsnPolicy {}
public static final int ESN_POLICY_NO_EXTENDED = 0;
public static final int ESN_POLICY_EXTENDED = 1;
/**
* Construct an instance of EsnTransform indicates using no-extended sequence numbers for
* building an outbound packet.
*/
public EsnTransform() {
super(Transform.TRANSFORM_TYPE_ESN, ESN_POLICY_NO_EXTENDED);
}
/**
* Contruct an instance of EsnTransform for decoding an inbound packet.
*
* @param id the IKE standard Transform ID.
* @param attributeList the decoded list of Attribute.
* @throws InvalidSyntaxException for syntax error.
*/
protected EsnTransform(int id, List Proposals containing an UnrecognizedTransform should be ignored.
*/
protected static final class UnrecognizedTransform extends Transform {
protected UnrecognizedTransform(int type, int id, List Attribute is either in Type/Value format or Type/Length/Value format. For TV format,
* Attribute length is always 4 bytes containing value for 2 bytes. While for TLV format,
* Attribute length is determined by length field.
*
* Currently only Key Length type is supported
*
* @see RFC 7296, Internet Key
* Exchange Protocol Version 2 (IKEv2)
*/
public abstract static class Attribute {
@Retention(RetentionPolicy.SOURCE)
@IntDef({ATTRIBUTE_TYPE_KEY_LENGTH})
public @interface AttributeType {}
// Support only one Attribute type: Key Length. Should use Type/Value format.
public static final int ATTRIBUTE_TYPE_KEY_LENGTH = 14;
// Mask to extract the left most AF bit to indicate Attribute Format.
private static final int ATTRIBUTE_FORMAT_MASK = 0x8000;
// Mask to extract 15 bits after the AF bit to indicate Attribute Type.
private static final int ATTRIBUTE_TYPE_MASK = 0x7fff;
// Package private mask to indicate that Type-Value (TV) Attribute Format is used.
static final int ATTRIBUTE_FORMAT_TV = ATTRIBUTE_FORMAT_MASK;
// Package private
static final int TV_ATTRIBUTE_VALUE_LEN = 2;
static final int TV_ATTRIBUTE_TOTAL_LEN = 4;
static final int TVL_ATTRIBUTE_HEADER_LEN = TV_ATTRIBUTE_TOTAL_LEN;
// Only Key Length type belongs to AttributeType
public final int type;
/** Construct an instance of an Attribute when decoding message. */
protected Attribute(int type) {
this.type = type;
}
@VisibleForTesting
static Pair Transforms containing UnrecognizedAttribute should be ignored.
*/
protected static final class UnrecognizedAttribute extends Attribute {
protected UnrecognizedAttribute(int type, byte[] value) {
super(type);
}
@Override
protected void encodeToByteBuffer(ByteBuffer byteBuffer) {
throw new UnsupportedOperationException(
"It is not supported to encode an unrecognized Attribute.");
}
@Override
protected int getAttributeLength() {
throw new UnsupportedOperationException(
"It is not supported to get length of an unrecognized Attribute.");
}
}
/**
* Encode SA payload to ByteBUffer.
*
* @param nextPayload type of payload that follows this payload.
* @param byteBuffer destination ByteBuffer that stores encoded payload.
*/
@Override
protected void encodeToByteBuffer(@PayloadType int nextPayload, ByteBuffer byteBuffer) {
encodePayloadHeaderToByteBuffer(nextPayload, getPayloadLength(), byteBuffer);
for (int i = 0; i < proposalList.size(); i++) {
// The last proposal has the isLast flag set to true.
proposalList.get(i).encodeToByteBuffer(i == proposalList.size() - 1, byteBuffer);
}
}
/**
* Get entire payload length.
*
* @return entire payload length.
*/
@Override
protected int getPayloadLength() {
int len = GENERIC_HEADER_LENGTH;
for (Proposal p : proposalList) len += p.getProposalLength();
return len;
}
/**
* Return the payload type as a String.
*
* @return the payload type as a String.
*/
@Override
public String getTypeString() {
return "SA";
}
@Override
@NonNull
public String toString() {
StringBuilder sb = new StringBuilder();
if (isSaResponse) {
sb.append("SA Response: ");
} else {
sb.append("SA Request: ");
}
int len = proposalList.size();
for (int i = 0; i < len; i++) {
sb.append(proposalList.get(i).toString());
if (i < len - 1) sb.append(", ");
}
return sb.toString();
}
}