android¶
1. 개요¶
헤카테 DID 서비스를 적용하기 위한 사용자용 Client 라이브러리 API입니다.
2. 객체 생성 및 콜백¶
객체 생성¶
객체 생성 후 HDMS(Hecate DID Management Server) 도메인을 설정합니다.
// DID 객체 생성 DIDManager dManager = DIDManager.getInstance(Context); // DID dManager.setDIDServerDomain("DID 서버 주소"); // 증명서 객체 생성 VCManager vcManager = VCManager.getInstance(Context); // 증명서CommonCallback.CCallback callback = new CommonCallback.CCallback() { @Override public void onFailed(final String code, final String resultMsg) { // "API 호출 후 해당 케이스가 성공이 아닌 경우" } @Override public void onSuccess(final String code, final String resultMsg) { // "API 호출 후 해당 케이스가 성공인 경우" } };
3. 개발환경 및 구성요소¶
빌드 환경¶
Android Studio 4.1.2
Min SDK Version 23
Complie SDK Version 30
Java Version 1.8
라이브러리 구성¶
HDIDClinetSDK_vX.X.X.aar
디펜던시¶
HDIDClinetSDK_vX.X.X.aar
Gson (com.google.code.gson)
Spongycastle(com.madgag.spongycastle)
Nimbusds(com.nimbusds)
Okhttp3 (com.squareup.okhttp3)
4. SDK 적용 가이드¶
AAR 복사¶
프로젝트 내 libs 폴더에 aar 파일 추가
Build.gradle dependency 추가¶
// 없으면 추가합니다. repositories { flatDir{ dirs 'libs' } } dependencies { implementation fileTree(dir: "libs", include: ["*.jar"]) implementation group: 'com.google.code.gson', name: 'gson', version: '2.8.5' // gson implementation 'org.bitcoinj:bitcoinj-core:0.15.6' // base58 // Zxing QR/Bar Code Reader implementation group: 'com.journeyapps', name: 'zxing-android-embedded', version: '3.6.0' // Encrypted SharedPreference implementation 'androidx.security:security-crypto:1.0.0-rc01' implementation 'com.squareup.okhttp3:okhttp:3.10.0' implementation 'com.madgag.spongycastle:prov:1.58.0.0' implementation("com.nimbusds:nimbus-jose-jwt:8.19") { exclude module: 'jcip-annotations' } // DID AAR 적용 implementation name: 'HDIDClientSDK_vX.X.X', ext: 'aar' }
5. DID API¶
getInstance ( 객체 생성 )¶
-
DIDManager.getInstance(Context)
DID 객체를 생성하여 사용합니다.
객체는 싱글톤으로 사용되며 생성후 DID 서버 도메인 설정을 수행해야 합니다.
- Parameters
Context (Context) – 컨텍스트 객체
Example:
DIDManager dManager = DIDManager.getInstance(getApplicationContext());
setDIDServerDomain ( DID 서버 설정 )¶
-
DIDManager.getInstance()).setDIDServerDomain(Url)
DID 서버 도메인을 설정합니다.
- Parameters
Url (String) – DID 서버 주소
Example:
DIDManager dManager = DIDManager.getInstance(getApplicationContext()); dManager.setDIDServerDomain("http://192.168.0.1:9999");
existDID ( DID 유무 확인 )¶
-
DIDManager.getInstance().existDID()
DID 발급 유무를 확인합니다.
- Returns
발급 유무
- Return type
Boolean
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); // DID 유무를 체크한다. if (!dManager.existDID()) { // 발급받은 DID 무 }else{ // 발급받은 DID 유 }
registDID ( DID 발급 )¶
-
DIDManager.getInstance().registDID(userHash, jsonOther, authType, secretHash, didName, CommonCallback)
DID 발급 요청을 수행한다
- Parameters
userHash (String) – 사용자 식별 정보
jsonOther (String) – 사용자 기타 정보 (없을경우 Dummy 설)
authType (String) – “01”: Pin, “02”: 지문
secretHash (String) – 비밀번호 Hash값
didName (String) – DID 별명으로 설정되는 값
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
jsonOther 구성
Key
Type
Description
name
String
이름
email
String
이메일
birthday
String
생년월일
mobile
String
휴대폰번호
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); // DID 발급 dManager.registDID(memberInfo, jsonOther, authType, pinHash, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 발급 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 발급 성공 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
getDIDInfo ( DID 정보 조회 )¶
-
DIDManager.getInstance().getDIDInfo()
DID 정보를 조회 한다.
- Returns
DID 정보 값
- Return type
String
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID 정보 :" + dManager.getDIDInfo());
getDIDName ( DID 별명 조회 )¶
-
DIDManager.getInstance().getDIDName()
DID 발급시 설정했던 별명값을 조회 한다.
- Returns
DID 별명 값
- Return type
String
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID Name : " + dManager.getDIDName());
getDIDList ( DID 리스트 조회 )¶
-
DIDManager.getInstance().getDIDList()
발급받은 DID 리스트를 조회 한다.
- Returns
발급받은 DID 리스트
- Return type
JSONArray
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID Name : " + dManager.getDIDList().toString());
unRegisterDID ( DID 폐기 )¶
-
DIDManager.getInstance().unRegistDID( unRegType, authType, secretHash, CommonCallback )
DID를 폐기한다.
- Parameters
unRegType (String) – 폐기 주체
authType (String) – “01”: Pin, “02”: 지문
secretHash (String) – 비밀번호 Hash값
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
unRegType
Value
Description
0
사용자 폐기
1
발급기관 폐기
2
검증기관 폐기
3
검증자 폐기
Example:
// 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); // 사용자 DID 폐기 dManager.unRegistDID("0", authType, secretHash, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 폐기 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 폐기 성공 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
deleteDID ( DID 로컬 삭제 )¶
-
DIDManager.getInstance().deleteDID()
로컬에 발급 받은 DID를 삭제한다.
사용자가 PIN번호를 분실했을 경우 DID를 삭제하는 용도로 사용
Example:
[[DIDManager getInstance()] deleteDID];
changePin ( 핀번호 변경 )¶
-
DIDManager.getInstance().changePin(oldPinHash, newPinHash)
개인키를 암호화한 PIN번호를 변경한다.
- Parameters
oldPinHash (String) – 이전 PIN번호
newPinHash (String) – 신규 PIN번호
- Returns
true: 변경 성공, false: 변경 실패
- Return type
Boolean
Example:
if (DIDManager.getInstance().changePin(oldPinHash, newPinHash)) { // PIN번호 변경 성공 }else{ // PIN번호 변경 실패 }
6. VC API¶
getInstance ( 객체 생성 )¶
-
VCManager.getInstance(Context)
DID 객체를 생성하여 사용합니다.
객체는 싱글톤으로 사용되며 생성후 DID 서버 도메인 설정을 수행해야 합니다.
Example:
VCManager vcManager = VCManager.getInstance(getApplicationContext());
getIssuer ( 발급 가능 기관 조회 )¶
-
VCManager.getInstance().getIssuer(CommonCallback)
증명서(VC) 발급 가능한 발급기관 목록을 요청한다.
조회 성공시 메시지에 발급기관 목록이 전달된다.
발급기관 목록
Key
Type
Description
did
String
발급기관 DID
name
String
발급기관 이름
- Parameters
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vcManager = VCManager.getInstance(getApplicationContext()); vcManager.getIssuer( new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 조회 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 조회 성공 // code : 0000, resultMsg : JSONArray [{"name":"", "did":""}] Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
getIssuerVCType ( 발급 가능한 VC 타입 조회 )¶
-
VCManager.getInstance().getIssuerVCType(issuerDID, CommonCallback)
발급기관에서 발급 가능한 증명서(VC) 타입을 조회한다.
조회 성공시 메시지에 발급 가능한 증명서 타입 목록이 전달된다.
증명서타입 목록
Key
Type
Description
issueType
String
발급기관 DID
craimFormat
String
발급기관 이름
name
String
발급 가능 증명서 이름
type
String
발급 가능 증명서 타입
- Parameters
issuerDID (String) – 발급기관 DID, getIssuer에서 조회한 발급기관 정보 사용
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vcManager = VCManager.getInstance(getApplicationContext()); vcManager.getIssuerVCType("ISSUER DID", new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 조회 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 조회 성공 // code : 0000 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
existVC ( VC 유무 확인 )¶
-
VCManager.getInstance().existVC()
증명서(VC) 발급 유무를 확인합니다.
- Returns
true: 있음, false: 없음
- Return type
Boolean
Example:
if (!VCManager.getInstance().existVC()) { // 발급받은 VC 무 }else{ // 발급받은 VC 유 }
registVC ( VC 발급 )¶
-
VCManager.getInstance().registVC(issuerDID, vcType, CommonCallback)
증명서(VC) 발급 요청을 수행한다
- Parameters
issuerDID (String) – 기관 DID
vcType (String) – 증명서 타입
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vcManager = VCManager.getInstance(getApplicationContext()); vcManager.registVC( issuerDID, vcTYPE, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 발급 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 발급 성공 // code : 0000 resultMsg : 증명서 발급에 성공하였습니다. Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
getVCStatus ( VC 상태 조회 )¶
-
VCManager.getInstance().getVCStatus(vcId, CommonCallback)
증명서(VC) 상태를 조회한다.
증명서 상태
Code
Description
0000
정상 인증서
8003
만료or폐기 인증서
- Parameters
vcId (String) – 증명서 아이디
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); vManager.getVCStatus( vcID, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 상태 조회 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 조회 성공 // code : 0000(정상), 8003(만료, 폐기) Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });
getALLVCList ( VC 리스트 조회 )¶
-
VCManager.getInstance().getALLVCList()
발급받은 증명서(VC) 리스트를 조회 한다.
- Returns
발급받은 증명서 리스트
- Return type
VCredential JSONObject
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. JSONObject vcList = vManager.getALLVCList(); Log.d("TAG", "발급받은 증명서 리스트 : " + vcList.toString());
getVCDetailInfo ( VC 상세 조회 )¶
-
VCManager.getInstance().getVCDetailInfo(vcId)
증명서(VC) 상세정보를 조회 한다.
- Parameters
vcId (String) – 증명서 아이디
- Returns
발급받은 증명서 상세내역
- Return type
VCredential
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. VCredential vc = vManager.getVCDetailInfo(vcID); Log.d("TAG", "발급받은 증명서 : " + vc.toString()); Log.d("TAG", "증명서 발급기관: " + vc.getIssuer());
showVC ( VC 전시 )¶
-
VCManager.getInstance().showVC(vcId, submitPurpose, crtfcTy, verifyTy, authType, secretHash, CommonCallback)
증명서(VC) 전시에 필요한 정보를 요청한다.
QR데이터 요청
호출전 증명서(VC) 상태조회 체크
- Parameters
vcId (String) – 증명서 아이디
submitPurpose (String) – 요청 정보 메시지 (“사용자 VP 검증 요청”)
crtfcTy (String) – 비밀번호 타입 ( 0 = PIN, 1 = 생체인증 )
verifyTy (String) – ATA
authType (String) – “01”: Pin, “02”: 지문
secretHash (String) – 비밀번호 Hash값
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); vManager.showVC( vcID, submitPurpose, crtfcTy, verifyTy, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 증명서 전시 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 조회 성공 // code : 0000(정상), Log.d("TAG", "code : " + code + "\nQR Data : " + resultMsg); } });
unRegistVC ( VC 폐기 )¶
-
VCManager.getInstance().unRegistVC(vcId, authType, secretHash, CommonCallback)
증명서(VC) 를 폐기한다.
- Parameters
vcId (String) – 증명서 아이디
authType (String) – “01”: Pin, “02”: 지문
secretHash (String) – 비밀번호 Hash값
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); vManager.unRegistVC( vcID, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 폐기 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 폐기 성공 // code : 0000(정상) Log.d("TAG", "code : " + code + "\n resultMsg : " + resultMsg); } });
getVCRegistHistory ( VC 발급 이력 조회 )¶
-
VCManager.getInstance().getVCRegistHistory(CommonCallback)
증명서(VC) 발급 이력을 조회한다.
조회 성공시 메시지에 발급 이력 목록이 전달된다.
발급이력 Object
Key
Type
Description
issuerDID
String
발급기관 DID
autoConfirm
String
자동 승인 여부
name
String
증명서 이름
holderDID
String
사용자 DID
id
String
증명서 아이디
type
String
증명서 타입
status
String
증명서 상태
registDate
String
등록일
- Parameters
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); vManager.getVCRegistHistory( new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 발급 이력 조회 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 발급 이력 조회 성공 // code : 0000(정상), resultMsg : 발급이력 Log.d("TAG", "code : " + code + "\n resultMsg : " + resultMsg); } });
getVCType ( VC 타입 확인 )¶
-
VCManager.getInstance().getVCType(vcID)
증명서(VC) ID로 증명서 타입을 조회한다.
- Parameters
vcId (String) – 증명서 아이디
- Returns
증명서 타입
- Return type
String
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. String vcType = vManager.getVCType(vcID); Log.d("TAG", "증명서 타입: " + vcType.toString());
getSavedVCTypeList ( VC 타입리스트 조회 )¶
-
VCManager.getInstance().getSavedVCTypeList()
단말에 저장된 증명서(VC)들의 타입을 조회한다.
- Returns
증명서 타입
- Return type
ArrayList
Example:
// 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. ArrayList vcType = vManager.getSavedVCTypeList();
authMulti ( 멀티 인증 요청 )¶
-
VCManager.getInstance().authMulti(certType, certNumber, vcId, authType, secretHash, CommonCallback)
멀티 인증 요청을 수행한다.
- Parameters
certType (String) – 인증타입 (“qr”)
certNumber (String) – 인증번호 (6자리)
vcId (String) – 증명서 아이디
authType (String) – “01”: Pin, “02”: 지문
secretHash (String) – 비밀번호 Hash값
callback (CommonCallback) – 결과 응답을 받기 위한 콜백함수
Example:
// 객체 생성 VCManager vcManager = VCManager.getInstance(getApplicationContext()); vcManager.authMulti( "qr", "123456", vcId, vcTYPE, authType, secretHash, new CommonCallback.CCallback() { @Override public void onFailed(String code, String resultMsg) { // 멀티인증 실패 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } @Override public void onSuccess(String code, String resultMsg) { // 멀티인증 성공 Log.d("TAG", "code : " + code + "\nresultMsg : " + resultMsg); } });