Android Device Encryption

 1private boolean setLockCredentialInternal(LockscreenCredential credential,
 2        LockscreenCredential savedCredential, int userId, boolean isLockTiedToParent) {
 3    // None-LSKF protector (not null)
 4    final long oldProtectorId = getCurrentLskfBasedProtectorId(userId);
 5    AuthenticationResult authResult = mSpManager.unlockLskfBasedProtector(
 6            getGateKeeperService(), oldProtectorId, savedCredential, userId, null);
 7    VerifyCredentialResponse response = authResult.gkResponse;
 8    // not null
 9    SyntheticPassword sp = authResult.syntheticPassword;
10
11    // 키 설정을 위해 필요한 unlock들이 있음. 준비 절차 수행하는곳
12    onSyntheticPasswordUnlocked(userId, sp);
13    // 실질적인 키 세팅. Gatekeeper에 최초 세팅하는 함수
14    setLockCredentialWithSpLocked(credential, sp, userId);
15}

 1private long setLockCredentialWithSpLocked(LockscreenCredential credential,
 2        SyntheticPassword sp, int userId) {
 3    // 전달받은 credential로 새 ProtectorID를 생성. 이때 Gatekeeper가 관여한다. 
 4    // 이때 oldProtector의 sp를 그대로 전달하는데, sp는 동일하게 사용함. 
 5    final long newProtectorId = mSpManager.createLskfBasedProtector(getGateKeeperService(), credential, sp, userId);
 6    if (!credential.isNone()) {
 7        // 완전 최초 설정엔 Sid(Keystore에서 사용할 사용자 식별값)가 없다.
 8        if (!mSpManager.hasSidForUser(userId)) {
 9            // Gatekeeper를 통해 비밀키로 서명된 password_handle을 발급받아 REE에 저장
10            // /data/system_de/<userId>/spblob/0000000000000000.handle
11            mSpManager.newSidForUser(getGateKeeperService(), sp, userId);
12            // Gatekeeper에서 인증된 상태임을 확인하고 범용 HAT(Hardware Auth Token) 전달
13            // 지정한 AUTH_TIMEOUT 시간 동안 HAT가 유효하며 PIN 설정 직후에도 백업등 키가 필요한 일부 기능들 사용 가능
14            mSpManager.verifyChallenge(getGateKeeperService(), sp, 0L, userId);
15        }
16    else {
17        // ... 잠금해제 로직
18    }
19    // LSKF protector를 방금 생성한걸로 스위치. 
20    // 이후 잠금해제에서 사용되는 protector는 이 값이 된다. 
21    setCurrentLskfBasedProtectorId(newProtectorId, userId);
22    // 시스템에 캐시된 자격 타입(PIN/패턴/없음)을 무효화
23    LockPatternUtils.invalidateCredentialTypeCache();
24    // 이전 oldProtector 삭제
25    mSpManager.destroyLskfBasedProtector(oldProtectorId, userId);
26}

 1/*** 
 2입력: (gatekeeper, credential, sp, userId)
 3↓
 4protectorId 생성 → PIN 길이(옵션) 계산 → PasswordData 준비 → LSKF 스트레칭
 5↓
 6Weaver 사용? (환경/설정/빈 LSKF 여부로 결정)
 7  ├─ Yes: Weaver 슬롯 등록(enroll) → FRP 동기화(Weaver) → protectorSecret = f(stretched, weaverSecret)
 8  └─ No : (빈 LSKF 아니면) GK enroll → FRP 동기화(GK)
 9          protectorSecret = f(stretched, secdiscardable)
10↓
11PasswordData/메트릭 저장(빈 LSKF 아니면)
12↓
13SP Blob 생성(= protectorId로 SP를 저장, sid 함께) → 디스크 flush → protectorId 반환
14***/
15public long createLskfBasedProtector(IGateKeeperService gatekeeper,
16        LockscreenCredential credential, SyntheticPassword sp, int userId) {
17    long protectorId = generateProtectorId();
18    // LSKF 타입, 길이 등 메타데이터 및 scrypt 저장 컨테이너(N, r, p, salt) 생성
19    PasswordData pwd = credential.isNone() ? null :
20            PasswordData.create(credential.getType(), pinLength);
21    // scrypt로 credential 스트레치. 
22    // 그림에서 Token이라고 부르는건 이 stretchedLskf 키를 의미함.
23    byte[] stretchedLskf = stretchLskf(credential, pwd);
24    long sid = GateKeeper.INVALID_SECURE_USER_ID;
25    final byte[] protectorSecret;
26
27    final IWeaver weaver = getWeaverService();    // or 사용할 수 없다면 null
28    if (weaver != null) {
29        // 사용가능한 슬롯 할당
30        int weaverSlot = getNextAvailableWeaverSlot();
31        // stretchedLskf 로 만든 WeaverKey를 등록하는데 null이면 새 랜덤값을 기록하고 반환
32        byte[] weaverSecret = weaverEnroll(weaver, weaverSlot,
33                    stretchedLskfToWeaverKey(stretchedLskf), null);
34        // 어떤 슬롯을 사용하고있는지 기록. /data/system_de/0/spblob/<protector_id>.weaver 파일 생성
35        saveWeaverSlot(weaverSlot, protectorId, userId); 
36        // 메모리상으로 사용중인 슬롯관리 
37        mPasswordSlotManager.markSlotInUse(weaverSlot);
38        // SP를 보호하는 protectorSecret 생성 (spblob의 복호화 재료임) concat(stretchedLskf, hash(weaverSecret))
39        protectorSecret = transformUnderWeaverSecret(stretchedLskf, weaverSecret);
40    } else {
41        if (!credential.isNone()) {
42            gatekeeper.clearSecureUserId(fakeUserId(userId));
43            // stretchedLskf 로 GK용 키를 만들고 그걸로 enroll해서 등록한다. 나중에 verify에서 사용
44            // GateKeeper도 실패 누적 시 RETRY/타임아웃을 적용한다. 
45            response = gatekeeper.enroll(fakeUserId(userId), null, null,
46                    stretchedLskfToGkPassword(stretchedLskf));
47            pwd.passwordHandle = response.getPayload();
48            sid = sidFromPasswordHandle(pwd.passwordHandle);             
49        }
50        // concat(stretchedLskf, hash(secdiscardable))
51        protectorSecret = transformUnderSecdiscardable(stretchedLskf,
52                createSecdiscardable(protectorId, userId));
53        synchronizeGatekeeperFrpPassword(pwd, 0, userId);
54    }
55    if (!credential.isNone()) {
56        saveState(PASSWORD_DATA_NAME, pwd.toBytes(), protectorId, userId); // *.pwd
57        savePasswordMetrics(credential, sp, protectorId, userId);          // *.metrics
58    }
59    // sp를 protectorSecret(+@)로 암호화해서 spblob 파일로 저장
60    // *.spblob 파일 생성
61    createSyntheticPasswordBlob(protectorId, PROTECTOR_TYPE_LSKF_BASED, sp, protectorSecret, sid, userId);
62    syncState(userId);
63    return protectorId;
64}

1SyntheticPasswordManager.createLskfBasedProtector(...)
2  └─ gatekeeper.enroll(fakeUserId(userId), null, null, stretchedLskfToGkPassword(...))  [Java Binder]
3      └─ IGateKeeperService.aidl (framework ↔ native binder 인터페이스)
4          └─ gatekeeperd (C++ binder 서비스) → HAL 호출(AIDL/HIDL 중 AIDL 우선)
5              └─ android.hardware.gatekeeper.IGatekeeper/default (AIDL HAL)
6                  └─ android.hardware.gatekeeper-service.trusty (userspace HAL)
7                      └─ Trusty IPC → Trusty Gatekeeper TA(TEE)에서 enroll 실행

1SyntheticPasswordManager.weaverEnroll()
2   → IWeaver.write(slot, key, value)  // AIDL/HIDL Binder
3      → android.hardware.weaver*-service.citadel  // Pixel 벤더 HAL
4         → (Citadel/Titan/TEE의 TA)  // 실제 슬롯에 key/value 저장

 1private void createSyntheticPasswordBlob(long protectorId, byte protectorType,
 2        SyntheticPassword sp, byte[] protectorSecret, long sid, int userId) {
 3    final byte[] spSecret;
 4    spSecret = sp.getSyntheticPassword();
 5
 6    // sp 암호화.  alias: "synthetic_password_{protectorId}"
 7    byte[] content = createSpBlob(getProtectorKeyAlias(protectorId), spSecret, protectorSecret, sid);
 8
 9    byte version = sp.mVersion == SYNTHETIC_PASSWORD_VERSION_V3
10            ? SYNTHETIC_PASSWORD_VERSION_V3 : SYNTHETIC_PASSWORD_VERSION_V2;
11    // 이건 그냥 blob 바이트로 만들고 *.spblob 저장하는 로직
12    SyntheticPasswordBlob blob = SyntheticPasswordBlob.create(version, protectorType, content);
13    saveState(SP_BLOB_NAME, blob.toByte(), protectorId, userId);
14}
15
16// 별 내용은 없다. SyntheticPasswordCrypto 호출래퍼
17protected byte[] createSpBlob(String protectorKeyAlias, byte[] data, byte[] protectorSecret, long sid) {
18    return SyntheticPasswordCrypto.createBlob(protectorKeyAlias, data, protectorSecret, sid);
19}

 1public static byte[] createBlob(String protectorKeyAlias, byte[] data, byte[] protectorSecret, long sid) {
 2    // 바깥(Keystore)층 복호화 랜덤 AES-GCM 키 생성
 3    KeyGenerator keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES);
 4    keyGenerator.init(AES_GCM_KEY_SIZE * 8, new SecureRandom());
 5    SecretKey protectorKey = keyGenerator.generateKey();
 6    final KeyStore keyStore = getKeyStore();
 7
 8    // 복호화 용도(PURPOSE_DECRYPT)로만 사용 가능
 9    KeyProtection.Builder builder = new KeyProtection.Builder(KeyProperties.PURPOSE_DECRYPT)
10            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
11            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
12            .setCriticalToDeviceEncryption(true);
13
14    // 이 키는 인증된 사용자(HAT을 함께 제출)만 사용할 수 있다.
15    // sid에 해당하는 HAT이 살아있는 경우 && HAT이 발급된 15초 이내
16    builder.setUserAuthenticationRequired(true)
17        .setBoundToSpecificSecureUserId(sid)               // 15초
18        .setUserAuthenticationValidityDurationSeconds(USER_AUTHENTICATION_VALIDITY);
19
20    // 롤백 저항옵션이 있는 키와 아닌 키 생성. 기기마다 지원되지 않을 수 있기 때문에
21    final KeyProtection protNonRollbackResistant = builder.build();
22    builder.setRollbackResistant(true);
23    final KeyProtection protRollbackResistant = builder.build();
24    final KeyStore.SecretKeyEntry entry = new KeyStore.SecretKeyEntry(protectorKey);
25    try {
26        // 롤백저항 옵션으로 키 저장
27        // 과거 키를 얻어와서 keystore에 세팅하려할 때 방지해주는 기능임
28        // 이 기능이 없다면 HAT설정이 없는 과거 키를 복원하고 과거의 spblob파일을 복호화할 수 있게된다. 
29        // "synthetic_password_{protectorId}"
30        keyStore.setEntry(protectorKeyAlias, entry, protRollbackResistant);
31        Slog.i(TAG, "Using rollback-resistant key");
32    } catch (KeyStoreException e) {
33        // 예외 발생하면 NonRollbackResistant 로 진행
34        Slog.w(TAG, "Rollback-resistant keys unavailable.  Falling back to "
35                + "non-rollback-resistant key");
36        keyStore.setEntry(protectorKeyAlias, entry, protNonRollbackResistant);
37    }
38
39    // protectorSecret (credential + weaver/gk)으로 암호화
40    // PROTECTOR_SECRET_PERSONALIZATION = "application-id".getBytes();
41    byte[] intermediate = encrypt(protectorSecret, PROTECTOR_SECRET_PERSONALIZATION, data);
42    // protectorKey (keystore Key)로 암호화
43    return encrypt(protectorKey, intermediate);
44}

 1public AuthenticationResult unlockLskfBasedProtector(IGateKeeperService gatekeeper,
 2        long protectorId, @NonNull LockscreenCredential credential, int userId,
 3        ICheckCredentialProgressCallback progressCallback) {
 4    // 패스워드 파일 로드. 파일이 있는경우에만
 5    byte[] pwdDataBytes = loadState(PASSWORD_DATA_NAME, protectorId, userId);
 6    PasswordData pwd = PasswordData.fromBytes(pwdDataBytes);
 7    int storedType = pwd.credentialType;
 8    // 현재 들어온 credential과 pwd 파일에 저장된 내용이 같은지 확인
 9    if (!credential.checkAgainstStoredType(storedType)) {
10        Slogf.e(TAG, "Credential type mismatch: stored type is %s but provided type is %s",
11                LockPatternUtils.credentialTypeToString(storedType),
12                LockPatternUtils.credentialTypeToString(credential.getType()));
13        result.gkResponse = VerifyCredentialResponse.ERROR;
14        return result;
15    }
16    
17    // credential 키 스트레치. 여기서부터 이미지에 있는 순서도의 시작 
18    byte[] stretchedLskf = stretchLskf(credential, pwd);
19    final byte[] protectorSecret;
20    long sid = GateKeeper.INVALID_SECURE_USER_ID;
21    int weaverSlot = loadWeaverSlot(protectorId, userId);
22    if (weaverSlot != INVALID_WEAVER_SLOT) {
23        // Weaver 가 있는경우 위버로 검증 
24        result.usedWeaver = true;
25        final IWeaver weaver = getWeaverService();
26        result.gkResponse = weaverVerify(weaver, weaverSlot,
27                stretchedLskfToWeaverKey(stretchedLskf));
28        // 검증 후에는 stretchedLskf에 weaverSecret을 붙여서 protectorSecret을 만든다. 
29        // HAT처럼 보이는건 그냥 같은 필드를 돌려쓴것.
30        protectorSecret = transformUnderWeaverSecret(stretchedLskf,
31                result.gkResponse.getGatekeeperHAT());
32    } else {
33        // Weaver가 없는경우 GK를 통해서 검증
34        byte[] gkPassword = stretchedLskfToGkPassword(stretchedLskf);
35        GateKeeperResponse response;
36        // 이후 passwordHandle과 gkPassword 를 비교한다. 
37        response = gatekeeper.verifyChallenge(fakeUserId(userId), 0L,
38                pwd.passwordHandle, gkPassword);
39        result.gkResponse = VerifyCredentialResponse.OK;
40        if (response.getShouldReEnroll()) {
41            // GK 가 업데이트되면서 재발급받아야되는 경우 로직
42            // ... 
43        }
44        sid = sidFromPasswordHandle(pwd.passwordHandle);
45        byte[] secdiscardable = loadSecdiscardable(protectorId, userId);
46        protectorSecret = transformUnderSecdiscardable(stretchedLskf, secdiscardable);
47    }
48    
49    result.syntheticPassword = unwrapSyntheticPasswordBlob(protectorId,
50            PROTECTOR_TYPE_LSKF_BASED, protectorSecret, sid, userId);
51    // Perform verifyChallenge to refresh auth tokens for GK if user password exists.
52    result.gkResponse = verifyChallenge(gatekeeper, result.syntheticPassword, 0L, userId);
53    // Upgrade case: store the metrics if the device did not have stored metrics before, should
54    // only happen once on old protectors.
55    if (result.syntheticPassword != null && !credential.isNone()
56            && !hasPasswordMetrics(protectorId, userId)) {
57        savePasswordMetrics(credential, result.syntheticPassword, protectorId, userId);
58        syncState(userId);
59    }
60    return result;
61}

 1private VerifyCredentialResponse weaverVerify(IWeaver weaver, int slot, byte[] key) {
 2    final WeaverReadResponse readResponse;
 3    try {
 4        // Binder HAL을 통해 값을 읽어온다. 
 5        readResponse = weaver.read(slot, key);
 6    } catch (RemoteException e) {
 7        Slog.e(TAG, "weaver read failed, slot: " + slot, e);
 8        return VerifyCredentialResponse.ERROR;
 9    }
10    switch (readResponse.status) {
11        case WeaverReadStatus.OK:
12            // HAT 필드에 담기는건 weaverSecret
13            return new VerifyCredentialResponse.Builder()
14                                  .setGatekeeperHAT(readResponse.value)
15                                  .build();
16        case WeaverReadStatus.THROTTLE:
17            Slog.e(TAG, "weaver read failed (THROTTLE), slot: " + slot);
18            return responseFromTimeout(readResponse);
19        case WeaverReadStatus.INCORRECT_KEY:
20        case WeaverReadStatus.FAILED:
21        default:
22            return VerifyCredentialResponse.ERROR;
23    }
24}

 1bool GateKeeper::CreatePasswordHandle(SizedBuffer *password_handle_buffer, salt_t salt,
 2        secure_id_t user_id, uint64_t flags, uint8_t handle_version, const SizedBuffer & password) {
 3    // ... 
 4    
 5    // password_key를 가져옴. 
 6    GetPasswordKey(&password_key, &password_key_length);
 7    if (!password_key || password_key_length == 0) {
 8        return false;
 9    }
10    
11    // 여기에서 시그니쳐 계산함. 이때 password_key를 사용한다. 
12    ComputePasswordSignature(password_handle.signature, sizeof(password_handle.signature),
13            password_key, password_key_length, to_sign.get(), to_sign_size, salt);
14    uint8_t *ph_buffer = new(std::nothrow) uint8_t[sizeof(password_handle_t)];
15    if (ph_buffer == nullptr) return false;
16    *password_handle_buffer = { ph_buffer, sizeof(password_handle_t) };
17    memcpy(ph_buffer, &password_handle, sizeof(password_handle_t));
18    return true;
19}

 1// 패스워드 키를 가져오는 로직. 
 2void TrustyGateKeeper::GetPasswordKey(const uint8_t** password_key,
 3                                      uint32_t* length) {
 4    *password_key = const_cast<const uint8_t*>(password_key_.get());
 5    *length = HMAC_SHA_256_KEY_SIZE;
 6}
 7
 8// 시그니쳐 계산
 9void TrustyGateKeeper::ComputePasswordSignature(uint8_t* signature,
10                                                uint32_t signature_length,
11                                                const uint8_t* key,
12                                                uint32_t key_length,
13                                                const uint8_t* password,
14                                                uint32_t password_length,
15                                                salt_t salt) const {
16    uint8_t salted_password[GATEKEEPER_MAX_BUFFER_LENGTH];
17    assert(password_length + sizeof(salt) <= sizeof(salted_password));
18    memcpy(salted_password, &salt, sizeof(salt));
19    memcpy(salted_password + sizeof(salt), password, password_length);
20    ComputeSignature(signature, signature_length, key, key_length,
21                     salted_password, password_length + sizeof(salt));
22}
23
24void TrustyGateKeeper::ComputeSignature(uint8_t* signature,
25                                        uint32_t signature_length,
26                                        const uint8_t* key,
27                                        uint32_t key_length,
28                                        const uint8_t* message,
29                                        const uint32_t length) const {
30    uint8_t buf[HMAC_SHA_256_KEY_SIZE];
31    unsigned int buf_len;
32    HMAC(EVP_sha256(), key, key_length, message, length, buf, &buf_len);
33    size_t to_write = buf_len;
34    if (buf_len > signature_length)
35        to_write = signature_length;
36    memset(signature, 0, signature_length);
37    memcpy(signature, buf, to_write);
38}

