NPKI(MagicXsign) 디바이스API 가이드 프로그램

NPKI 가이드 프로그램(MagicXSign)은 모바일 디바이스 API 실행환경을 활용하여 하이브리드 앱을 개발 시 참고 및 활용될 수 있도록 구현 된 전자정부 디바이스 API에 대한 가이드 앱으로써, 모바일 스마트 디바이스의 NPKI 관련 기능을 JavaScript 기반으로 구성 된 NPKI DeviceAPI 를 통하여 이용할 수 있도록 지원한다.

또한, 전자정부 표준프레임워크 기반의 웹 서버 어플리케이션과 연계하여 모바일기기에 저장된 인증서를 정부에서 제공하는 인증을 이용하여 인증서 인증을 하고 결과를 서버에 저장하며 인증서 인증 결과 로그를 조회하는 기능으로 구성되어 있다.

본 가이드 프로그램 에서는 NPKI 기능을 가이드 할 수 있도록 모바일 기기 인증서 선택/인증하기 , 인증 로그 정보 보기 기능을 제공하고 있으며 웹 서버 어플리케이션에 표준 보안 API 를 적용하여 인증서 정보를 확인 할 수 있는 기능으로 구현되었다.

NPKI MagicXSign Library

NPKI 디바이스 API 구성 라이브러 중 아래 코드 라이브러리는 보안 Native Module로서 라이선스를 가지고 있다. 그에 따라, 표에 기재된 라이브러리의 경우 NPKI 디바이스 API 배포 시 배포 리소스에서 제외하여 배포되고, 해당 모듈을 적용하여, 테스트 및 실제 구현을 진행하고자 하는 정부기관이나, 업체에서는 아래 기술협력 업체로 연락 문의해야 한다.

