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

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

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

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

• 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)를 참고한다.

• 문제 : 폰갭 오류시.
• 해결방안 : setTimeout() 함수로 phonegap 로딩 순서를 지연시킨다.
  

    document.addEventListener('DOMContentLoaded', function () { setTimeout(loaded, 200); }, false);

• 문제 : iScroll5 컨텐츠 내용 높이 계산 오류.
• 해결방안 : setTimeout() 함수로 컨텐츠에 css 적용이 완료되고 iscroll 생성이 되도록 한다.

setTimeout(function()
           {
               myScroll = new iScroll(thisPage, 
                                      { 
                                          checkDOMChanges: true,
                                          onBeforeScrollStart:function(e)
                                          {
                                          }
                                      });
           },
           500);

• 문제 : 폰갭에 지정한 콜백 함수에서 alert() 메시지 호출시 동작 오류.
• 해결 방안 : 비동기 함수를 사용하거나 alert()처럼 스레드를 잡는 함수는 사용하지 않는다.

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

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.magicxsign.certdel(success return, fail return, Cert Index);

window.plugins.magicxsign.certdel(certdelSuccess, certdelFail, 0);

• 인증서의 비밀번호를 변경한다.

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

var setDefine = {};
setDefine["certindex"] = iCertIndex;	//선택된 인증서 index
setDefine["oldpassword"] = oldpassword;	//선택된 인증서 Password
setDefine["newpassword"] = newpassword;	//신규 인증서 Password
window.plugins.magicxsing.certchagepassword(certchagepasswordSuccess, certchagepasswordFail, 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));

• 인증서버에 접속 하여 인증번호를 얻어온다.

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

var setDefine = {};
setDefine["phoneno"] = "123456789";
setDefine["serverip"] = "125.141.204.173";
setDefine["serverport"] = "10001";
setDefine["serviceid"] = "dreamAPP";
window.plugins.magicxsign.makesign(makesign_ok, makesign_fail, JSON.stringify(setDefine));

• 인증서를 전송 받아 저장하고 인증서 정보를 리턴한다.

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

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

• 인증서 이동을 중지한다.

window.plugins.magicxsign.mrs_stopcertmove();

• 올레인증서가 인스톨 되어 있는지 확인한다.

window.plugins.magicxsign.ollecert_check(ollecert_Check_Success, ollecert_Check_Fail);

• 올레인증서 인스톨을 위해 AppStore의 올레인증서 인스톨 화면 호출

window.plugins.magicxsign.ollecert_install();

• 올레인증서에서 인증서를 요청하여 선택된 인증서를 저장한다.