1pwd = generate new password         # Bruteforce 위치
2token = scrypt(pwd, R, N, P, Salt)
3Application_id = token || Prehashed value
4key = SHA512("application_id" || application_id)
5
6# 복호화 성공 시 credential을 잘 선택했다는 의미이다. 
7AES_Decrypt(value_leaked_from_keymaster, key) 

1pwd = generate new password
2token = scrypt(pwd, R, N, P, Salt)
3key = SHA512("weaver_key" || token)
4
5# 메모리에서 유출된 키와 비교해서 같은지 확인
6Compare with leaked Weaver key

 1static class PasswordData {
 2    byte scryptN;
 3    byte scryptR;
 4    byte scryptP;
 5    public int passwordType;
 6    byte[] salt;
 7    public byte[] passwordHandle;   // password_handle_t 
 8};
 9struct __attribute__ ((__packed__)) password_handle_t {
10    uint8_t version;
11    secure_id_t user_id;      // uint64_t
12    uint64_t flags;
13    salt_t salt;              // uint64_t
14    uint8_t signature[32];
15    bool hardware_backed;
16};
17
18public AuthenticationResult unlockLskfBasedProtector(IGateKeeperService gatekeeper,
19        long protectorId, @NonNull LockscreenCredential credential, int userId,
20        ICheckCredentialProgressCallback progressCallback) {
21    // 패스워드 파일 로드. 파일이 있는경우에만
22    byte[] pwdDataBytes = loadState(PASSWORD_DATA_NAME, protectorId, userId);
23    PasswordData pwd = PasswordData.fromBytes(pwdDataBytes);
24 
25    // 여기에서 pwd.passwordHandle 이 expected_handle 값이다. 
26        response = gatekeeper.verifyChallenge(fakeUserId(userId), 0L,
27                pwd.passwordHandle, gkPassword);