전자정부 보안표준 API를 사용하기 위해서는 별도로 보안표준 API를 신청하여야 하며, 이는 행정전자서명 인증관리센터(http://www.gpki.go.kr 새 창 열림)에서 주관하고 있다.

서비스 신청 방법은 다음과 같다.

▶ 표준 API 보급관리시스템 접속이 가능한 경우
ㅇ [표준API보급관리시스템] 에서 웹으로 API신청(공문, 구성도 첨부)
ㅇ 서비스 URL : http://api.gpki.go.kr 새 창 열림
공문은 한국지역정보개발원 - 지역정보센터 - 정보기반과로 보내주면 된다.
공문 내용은 업무시스템명, 담당자, 연락처 및 표준 API 를 신청한다는 내용.
- 해당서비스는 행정망에서만 이용가능함 -

▶ 외부망 (http://api.gpki.go.kr 새 창 열림 접속 불가) 일경우
ㅇ 행정전자서명 인증관리센터(http://www.gpki.go.kr 새 창 열림) 사이트의 “자료실-인증서신청관련양식-7.표준 API 신청방법 및 표준 API 신청서”에 있는 표준 API 신청서를 작성하셔서 공문과 함께 신청서를 보내주면 된다.
공문 수신처 : 한국지역정보개발원 - 지역정보센터 - 정보기반과
공문 내용은 업무시스템명, 담당자, 연락처 및 표준 API 를 신청한다는 내용.

기타 자세한 정보 확인 및 문의는 행정전자서명 인증관리센터(http://www.gpki.go.kr 새 창 열림)를 참고한다.

N/A

폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,
Res/xml/config.xml에서 <access origin=“” />에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.

NPKI 디바이스API 가이드 프로그램은 크게 모바일 기기내의 인증서를 선택 및 서명 데이터를 만들어 웹 서버 어플리케이션으로 전송하여 인증서 인증하는 기능과 인증서 인증된 로그 데이터를 조회하는 기능으로 구성되어 있다.(관련기능 부분참조)

MagicXSign API DOC

• MagicXSign 을 사용하기 위해 초기화를 한다.
  

window.plugins.magicxsign.init(var Flag)

window.plugins.magicxsign.init("false");
window.plugins.magicxsign.init("true");

• 단말의 인증서를 jsonString 형식으로 맞추어서 읽어온다.

window.plugins.magicxsign.getcertlist( success return , fail return, jsonString);

• 조회 할 인증서의 정보

var setDefine = ["oidname","issuer","name","subjdn","start","end"];
window.plugins.magicxsign.getcertlist(getcertlistSuccess, getcertlistFail, JSON.stringify(setDefine));

• 서명 데이터를 생성한다.

window.plugins.magicxsing.makesign(success return, fail return, jsonString);

var setDefine = {};
setDefine["plaintext"] = encodeURIComplnent(MagicXSign_makeQueryString(form)));
setDefine["url"] = sURL;
setDefine["certindex"] = document.getElementById("xsigncertindex").value;
setDefine["certpassword"] = document.getElementById("xsigncertpassword").value;
window.plugins.magicxsign.makesign(makesign_ok, makesign_fail, JSON.stringify(setDefine));

• PKI

public String verifyCert(PKIAndroidAPIVO pkiVo) throws Exception {
    // API 초기화
    GpkiApi.init("C:/libgpkiapi_jni/conf");
    String sign;
    sign = pkiVo.getSign();	
    return verify(Base64.decode(sign));   	
}

private String verify(final byte[] bSignedData)  {
    String sClientName = "";
    try {
        // 서명값을 검증
        SignedData signedData = null;
        signedData = new SignedData();			
        signedData.verify(bSignedData);		
			
        // 서명자의 인증서 검증을 위해서 서버의 서명용 인증서 획득
        X509Certificate clientCert = null;
        clientCert = signedData.getSignerCert(0);
	
        // 인증서 검증
        CertPathValidator certPathValiditor = null;
        certPathValiditor = new CertPathValidator("C:/libgpkiapi_jni/conf/gpkiapi.conf");
			
        // 신뢰하는 최상위 인증서 추가
        X509Certificate rootCertRsa = null;
        rootCertRsa = Disk.readCert("C:/libgpkiapi_jni/conf/root-rsa2.der");
        X509Certificate rootCertRsaSha = null;
        rootCertRsaSha = Disk.readCert("C:/libgpkiapi_jni/conf/root-rsa-sha2.der");
        certPathValiditor.addTrustedRootCert(rootCertRsa);
        certPathValiditor.addTrustedRootCert(rootCertRsaSha);			
			
        // 클라이언트의 인증서 검증 범위 설정
        certPathValiditor.setVerifyRange(CertPathValidator.CERT_VERIFY_FULL_PATH);
			
        // 클라이언트의 인증서 폐지여부 확인 설정 (CRL/ARL 검증 설정함)
        certPathValiditor.setRevokationCheck(CertPathValidator.REVOKE_CHECK_ARL | CertPathValidator.REVOKE_CHECK_CRL);
			
        // 인증서 검증 요청
        certPathValiditor.validate(CertPathValidator.CERT_SIGN, clientCert);	
					
        sClientName = clientCert.getSubjectDN();			
			
			
    } catch (Exception e) {			
        sClientName = "";
    }
    return sClientName;
}

NPKI 디바이스API 가이드 프로그램에서 제공하는 모바일 디바이스의 NPKI 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

public void onCreate(Bundle savedInstanceState)
{
    super.onCreate(savedInstanceState);

    //MagicXsign 을 PhoneGap Plugin 에서 사용하기 위함
    PhoneGapPlugin.init(this);
	
    super.clearCache();
    super.loadUrl("file:///android_asset/www/intro.html");
}
<code>

=== res/xml/plugins.xml ===

<code xml>
    <!--전자정부 Interface 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="EgovInterfacePlugin" value="kr.go.egovframework.hyb.plugin.EgovInterfacePlugin" />
    <!--전자정부 NPKI 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="MagicXSignPlugin" value="com.dreamsecurity.magicxsign.PhoneGapPlugin" />

    <!--전자정부 Interface 디바이스 API에서 사용하기 위한 서버경로 설정-->
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
	<string name="SERVER_URL">http://192.168.100.222:8080/DeviceAPIGuideTotal_Web_V1.7.1</string>
    </resources>

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<dependency>
	<groupId>egovframework.com.cmm.uat</groupId>
	<artifactId>libgpkiapi_jni</artifactId>
	<version>1.4.0.0</version>
</dependency>

<sqlMap resource="egovframework/sqlmap/hyb/add/dvc/EgovPKIAndroidAPIGuide_SQL_[DB명].xml"/>

• 표준 보안 API 설정

NPKI 디바이스 API 가이드는 크게 모바일 기기 인증서 선택/인증하기 , 인증 로그 정보 보기 기능으로 구성되어있다.

디바이스 API를 통해 모바일 기기에 저장된 인증서 리스트를 조회하고, 리스트에서 선택 한 인증서로 인증서 인증을 한다.

디바이스 API 내의 인증서 리스트 조회 함수를 사용하는 JavaScript 코드를 통해 인증서 리스트를 조회 하고, 서명 데이터를 만드는 JavaScript 함수를 사용하여 서명 한다.

// 인증서 리스트 조회
function fn_egov_go_certlist() {
	console.log('DeviceAPIGuide fn_egov_go_certlist');
	var setDefine = ["oidname","issuer","name","subjdn","start","end"];
	// setDefine 에 지정된 리스트로 데이타를 요청한다
	window.plugins.magicxsign.getcertlist(fn_egov_getcertlistSuccess,  fn_egov_getcertlistFail, JSON.stringify(setDefine));
}

// 인증서 서명
function fn_egov_login_member() {
	var setDefine = {};
	setDefine["plaintext"]=encodeURIComponent("usrId=&password=&name=");		// form Data
	setDefine["certindex"]=document.getElementById("xsigncertindex").value;		// 선택된 인증서 INDEX
	setDefine["certpassword"]=$("#loginPasswd").val();				// 선택된 인증서 Password
	// setDefine 에 지정된 리스트로 인증서 서명을 한다.
	window.plugins.magicxsign.makesign(fn_egov_makesign_ok, fn_egov_makesign_fail, JSON.stringify(setDefine));
}

// 인증서 서명 데이터 서버로 인증 요청
function fn_egov_makesign_ok(arg)
{
    console.log('DeviceAPIGuide fn_egov_makesign_ok Success');
    var jsonobj = JSON.parse(arg);
	
    // jsonobj.sign에서 서면 값, jsonobj.vidRandom에서 본인확인을 위한 VID Random값을 가져올 수 있다.
    var signedData = jsonobj.sign;	
    
    var url = "/pki/xml/addPKIInfo.do";
    var acceptType = "xml";
    var params = {uuid :  device.uuid,			
		  sign: signedData,
		  entrprsSeCode: 'PKI01'};
    alert('Http Method:POST\nacceptType:'+ acceptType + '\n요청데이터:' + JSON.stringify(params));
	
    // get the data from server
    window.plugins.EgovInterface.post(url,acceptType, params, function(xmldata) {		
        console.log('DeviceAPIGuide fn_egov_makesign_ok request Complete');
        alert('응답데이터:' + xmldata)
        if($(xmldata).find("resultState").text() == "OK"){				
            window.history.go(-2);
        }else{
            jAlert($(xmldata).find("resultMessage").text(), '오류', 'c');
        }
    });	
	
    document.getElementById("innerhtmlArea").innerHTML= "SendResult : <br>"+sResult+"<br><br>";
}

관련화면 및 수행매뉴얼

인증서 리스트	인증서 인증

인증서 리스트 화면에서 인증 할 인증서를 선택하고 인증서 인증 화면에서 PASSWD 항목에 패스워드를 입력 후 “인증 확인” 버튼을 클릭한다.
단, PASSWD 항목에서 validation을 확인하고, 조건이 불충분 할 경우 오류 메시지가 출력된다.

인증 확인 : 인증서 인증을 하기 위해서 PASSWD 항목에 인증서 패스워드를 입력 후 “인증 확인” 버튼을 클릭한다.
Back 버튼 : NPKI 디바이스 API 가이드 프로그램 메뉴 화면 또는 인증서 리스트 화면으로 이동한다.

웹 서버 어플리케이션으로 부터 인증서 인증 결과 로그를 조회한다.

function fn_egov_go_loginInfoList() {
    console.log('DeviceAPIGuide fn_egov_go_loginInfoList');
    //3G 사용시 과금이 발생 할 수 있다는 경고 메시지 표시
    if(!fn_egov_network_check(false)) {
    	return;
    }
    
    $.mobile.changePage("#loginInfoList", "slide", false, false);
	
    var url = "/pki/xml/pkiInfoList.do";
    var accept_type = "xml";
    // get the data from server
    window.plugins.EgovInterface.post(url,accept_type, null, function(xmldata) {
        console.log('DeviceAPIGuide fn_egov_go_loginInfoList request Complete');
        var list_html = "";		
        $(xmldata).find("pkiInfoList").each(function(){
            var dn = $(this).find("dn").text();
            var date = $(this).find("crtfcDt").text();
            var entrprsSeCode = $(this).find("entrprsSeCode").text().replace(/\s+$/, "");
            var entrprsSe = "NONE";
            if(entrprsSeCode == 'PKI01')
                entrprsSe = "MagicXSign";
            else if(entrprsSeCode == 'PKI02')
                entrprsSe = "WizSign";
            else if(entrprsSeCode == 'PKI03')
                entrprsSe = "XecureSmart";

            list_html += "<li><h3>subjdn : " + dn + "</h3>";
            list_html += "<p><strong>Date : " + date + "</strong></p>";						
            list_html += "<p><strong>NPKI : " + entrprsSe + "</strong></p></li>";
        });
        var theList = $('#theLogList');
        theList.html(list_html);				
        theList.listview("refresh"); 
        setTimeout(loadiScrollList, 1000);	
    });
}

• 프로젝트 선택 > 오른쪽 클릭 > Run As > Android Application

• 상단의 메뉴 > Run As > Android Application

• 실행할 타겟 선택 > 에뮬레이터, 디바이스(디버깅모드)

• 디바이스를 이용한 실행 화면

• 서버사이드 가이드 프로그램의 실행은 프로젝트를 마우스 오른쪽 버튼을 클릭 한후 Run As>Run On Server 버튼을 통해 실행 할 수 있다.

• 빌드가 성공적으로 수행 되면 이클립스의 콘솔 창에서 'Server Startup in xxx ms' 메시지를 확인 할 수 있다.

디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스에서 확인 할 수 있다.

console.log의 작성 방법은 다음과 같다.

function fn_egov_getcertlistSuccess(arg) {
    console.log('DeviceAPIGuide fn_egov_getcertlistSuccess Success');
    certListObj = JSON.parse(arg);
    var certList = '';
    ...
}

디버깅 코드가 실행 되면 아래와 같은 메시지를 개발도구의 콘솔 메시지 창에서 볼 수 있다.

NPKI 디바이스 API 가이드 프로그램 에서는 디버깅을 위하여 다음과 같이 콘솔 정보를 출력한다.

NPKI(MagicXSign) 디바이스 API 가이드 다운로드 : Click 새 창 열림

• Cordova : Click 새 창 열림
  
• UX/UI 라이브러리 : jQuery MobileClick 새 창 열림
  
• 표준보안API : Click 새 창 열림
  
• (주)드림시큐리티 : Click 새 창 열림