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);
        }
});