var setDefine = ["oidname","issuer","name","subjdn","start","end"];
window.plugins.magicxsign.ollecert_getcert(certGetFromOlleCert_Success, certGetFromOlleCert_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 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

    <feature name="InterfaceAPI">
        <param name="ios-package" value="EgovInterface"/>
    </feature>
    <!--전자정부 NPKI 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <feature name="MagicXSignPlugin">
        <param name="ios-package" value="MagicXSignPlugin"/>
    </feature>

<!--전자정부 Interface 디바이스 API에서 사용하기 위한 서버경로 설정-->
#define kSERVER_URL     @"Server_URL"

<sqlMap resource="egovframework/sqlmap/hyb/ios/pki/EgovPKIiOSAPIGuide_SQL_[DB명].xml"/>

설정 참조

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

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

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

// 인증서 리스트 조회
function fn_egov_show_certlist()
{
    console.log('DeviceAPIGuide fn_egov_show_certlist');
    $.mobile.showPageLoadingMsg('a');
    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() {		
    console.log('fn_egov_login_member()');

    $.mobile.showPageLoadingMsg('a');
    
    var setDefine = {};
    setDefine["plaintext"]=encodeURIComponent("usrId=&password=&name=");		// form Data	
    setDefine["certindex"]=document.getElementById("xsigncertindex").value;			// 선택된 인증서 INDEX
    setDefine["certpassword"]=$("#loginPasswd").val();								// 선택된 인증서 Password
    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');
    var jsonobj = JSON.parse(arg);
	
    var signedData = jsonobj.sign;
    var vidRandom = jsonobj.vidRandom;
    
    var acceptType = "json";	
    var params = {  uuid :  device.uuid,			
        sign : signedData,
        entrprsSeCode : "PKI01"};
	
    alert('Http Method:POST\nAcceptType:JSON\n전송데이터:' + JSON.stringify(params));
    $.mobile.showPageLoadingMsg('a');
    EgovInterface.submitAsynchronous(
                                     [params, "/pki/addPKIiOSInfo.do"],
                                     function(result) {
                                         console.log("PKIMagicXSignAPIGuide fn_egov_makesign_ok Completed");
                                         var str = '{';
                                         for (myKey in result){
                                             str += myKey + ':' + result[myKey] + '\n';
                                         }
                                         str += '}';
                                         alert('응답방식:RESTful\n응답Type:json, post\nParam:\n' + str);
                                         //window.history.back();
                                         $.mobile.hidePageLoadingMsg('a');
                                         location.href = "index.html";
                                     },
                                     function(error) {
                                         console.log("PKIMagicXSignAPIGuide fn_egov_makesign_ok Failed");
                                         var str = '{';
                                         for (myKey in result){
                                             str += myKey + ' : ' + result[myKey] + '\n';
                                         }
                                         str += '}';
                                         $.mobile.hidePageLoadingMsg('a');
                                         alert('응답방식:RESTful\n전송Type:json, post\nParam:\n' + str);
                                     }
                                    );
    document.getElementById("innerhtmlArea").innerHTML= "SendResult : <br>"+str+"<br><br>";
}

//올레인증서가 설치되어있는지 확인
function fn_egov_check_ollecert()
{
    console.log('fn_egov_check_ollecert()');
    window.plugins.magicxsign.ollecert_check(fn_egov_ollecert_Check_Success,  fn_egov_ollecert_Check_Fail);
}  

//올레인증서 호출
function fn_egov_certGetFromOlleCert()
{
    console.log('fn_egov_certGetFromOlleCert()');
    var setDefine = ["oidname","issuer","name","subjdn","start","end"];
    window.plugins.magicxsign.ollecert_getcert( fn_egov_certGetFromOlleCert_Success, fn_egov_certGetFromOlleCert_Fail, JSON.stringify(setDefine) );
}

인증서 리스트	인증서 인증

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

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

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

function fn_goLoginInfoList()
{
    console.log('fn_goLoginInfoList()');
    var accept_type = "json";
    // get the data from server
    $.mobile.showPageLoadingMsg('a');
    EgovInterface.submitAsynchronous(
                                     ["/pki/pkiInfoList.do"],
                                     function(result) {
                                         console.log("PKIMagicXSignAPIGuide fn_goLoginInfoList Completed");
                                         var list_html = "";
                                         var totcnt = result.pkiInfoList.length;
                                         
                                         for (var i = 0; i < totcnt; i++) {
                                             var data = result.pkiInfoList[i];
                                             var entrprsSe = "NONE";
                                             var entrprsSeCode = data.entrprsSeCode;
                                             if(entrprsSeCode == 'PKI01')
                                                 entrprsSe = "MagicXSign";
                                             else if(entrprsSeCode == 'PKI02')
                                                 entrprsSe = "WizSign";
                                             else if(entrprsSeCode == 'PKI03')
                                                 entrprsSe = "XecureSmart";
                                             
                                             list_html += "<li><h3>subjdn : " + data.dn + "</h3>";
                                             list_html += "<p><strong>Date : " + data.crtfcDt + "</strong></p>";
                                             list_html += "<p>NPKI : " + entrprsSe + "</p></li>";
                                         }
                                         var theList = $('#theLogList');
                                         theList.html(list_html);
                                         $.mobile.changePage("#loginInfoList", "slide", false, false);	
                                         theList.listview("refresh");
                                         $.mobile.hidePageLoadingMsg('a');
                                         setTimeout(loadiScrollList, 1000);
                                     },
                                     function(error) {
                                         console.log("PKIMagicXSignAPIGuide fn_goLoginInfoList Failed");
                                         var str = '{';
                                         for (var myKey in error){
                                            str += myKey + ' : ' + error[myKey] + '\n';
                                         }
                                         str += '}';
                                         $.mobile.hidePageLoadingMsg('a');
                                         alert('응답방식:RESTful\n전송Type:json, post\nParam:\n' + str);
                                     }
                                    );
}

1. 디바이스 또는 시뮬레이터에서 실행하고자 할 경우 빨간 테두리 영역을 클릭한다.

2. 디바이스 또는 시뮬레이터를 선택한다.

3. 실행 버튼을 클릭한다.

4. 인트로 화면과 메인 화면을 확인한다.

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

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

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

• 실제 콘솔 로그 예

function fn_egov_network_check(doCheck)
{
    console.log('DeviceAPIGuide fn_egov_network_check');
    var networkState = navigator.network.connection.type;
    ...
}

• xCode 콘솔 창

• Organizer 로그 창

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

NPKI 디바이스 API 가이드 다운로드 : Click

• UX/UI 라이브러리 : jQuery MobileClick
  
• Phonegap 4.3.0 : Click
  
• 표준보안API : http://www.gpki.go.kr/