diff --git a/src/controller/java/src/chip/devicecontroller/ChipDeviceController.java b/src/controller/java/src/chip/devicecontroller/ChipDeviceController.java index 31b1f58d16a48d..74f1628b5eb63d 100644 --- a/src/controller/java/src/chip/devicecontroller/ChipDeviceController.java +++ b/src/controller/java/src/chip/devicecontroller/ChipDeviceController.java @@ -37,8 +37,7 @@ public class ChipDeviceController { private NOCChainIssuer nocChainIssuer; /** - * To load class and jni, we need to new AndroidChipPlatform after jni load but - * before new + * To load class and jni, we need to new AndroidChipPlatform after jni load but before new * ChipDeviceController */ public static void loadJni() { @@ -46,10 +45,8 @@ public static void loadJni() { } /** - * Returns a new {@link ChipDeviceController} with the specified parameters. you - * must set a vendor - * ID, ControllerParams.newBuilder().setControllerVendorId(0xFFF4).build() - * 0xFFF4 is a test vendor + * Returns a new {@link ChipDeviceController} with the specified parameters. you must set a vendor + * ID, ControllerParams.newBuilder().setControllerVendorId(0xFFF4).build() 0xFFF4 is a test vendor * ID */ public ChipDeviceController(ControllerParams params) { @@ -68,24 +65,16 @@ public void setScanNetworksListener(ScanNetworksListener listener) { } /** - * Sets this DeviceController to use the given issuer for issuing operational - * certs and verifying - * the DAC. By default, the DeviceController uses an internal, - * OperationalCredentialsDelegate (see + * Sets this DeviceController to use the given issuer for issuing operational certs and verifying + * the DAC. By default, the DeviceController uses an internal, OperationalCredentialsDelegate (see * AndroidOperationalCredentialsIssuer). * - *

- * When a NOCChainIssuer is set for this controller, then - * onNOCChainGenerationNeeded will be - * called when the NOC CSR needs to be signed and DAC verified. This allows for - * custom credentials - * issuer and DAC verifier implementations, for example, when a proprietary - * cloud API will perform + *

When a NOCChainIssuer is set for this controller, then onNOCChainGenerationNeeded will be + * called when the NOC CSR needs to be signed and DAC verified. This allows for custom credentials + * issuer and DAC verifier implementations, for example, when a proprietary cloud API will perform * DAC verification and the CSR signing. * - *

- * When a NOCChainIssuer is set for this controller, the PartialDACVerifier will - * be used rather + *

When a NOCChainIssuer is set for this controller, the PartialDACVerifier will be used rather * than the DefaultDACVerifier. * * @param issuer @@ -96,48 +85,37 @@ public void setNOCChainIssuer(NOCChainIssuer issuer) { } /** - * If DeviceAttestationCompletionCallback is setted, then it will always be - * called when device + * If DeviceAttestationCompletionCallback is setted, then it will always be called when device * attestation completes. * - *

- * When {@link + *

When {@link * DeviceAttestationDelegate.DeviceAttestationCompletionCallback#onDeviceAttestationCompleted(long, - * long, AttestationInfo, int)} is received, - * {@link #continueCommissioning(long, boolean)} must be + * long, AttestationInfo, int)} is received, {@link #continueCommissioning(long, boolean)} must be * called. * - * @param failSafeExpiryTimeoutSecs the value to set for the fail-safe timer - * before - * onDeviceAttestationCompleted is invoked. The - * unit is seconds. - * @param completionCallback the callback will be invoked when - * deviceattestation completed with - * device info for additional verification. + * @param failSafeExpiryTimeoutSecs the value to set for the fail-safe timer before + * onDeviceAttestationCompleted is invoked. The unit is seconds. + * @param completionCallback the callback will be invoked when deviceattestation completed with + * device info for additional verification. */ public void setDeviceAttestationCompletionCallback( int failSafeExpiryTimeoutSecs, DeviceAttestationDelegate.DeviceAttestationCompletionCallback completionCallback) { - setDeviceAttestationDelegate(deviceControllerPtr, failSafeExpiryTimeoutSecs, completionCallback); + setDeviceAttestationDelegate( + deviceControllerPtr, failSafeExpiryTimeoutSecs, completionCallback); } /** - * If DeviceAttestationFailureCallback is setted, then it will be called when - * device attestation + * If DeviceAttestationFailureCallback is setted, then it will be called when device attestation * fails, and the client can decide to continue or stop the commissioning. * - *

- * When {@link + *

When {@link * DeviceAttestationDelegate.DeviceAttestationFailureCallback#onDeviceAttestationFailed(long, - * long, int)} is received, {@link #continueCommissioning(long, boolean)} must - * be called. + * long, int)} is received, {@link #continueCommissioning(long, boolean)} must be called. * - * @param failSafeExpiryTimeoutSecs the value to set for the fail-safe timer - * before - * onDeviceAttestationFailed is invoked. The - * unit is seconds. - * @param failureCallback the callback will be invoked when device - * attestation failed. + * @param failSafeExpiryTimeoutSecs the value to set for the fail-safe timer before + * onDeviceAttestationFailed is invoked. The unit is seconds. + * @param failureCallback the callback will be invoked when device attestation failed. */ public void setDeviceAttestationFailureCallback( int failSafeExpiryTimeoutSecs, @@ -157,15 +135,12 @@ public void pairDevice( /** * Pair a device connected through BLE. * - * @param bleServer the BluetoothGatt representing the BLE connection to the - * device - * @param connId the BluetoothGatt Id representing the BLE connection to - * the device - * @param deviceId the node ID to assign to the device + * @param bleServer the BluetoothGatt representing the BLE connection to the device + * @param connId the BluetoothGatt Id representing the BLE connection to the device + * @param deviceId the node ID to assign to the device * @param setupPincode the pincode for the device - * @param csrNonce the 32-byte CSR nonce to use, or null if we want to use - * an internally randomly - * generated CSR nonce. + * @param csrNonce the 32-byte CSR nonce to use, or null if we want to use an internally randomly + * generated CSR nonce. */ public void pairDevice( BluetoothGatt bleServer, @@ -226,9 +201,9 @@ public void establishPaseConnection(long deviceId, int connId, long setupPincode /** * Establish a secure PASE connection to the given device via IP address. * - * @param deviceId the ID of the node to connect to - * @param address the IP address at which the node is located - * @param port the port at which the node is located + * @param deviceId the ID of the node to connect to + * @param address the IP address at which the node is located + * @param port the port at which the node is located * @param setupPincode the pincode for this node */ public void establishPaseConnection(long deviceId, String address, int port, long setupPincode) { @@ -237,12 +212,11 @@ public void establishPaseConnection(long deviceId, String address, int port, lon } /** - * Initiates the automatic commissioning flow using the specified network - * credentials. It is + * Initiates the automatic commissioning flow using the specified network credentials. It is * expected that a secure session has already been established via {@link * #establishPaseConnection(long, int, long)}. * - * @param deviceId the ID of the node to be commissioned + * @param deviceId the ID of the node to be commissioned * @param networkCredentials the credentials (Wi-Fi or Thread) to be provisioned */ public void commissionDevice(long deviceId, @Nullable NetworkCredentials networkCredentials) { @@ -250,13 +224,12 @@ public void commissionDevice(long deviceId, @Nullable NetworkCredentials network } /** - * Initiates the automatic commissioning flow using the specified network - * credentials. It is + * Initiates the automatic commissioning flow using the specified network credentials. It is * expected that a secure session has already been established via {@link * #establishPaseConnection(long, int, long)}. * - * @param deviceId the ID of the node to be commissioned - * @param csrNonce a nonce to be used for the CSR request + * @param deviceId the ID of the node to be commissioned + * @param csrNonce a nonce to be used for the CSR request * @param networkCredentials the credentials (Wi-Fi or Thread) to be provisioned */ public void commissionDevice( @@ -265,12 +238,10 @@ public void commissionDevice( } /** - * This function instructs the commissioner to proceed to the next stage of - * commissioning after + * This function instructs the commissioner to proceed to the next stage of commissioning after * attestation is reported. * - * @param devicePtr a pointer to the device which is being - * commissioned. + * @param devicePtr a pointer to the device which is being commissioned. * @param ignoreAttestationFailure whether to ignore device attestation failure. */ public void continueCommissioning(long devicePtr, boolean ignoreAttestationFailure) { @@ -278,28 +249,18 @@ public void continueCommissioning(long devicePtr, boolean ignoreAttestationFailu } /** - * When a NOCChainIssuer is set for this controller, then - * onNOCChainGenerationNeeded will be - * called when the NOC CSR needs to be signed. This allows for custom - * credentials issuer - * implementations, for example, when a proprietary cloud API will perform the - * CSR signing. + * When a NOCChainIssuer is set for this controller, then onNOCChainGenerationNeeded will be + * called when the NOC CSR needs to be signed. This allows for custom credentials issuer + * implementations, for example, when a proprietary cloud API will perform the CSR signing. * - *

- * The commissioning workflow will stop upon the onNOCChainGenerationNeeded - * callback and resume + *

The commissioning workflow will stop upon the onNOCChainGenerationNeeded callback and resume * once onNOCChainGeneration is called. * - *

- * The following fields on the ControllerParams object MUST be populated: - * rootCertificate, + *

The following fields on the ControllerParams object MUST be populated: rootCertificate, * intermediateCertificate, operationalCertificate * - *

- * If ipk and adminSubject are set on the ControllerParams object, then they - * will be used in - * the AddNOC command set to the commissionee. If they are not populated, then - * the values provided + *

If ipk and adminSubject are set on the ControllerParams object, then they will be used in + * the AddNOC command set to the commissionee. If they are not populated, then the values provided * in the ChipDeviceController initialization will be used. * * @param params @@ -310,19 +271,14 @@ public int onNOCChainGeneration(ControllerParams params) { } /** - * Update the network credentials held by the commissioner for the current - * commissioning session. - * The updated values will be used by the commissioner if the network - * credentials haven't already + * Update the network credentials held by the commissioner for the current commissioning session. + * The updated values will be used by the commissioner if the network credentials haven't already * been sent to the device. * - *

- * Its expected that this method will be called in response to the NetworkScan - * or the + *

Its expected that this method will be called in response to the NetworkScan or the * ReadCommissioningInfo callbacks. * - * @param networkCredentials the credentials (Wi-Fi or Thread) to use in - * commissioning + * @param networkCredentials the credentials (Wi-Fi or Thread) to use in commissioning */ public void updateCommissioningNetworkCredentials(NetworkCredentials networkCredentials) { updateCommissioningNetworkCredentials(deviceControllerPtr, networkCredentials); @@ -333,8 +289,7 @@ public void unpairDevice(long deviceId) { } /** - * Returns a pointer to a device currently being commissioned. This should be - * used before the + * Returns a pointer to a device currently being commissioned. This should be used before the * device is operationally available. */ public long getDeviceBeingCommissionedPointer(long nodeId) { @@ -342,18 +297,12 @@ public long getDeviceBeingCommissionedPointer(long nodeId) { } /** - * Through GetConnectedDeviceCallback, returns a pointer to a connected device - * or an error. + * Through GetConnectedDeviceCallback, returns a pointer to a connected device or an error. * - *

- * The native code invoked by this method creates a strong reference to the - * provided callback, - * which is released only when GetConnectedDeviceCallback has returned success - * or failure. + *

The native code invoked by this method creates a strong reference to the provided callback, + * which is released only when GetConnectedDeviceCallback has returned success or failure. * - *

- * TODO(#8443): This method could benefit from a ChipDevice abstraction to hide - * the pointer + *

TODO(#8443): This method could benefit from a ChipDevice abstraction to hide the pointer * passing. */ public void getConnectedDevicePointer(long nodeId, GetConnectedDeviceCallback callback) { @@ -410,8 +359,10 @@ public void onScanNetworksFailure(int errorCode) { public void onScanNetworksSuccess( Integer networkingStatus, Optional debugText, - Optional> wiFiScanResults, - Optional> threadScanResults) { + Optional> + wiFiScanResults, + Optional> + threadScanResults) { if (scanNetworksListener != null) { scanNetworksListener.onScanNetworksSuccess( networkingStatus, debugText, wiFiScanResults, threadScanResults); @@ -476,12 +427,10 @@ public String getIpAddress(long deviceId) { } /** - * Returns the {@link NetworkLocation} at which the given {@code deviceId} has - * been found. + * Returns the {@link NetworkLocation} at which the given {@code deviceId} has been found. * * @param deviceId the 64-bit node ID of the device - * @throws ChipDeviceControllerException if the device location could not be - * resolved + * @throws ChipDeviceControllerException if the device location could not be resolved */ public NetworkLocation getNetworkLocation(long deviceId) { return getNetworkLocation(deviceControllerPtr, deviceId); @@ -492,19 +441,17 @@ public long getCompressedFabricId() { } /** - * Returns the compressed fabric ID based on the given root certificate and node - * operational + * Returns the compressed fabric ID based on the given root certificate and node operational * credentials. * * @param rcac the root certificate (in Matter cert form) - * @param noc the NOC (in Matter cert form) + * @param noc the NOC (in Matter cert form) * @see #convertX509CertToMatterCert(byte[]) */ public native long generateCompressedFabricId(byte[] rcac, byte[] noc); /** - * Get commmissionible Node. Commmissionible Node results are able to get using - * {@link + * Get commmissionible Node. Commmissionible Node results are able to get using {@link * ChipDeviceController.getDiscoveredDevice}. */ public void discoverCommissionableNodes() { @@ -547,13 +494,11 @@ public void shutdownSubscriptions(long devicePtr) { } /** - * Returns an attestation challenge for the given device, for which there must - * be an existing + * Returns an attestation challenge for the given device, for which there must be an existing * secure session. * * @param devicePtr a pointer to the device from which to retrieve the challenge - * @throws ChipDeviceControllerException if there is no secure session for the - * given device + * @throws ChipDeviceControllerException if there is no secure session for the given device */ public byte[] getAttestationChallenge(long devicePtr) { return getAttestationChallenge(deviceControllerPtr, devicePtr); @@ -567,7 +512,8 @@ public void subscribeToAttributePath( List attributePaths, int minInterval, int maxInterval) { - ReportCallbackJni jniCallback = new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); + ReportCallbackJni jniCallback = + new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); subscribe( deviceControllerPtr, jniCallback.getCallbackHandle(), @@ -588,7 +534,8 @@ public void subscribeToEventPath( List eventPaths, int minInterval, int maxInterval) { - ReportCallbackJni jniCallback = new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); + ReportCallbackJni jniCallback = + new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); subscribe( deviceControllerPtr, jniCallback.getCallbackHandle(), @@ -601,10 +548,7 @@ public void subscribeToEventPath( false); } - /** - * Subscribe to the given attribute/event path with keepSubscriptions and - * isFabricFiltered. - */ + /** Subscribe to the given attribute/event path with keepSubscriptions and isFabricFiltered. */ public void subscribeToPath( SubscriptionEstablishedCallback subscriptionEstablishedCallback, ResubscriptionAttemptCallback resubscriptionAttemptCallback, @@ -619,7 +563,8 @@ public void subscribeToPath( // TODO: pass resubscriptionAttemptCallback to ReportCallbackJni since jni layer // is not ready // for auto-resubscribe - ReportCallbackJni jniCallback = new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); + ReportCallbackJni jniCallback = + new ReportCallbackJni(subscriptionEstablishedCallback, reportCallback, null); subscribe( deviceControllerPtr, jniCallback.getCallbackHandle(), @@ -672,20 +617,18 @@ public void readPath( /** * Converts a given X.509v3 certificate into a Matter certificate. * - * @throws ChipDeviceControllerException if there was an issue during encoding - * (e.g. out of - * memory, invalid certificate format) + * @throws ChipDeviceControllerException if there was an issue during encoding (e.g. out of + * memory, invalid certificate format) */ public native byte[] convertX509CertToMatterCert(byte[] x509Cert); /** * Generates a new PASE verifier for the given setup PIN code. * - * @param devicePtr a pointer to the device object for which to generate the - * PASE verifier + * @param devicePtr a pointer to the device object for which to generate the PASE verifier * @param setupPincode the PIN code to use - * @param iterations the number of iterations for computing the verifier - * @param salt the 16-byte salt + * @param iterations the number of iterations for computing the verifier + * @param salt the 16-byte salt */ public PaseVerifierParams computePaseVerifier( long devicePtr, long setupPincode, long iterations, byte[] salt) { @@ -826,46 +769,28 @@ protected void finalize() throws Throwable { } } - /** - * Interface to implement custom operational credentials issuer (NOC chain - * generation). - */ + /** Interface to implement custom operational credentials issuer (NOC chain generation). */ public interface NOCChainIssuer { /** - * When a NOCChainIssuer is set for this controller, then - * onNOCChainGenerationNeeded will be - * called when the DAC chain must be verified and NOC chain needs to be issued - * from a CSR. This - * allows for custom credentials issuer and DAC verifier implementations, for - * example, when a - * proprietary cloud API will perform DAC verification and the NOC chain - * issuance from CSR. + * When a NOCChainIssuer is set for this controller, then onNOCChainGenerationNeeded will be + * called when the DAC chain must be verified and NOC chain needs to be issued from a CSR. This + * allows for custom credentials issuer and DAC verifier implementations, for example, when a + * proprietary cloud API will perform DAC verification and the NOC chain issuance from CSR. * - *

- * When a NOCChainIssuer is set for this controller, the PartialDACVerifier will - * be used + *

When a NOCChainIssuer is set for this controller, the PartialDACVerifier will be used * rather than the DefaultDACVerifier. * - *

- * The commissioning workflow will stop upon the onNOCChainGenerationNeeded - * callback and + *

The commissioning workflow will stop upon the onNOCChainGenerationNeeded callback and * resume once onNOCChainGeneration is called. * - *

- * The following fields on the ControllerParams object passed to - * onNOCChainGeneration MUST be + *

The following fields on the ControllerParams object passed to onNOCChainGeneration MUST be * populated: rootCertificate, intermediateCertificate, operationalCertificate * - *

- * If ipk and adminSubject are set on the ControllerParams object, then they - * will be used in - * the AddNOC command set to the commissionee. If they are not populated, then - * the values + *

If ipk and adminSubject are set on the ControllerParams object, then they will be used in + * the AddNOC command set to the commissionee. If they are not populated, then the values * provided in the ChipDeviceController initialization will be used. * - *

- * All csr and attestation fields are provided to allow for custom - * attestestation checks. + *

All csr and attestation fields are provided to allow for custom attestestation checks. */ void onNOCChainGenerationNeeded(CSRInfo csrInfo, AttestationInfo attestationInfo); } @@ -873,20 +798,13 @@ public interface NOCChainIssuer { /** * Interface to listen for scan networks callbacks from CHIPDeviceController. * - *

- * Set the AttemptNetworkScanWiFi or AttemptNetworkScanThread to configure the - * enable/disable - * WiFi or Thread network scan during commissioning in the the default - * CommissioningDelegate used + *

Set the AttemptNetworkScanWiFi or AttemptNetworkScanThread to configure the enable/disable + * WiFi or Thread network scan during commissioning in the the default CommissioningDelegate used * by the ChipDeviceCommissioner. * - *

- * When the callbacks onScanNetworksFailure or onScanNetworksSuccess are - * invoked, the - * commissioning flow has reached the kNeedsNetworkCreds and will wait to - * advance until this - * device controller's updateCommissioningNetworkCredentials method is called - * with the desired + *

When the callbacks onScanNetworksFailure or onScanNetworksSuccess are invoked, the + * commissioning flow has reached the kNeedsNetworkCreds and will wait to advance until this + * device controller's updateCommissioningNetworkCredentials method is called with the desired * network credentials set. */ public interface ScanNetworksListener { @@ -896,8 +814,10 @@ public interface ScanNetworksListener { void onScanNetworksSuccess( Integer networkingStatus, Optional debugText, - Optional> wiFiScanResults, - Optional> threadScanResults); + Optional> + wiFiScanResults, + Optional> + threadScanResults); } /** Interface to listen for callbacks from CHIPDeviceController. */ @@ -934,9 +854,7 @@ void onReadCommissioningInfo( /** Notifies the listener of the error. */ void onError(Throwable error); - /** - * Notifies the Commissioner when the OpCSR for the Comissionee is generated. - */ + /** Notifies the Commissioner when the OpCSR for the Comissionee is generated. */ void onOpCSRGenerationComplete(byte[] csr); } } diff --git a/src/controller/java/src/chip/devicecontroller/DeviceAttestationDelegate.java b/src/controller/java/src/chip/devicecontroller/DeviceAttestationDelegate.java index 7aa8b50e1755ff..12a85e03413eaf 100644 --- a/src/controller/java/src/chip/devicecontroller/DeviceAttestationDelegate.java +++ b/src/controller/java/src/chip/devicecontroller/DeviceAttestationDelegate.java @@ -3,24 +3,17 @@ /** * Only one of the following delegate callbacks should be implemented. * - *

- * If one of the following callbacks is implemented, {@link - * ChipDeviceController#continueCommissioning(long, boolean)} is expected to be - * called if + *

If one of the following callbacks is implemented, {@link + * ChipDeviceController#continueCommissioning(long, boolean)} is expected to be called if * commissioning should continue. * - *

- * If DeviceAttestationCompletionCallback is implemented, then it will always be - * called when + *

If DeviceAttestationCompletionCallback is implemented, then it will always be called when * device attestation completes. * - *

- * If DeviceAttestationFailureCallback is implemented, then it will be called - * when device - * attestation fails, and the client can decide to continue or stop the - * commissioning. + *

If DeviceAttestationFailureCallback is implemented, then it will be called when device + * attestation fails, and the client can decide to continue or stop the commissioning. * - * For example: + *

For example: * * 

  * // Continue commissioning
@@ -29,24 +22,20 @@
  * // Stop commissioning
  * deviceController.continueCommissioning(devicePtr, true)
  *
- * */ public interface DeviceAttestationDelegate { public interface DeviceAttestationCompletionCallback extends DeviceAttestationDelegate { /** - * The callback will be invoked when device attestation completed with device - * info for + * The callback will be invoked when device attestation completed with device info for * additional verification. * - *

- * This allows the callback to stop commissioning after examining the device - * info (DAC, PAI, + *

This allows the callback to stop commissioning after examining the device info (DAC, PAI, * CD). * - * @param devicePtr Handle of device being commissioned + * @param devicePtr Handle of device being commissioned * @param attestationInfo Attestation information for the device - * @param errorCode Error code on attestation failure. 0 if success. + * @param errorCode Error code on attestation failure. 0 if success. */ void onDeviceAttestationCompleted( long devicePtr, AttestationInfo attestationInfo, int errorCode);