======================== android ======================== 1. 개요 ========= 헤카테 DID 서비스를 적용하기 위한 사용자용 Client 라이브러리 API입니다. 2. 객체 생성 및 콜백 ======================= 객체 생성 --------------------------- 객체 생성 후 HDMS(Hecate DID Management Server) 도메인을 설정합니다. .. code-block:: java // DID 객체 생성 DIDManager dManager = DIDManager.getInstance(Context); // DID dManager.setDIDServerDomain("DID 서버 주소"); // 증명서 객체 생성 VCManager vcManager = VCManager.getInstance(Context); // 증명서 CommonCallback --------------------------- .. code-block:: java 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 추가 --------------------------- .. code-block:: groovy // 없으면 추가합니다. 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 ( 객체 생성 ) --------------------------- .. c:function:: DIDManager.getInstance(Context) * DID 객체를 생성하여 사용합니다. * 객체는 싱글톤으로 사용되며 생성후 DID 서버 도메인 설정을 수행해야 합니다. :param Context Context: 컨텍스트 객체 Example: .. code-block:: java DIDManager dManager = DIDManager.getInstance(getApplicationContext()); setDIDServerDomain ( DID 서버 설정 ) -------------------------- .. c:function:: DIDManager.getInstance()).setDIDServerDomain(Url) * DID 서버 도메인을 설정합니다. :param String Url: DID 서버 주소 Example: .. code-block:: java DIDManager dManager = DIDManager.getInstance(getApplicationContext()); dManager.setDIDServerDomain("http://192.168.0.1:9999"); existDID ( DID 유무 확인 ) -------------------------- .. c:function:: DIDManager.getInstance().existDID() * DID 발급 유무를 확인합니다. :returns: 발급 유무 :rtype: Boolean Example: .. code-block:: java // 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); // DID 유무를 체크한다. if (!dManager.existDID()) { // 발급받은 DID 무 }else{ // 발급받은 DID 유 } registDID ( DID 발급 ) -------------------------- .. c:function:: DIDManager.getInstance().registDID(userHash, jsonOther, authType, secretHash, didName, CommonCallback) * DID 발급 요청을 수행한다 :param String userHash: 사용자 식별 정보 :param String jsonOther: 사용자 기타 정보 (없을경우 Dummy 설) :param String authType: "01": Pin, "02": 지문 :param String secretHash: 비밀번호 Hash값 :param String didName: DID 별명으로 설정되는 값 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 * jsonOther 구성 ====================== ========== ============= Key Type Description ====================== ========== ============= name String 이름 email String 이메일 birthday String 생년월일 mobile String 휴대폰번호 ====================== ========== ============= Example: .. code-block:: java // 객체 생성 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 정보 조회 ) -------------------------- .. c:function:: DIDManager.getInstance().getDIDInfo() * DID 정보를 조회 한다. :returns: DID 정보 값 :rtype: String Example: .. code-block:: java // 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID 정보 :" + dManager.getDIDInfo()); getDIDName ( DID 별명 조회 ) -------------------------- .. c:function:: DIDManager.getInstance().getDIDName() * DID 발급시 설정했던 별명값을 조회 한다. :returns: DID 별명 값 :rtype: String Example: .. code-block:: java // 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID Name : " + dManager.getDIDName()); getDIDList ( DID 리스트 조회 ) -------------------------- .. c:function:: DIDManager.getInstance().getDIDList() * 발급받은 DID 리스트를 조회 한다. :returns: 발급받은 DID 리스트 :rtype: JSONArray Example: .. code-block:: java // 객체 생성 DIDManager dManager = DIDManager.getInstance(getApplicationContext()); Log.d( "TAG", "DID Name : " + dManager.getDIDList().toString()); unRegisterDID ( DID 폐기 ) -------------------------- .. c:function:: DIDManager.getInstance().unRegistDID( unRegType, authType, secretHash, CommonCallback ) * DID를 폐기한다. :param String unRegType: 폐기 주체 :param String authType: "01": Pin, "02": 지문 :param String secretHash: 비밀번호 Hash값 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 * unRegType ====================== ============= Value Description ====================== ============= 0 사용자 폐기 1 발급기관 폐기 2 검증기관 폐기 3 검증자 폐기 ====================== ============= Example: .. code-block:: java // 객체 생성 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 로컬 삭제 ) -------------------------- .. c:function:: DIDManager.getInstance().deleteDID() * 로컬에 발급 받은 DID를 삭제한다. * 사용자가 PIN번호를 분실했을 경우 DID를 삭제하는 용도로 사용 Example: .. code-block:: [[DIDManager getInstance()] deleteDID]; changePin ( 핀번호 변경 ) -------------------------- .. c:function:: DIDManager.getInstance().changePin(oldPinHash, newPinHash) * 개인키를 암호화한 PIN번호를 변경한다. :param String oldPinHash: 이전 PIN번호 :param String newPinHash: 신규 PIN번호 :returns: true: 변경 성공, false: 변경 실패 :rtype: Boolean Example: .. code-block:: java if (DIDManager.getInstance().changePin(oldPinHash, newPinHash)) { // PIN번호 변경 성공 }else{ // PIN번호 변경 실패 } 6. VC API ======================= getInstance ( 객체 생성 ) --------------------------- .. c:function:: VCManager.getInstance(Context) * DID 객체를 생성하여 사용합니다. * 객체는 싱글톤으로 사용되며 생성후 DID 서버 도메인 설정을 수행해야 합니다. Example: .. code-block:: java VCManager vcManager = VCManager.getInstance(getApplicationContext()); getIssuer ( 발급 가능 기관 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getIssuer(CommonCallback) * 증명서(VC) 발급 가능한 발급기관 목록을 요청한다. * 조회 성공시 메시지에 발급기관 목록이 전달된다. * 발급기관 목록 ====================== ========== ============= Key Type Description ====================== ========== ============= did String 발급기관 DID name String 발급기관 이름 ====================== ========== ============= :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 타입 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getIssuerVCType(issuerDID, CommonCallback) * 발급기관에서 발급 가능한 증명서(VC) 타입을 조회한다. * 조회 성공시 메시지에 발급 가능한 증명서 타입 목록이 전달된다. * 증명서타입 목록 ====================== ========== ================== Key Type Description ====================== ========== ================== issueType String 발급기관 DID craimFormat String 발급기관 이름 name String 발급 가능 증명서 이름 type String 발급 가능 증명서 타입 ====================== ========== ================== :param String issuerDID: 발급기관 DID, getIssuer에서 조회한 발급기관 정보 사용 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 유무 확인 ) -------------------------- .. c:function:: VCManager.getInstance().existVC() * 증명서(VC) 발급 유무를 확인합니다. :returns: true: 있음, false: 없음 :rtype: Boolean Example: .. code-block:: java if (!VCManager.getInstance().existVC()) { // 발급받은 VC 무 }else{ // 발급받은 VC 유 } registVC ( VC 발급 ) -------------------------- .. c:function:: VCManager.getInstance().registVC(issuerDID, vcType, CommonCallback) * 증명서(VC) 발급 요청을 수행한다 :param String issuerDID: 기관 DID :param String vcType: 증명서 타입 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 상태 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getVCStatus(vcId, CommonCallback) * 증명서(VC) 상태를 조회한다. * 증명서 상태 ====================== ============= Code Description ====================== ============= 0000 정상 인증서 8003 만료or폐기 인증서 ====================== ============= :param String vcId: 증명서 아이디 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 리스트 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getALLVCList() * 발급받은 증명서(VC) 리스트를 조회 한다. :returns: 발급받은 증명서 리스트 :rtype: VCredential JSONObject Example: .. code-block:: java // 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. JSONObject vcList = vManager.getALLVCList(); Log.d("TAG", "발급받은 증명서 리스트 : " + vcList.toString()); getVCDetailInfo ( VC 상세 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getVCDetailInfo(vcId) * 증명서(VC) 상세정보를 조회 한다. :param String vcId: 증명서 아이디 :returns: 발급받은 증명서 상세내역 :rtype: VCredential Example: .. code-block:: java // 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. VCredential vc = vManager.getVCDetailInfo(vcID); Log.d("TAG", "발급받은 증명서 : " + vc.toString()); Log.d("TAG", "증명서 발급기관: " + vc.getIssuer()); showVC ( VC 전시 ) -------------------------- .. c:function:: VCManager.getInstance().showVC(vcId, submitPurpose, crtfcTy, verifyTy, authType, secretHash, CommonCallback) * 증명서(VC) 전시에 필요한 정보를 요청한다. * QR데이터 요청 * 호출전 증명서(VC) 상태조회 체크 :param String vcId: 증명서 아이디 :param String submitPurpose: 요청 정보 메시지 ("사용자 VP 검증 요청") :param String crtfcTy: 비밀번호 타입 ( 0 = PIN, 1 = 생체인증 ) :param String verifyTy: ATA :param String authType: "01": Pin, "02": 지문 :param String secretHash: 비밀번호 Hash값 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 폐기 ) -------------------------- .. c:function:: VCManager.getInstance().unRegistVC(vcId, authType, secretHash, CommonCallback) * 증명서(VC) 를 폐기한다. :param String vcId: 증명서 아이디 :param String authType: "01": Pin, "02": 지문 :param String secretHash: 비밀번호 Hash값 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 발급 이력 조회 ) -------------------------- .. c:function:: 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 등록일 ====================== ========== ============= :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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 타입 확인 ) -------------------------- .. c:function:: VCManager.getInstance().getVCType(vcID) * 증명서(VC) ID로 증명서 타입을 조회한다. :param String vcId: 증명서 아이디 :returns: 증명서 타입 :rtype: String Example: .. code-block:: java // 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. String vcType = vManager.getVCType(vcID); Log.d("TAG", "증명서 타입: " + vcType.toString()); getSavedVCTypeList ( VC 타입리스트 조회 ) -------------------------- .. c:function:: VCManager.getInstance().getSavedVCTypeList() * 단말에 저장된 증명서(VC)들의 타입을 조회한다. :returns: 증명서 타입 :rtype: ArrayList Example: .. code-block:: java // 객체 생성 VCManager vManager = VCManager.getInstance(getApplicationContext()); // 발급받은 증명서를 조회한다. ArrayList vcType = vManager.getSavedVCTypeList(); authMulti ( 멀티 인증 요청 ) -------------------------- .. c:function:: VCManager.getInstance().authMulti(certType, certNumber, vcId, authType, secretHash, CommonCallback) * 멀티 인증 요청을 수행한다. :param String certType: 인증타입 ("qr") :param String certNumber: 인증번호 (6자리) :param String vcId: 증명서 아이디 :param String authType: "01": Pin, "02": 지문 :param String secretHash: 비밀번호 Hash값 :param CommonCallback callback: 결과 응답을 받기 위한 콜백함수 Example: .. code-block:: java // 객체 생성 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); } });