Merge "Create UserRecovery AIDL definitions" into main

/*

 * Copyright (C) 2025 The Android Open Source Project

 *

 * 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 android.app.userrecovery;

/**

 * Parcelable to hold a single certificate represented as a byte array.

 * @hide

 */

parcelable CertificateBlob {

    byte[] blob;

}

/*

 * Copyright (C) 2025 The Android Open Source Project

 *

 * 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 android.app.userrecovery;

/**

 * Contains the escrow token data and metadata for a user's recovery factor.

 * This data is typically provided by an external recovery agent or service.

 * @hide

 */

parcelable EscrowToken {

    /** Version of this token structure. */

    int version;

    /**

     * Identifier for the backend or service key used for wrapping.

     * Similar to RecoverableKeyStoreParameters.backend_public_key in CrOS.

     */

    byte[] backendPublicKeyId;

    /**

     * The core encrypted recovery data. This might be analogous to

     * RecoverableKeyStore.wrapped_recovery_key, potentially

     * including the user's knowledge factor hash.

     */

    byte[] wrappedRecoveryData;

    // Metadata fields, similar to RecoverableKeyStoreMetadata in CrOS:

    /**

     * Type of knowledge factor (e.g., PIN, PASSWORD).

     * We should define an int enum for this in UserRecoveryManager.java.

     */

    int knowledgeFactorType;

    /** Algorithm used to hash the knowledge factor. Int enum. */

    int hashAlgorithm;

    /** Salt used in the knowledge factor hashing. */

    byte[] hashSalt;

    /**

     * Application-specific metadata for the recovery agent.

     */

    byte[] applicationMetadata;

    /**

     * Identifier for a hardware counter to limit attempts (if applicable).

     * Similar to RecoverableKeyStoreParameters.counter_id.

     */

    byte[] counterId;

    /** Maximum allowed failed attempts. */

    int maxAttempts;

}

package android.app.userrecovery;

package android.app.userrecovery;

import android.app.userrecovery.IUserRecoverySession;

import android.app.userrecovery.RecoveryChallenge;

/**

/**

* Interface between an app and the server implementation service (UserRecoveryManagerService).

* Main interface for managing user recovery operations.

* @hide

* @hide

*/

*/

oneway interface IUserRecoveryManager {

interface IUserRecoveryManager {

    /**

     * Initiates a new recovery session for the given user to add recovery data.

     * Returns an IUserRecoverySession instance to manage this specific session.

     */

    IUserRecoverySession createRecoverySession(int userId) = 0;

    /**

     * Requests a Recovery Agent Registration Token (RART) for the user.

     * This token is used to register a new recovery agent.

     */

    byte[] requestRart(int userId) = 1;

    /**

     * Starts the recovery process for the user.

     * Returns a challenge to be solved by the recovery agent.

     */

    RecoveryChallenge startRecovery(int userId) = 2;

}

}

/*

 * Copyright (C) 2025 The Android Open Source Project

 *

 * 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 android.app.userrecovery;

import android.app.userrecovery.EscrowToken;

import android.app.userrecovery.RecoveryAgentResponse;

import android.app.userrecovery.CertificateBlob; // Import the new Parcelable

import java.util.List;

/**

* Interface representing a single recovery session for a user.

* An instance of this interface is obtained from IUserRecoveryManager.createRecoverySession().

* @hide

*/

interface IUserRecoverySession {

    /**

     * Provides an escrow token received from a recovery agent

     * to the service for this session.

     */

    void saveEscrowToken(in EscrowToken escrowToken) = 0;

    /**

     * Called by the recovery agent to save the key pair generated for

     * the user's recovery for this session.

     * keyBlob: The encrypted key pair.

     * certChain: The attestation certificate chain for the key pair,

     *            represented as a List of CertificateBlob objects.

     */

    void saveKeyPair(in byte[] keyBlob, in List<CertificateBlob> certChain) = 1;

    /**

     * Requests validation of a recovery attempt for this session.

     */

    boolean requestValidation(in RecoveryAgentResponse recoveryResponse) = 2;

    /**

     * Closes this recovery session, releasing any associated resources.

     * After calling close, other methods on this interface instance may fail.

     */

    void close() = 3;

}

/*

 * Copyright (C) 2025 The Android Open Source Project

 *

 * 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 android.app.userrecovery;

/**

 * Response from a recovery agent to a challenge.

 * @hide

 */

parcelable RecoveryAgentResponse {

    /** The agent's response to the server/service challenge. */

    byte[] responseData;

}