목차

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

개요

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

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

특징

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

기능흐름도

기능시퀀스

전제조건

구분내용
Local 디바이스 개발 환경전자정부표준프레임워크 개발환경2.5, Android SDK Revision 18(적용빌드번호 : GINGERBREAD EL21)
서버 사이드 개발 환경전자정부표준프레임워크 개발환경2.5
표준 보안 API 설정(아래 환경설정의 Server Application 참조 )
Mash up Open API 연계N/A
테스트 디바이스 Galaxy S2
테스트 플랫폼 Android 2.2
추가 라이브러리 적용NPKI XecureSmart Library

NPKI XecureSmart Library

파일명설명
libs/KeySharp_Android_1.3.8.jar XecureSmart 라이브러리
libs/XecureSmart.jar XecureSmart PhoneGap Plugin Class 라이브러리
libs/armeabi/libKeySharp_Android_Core.so XecureSmart 라이브러리
libs/armeabi/libXecureCrypto.so XecureSmart 라이브러리
libs/armeabi/libXecurePKCS11.so XecureSmart 라이브러리
libs/armeabi/libXWClientSM_jni.so XecureSmart 라이브러리
assets/www/js/egovframework/mbl/hyb/XSCore.js XecureSmart PhoneGap Plugin JavaScript
src/com.softforum.xecure.XApplication.java XecureSmart 메인 Activity Class
src/com.softforum.xecure.util.EnvironmentConfig.java XecureSmart 설정 Class

제약사항

NPKI 기술협력에 대한 제약 사항

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

업체명연락처E-Mail
주식회사소프트포럼(031)622-6223 sukbum@softforum.com

전자정부 보안표준 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 가이드 프로그램은 크게 모바일 기기내의 인증서를 선택 및 서명 데이터를 만들어 웹 서버 어플리케이션으로 전송하여 인증서 인증하는 기능과 인증서 인증된 로그 데이터를 조회하는 기능으로 구성되어 있다.(관련기능 부분참조)

관련 클래스다이어그램

Device Application

관련 소스

유형대상소스명비고
Activitykr.go.egovframework.hyb.pkiapi.xecuresmart.PKIXecureSmartAPIGuide_AndroidActivityNPKI 가이드 프로그램 Activity Class
Activitycom.softforum.xecure.XApplication.javaNPKI 가이드 프로그램(XecureSmart) Main Activity Class
Classcom.softforum.xecure.util.EnvironmentConfig.javaXecureSmart 환경 설정 관련 Class
CSSassets/www/css/egovframwork/mbl/hyb/PKIXecureSmartAPI.css NPKIAPI 가이드 프로그램 주요 Cascading Style Sheets
IMAGE assets/www/images/egovframwork/mbl/hyb/ NPKIAPI 가이드 프로그램 주요 Image 폴더
JS assets/www/js/egovframwork/mbl/hyb/PKIXecureSmartAPI.js NPKIAPI 가이드 프로그램 주요 JavaScript
JS assets/www/js/egovframwork/mbl/hyb/XSCore.js NPKIAPI 가이드 프로그램 주요 JavaScript
JS assets/www/js/egovframwork/mbl/hyb/messages_ko.js Validate 메세지 처리 JavaScript
RES assets/www/res/ NPKIAPI 가이드 프로그램 주요 Resource 폴더
XML AndroidManiFest.xml 안드로이드 어플리케이션 설정 XML
HTMLassets/www/PKIXecureSmartAPI.htmlNPKIAPI 메인 페이지
HTMLassets/www/Intro.htmlNPKIAPI Intro 페이지
HTMLassets/www/license.htmlNPKIAPI 라이센스 페이지
HTMLassets/www/overview.htmlNPKIAPI 기능설명 페이지

전체 기능 API

XecureSmart API DOC

가이드프로그램에서 활용한 API

XecureSmartPlugin.getCertTree
void XecureSmartPlugin.getCertTree ( successCB , failCB , certType , searchType , contentLevel , searchValue , searchSerial )
Option설명비고
successCB성공 시 콜백함수(out)contentLevel : 0(자세한 정보), contentLevel : 5(간략한 정보)
failCB실패 시 콜백함수(out)에러코드$에러메세지
certType타입(in)0:루트인증서,1:CA인증서,2:사용자인증서,3:전체인증서
searchType검색조건(in)0:검색하지않음
10:subjectDN의 CN과 일치
11:subjectDN의 OU와 일치
12:subjectDN의 O와 일치
13:subjectDN의 C와 일치
14:subjectDN과 일치
20:issuerDN의 CN과 일치
21:issuerDN의 OU과 일치
22:issuerDN의 O와 일치
23:issuerDN의 C와 일치
24:issuerDN과 일치
contentLevel결과값의 레벨(in)0:자세한 정보,5:간략한 정보
searchValue검색값(in)
searchSerial검색할 일련 번호(in)
XecureSmartPlugin.signDataCMS
void XecureSmartPlugin.signDataCMS ( successCB , failCB , issuerDN , serial , password , plainText )
Option설명비고
successCB성공 시 콜백함수(out)전자서명 텍스트
failCB실패 시 콜백함수(out)에러코드$에러메세지
issuerDN인증서의 발급자(in)
serial인증서의 일련번호(in
password인증서의 암호(in)
plainText평문(in)

Server Application

관련 소스

유형대상소스명비고
Controlleregovframework.hyb.add.pki.web.EgovPKIAndroidAPIController.javaNPKIAPI 가이드 프로그램 Controller Class
Serviceegovframework.hyb.add.pki.service.EgovPKIAndroidAPIService.javaNPKIAPI 가이드 프로그램 Service Class
ServiceIimplegovframework.hyb.add.pki.service.impl.EgovPKIAndroidAPIServiceImpl.javaNPKIAPI 가이드 프로그램 ServiceImpl Class
VOegovframework.hyb.add.pki.service.PKIAndroidAPIDefaultVO.javaNPKIAPI 가이드 프로그램 VO Class
VOegovframework.hyb.add.pki.service.PKIAndroidAPIVO.javaNPKIAPI 가이드 프로그램 VO Class
VOegovframework.hyb.add.pki.service.PKIAndroidAPIXmlVO.javaNPKIAPI 가이드 프로그램 XML 관련 VO Class
DAOegovframework.hyb.add.pki.service.impl.PKIAndroidAPIDAO.javaNPKIAPI 가이드 프로그램 Dao Class
QUERY XMLresources/egovframework/sqlmap/hyb/add/pki/EgovPKIAndroidAPIGuide_SQL_XXX.xmlNPKIAPI 가이드 프로그램 QUERY XML
Idgen XMLresources/egovframework/spring/context-idgen.xmlNPKIAPI 가이드 프로그램 Id생성 Idgen XML

관련 테이블

테이블명테이블명(영문)비고
PKIPKI인증서 인증 로그 관리

테이블 명세서

No.컬럼컬럼명타입길이NullKEY
1SN일련번호NUMERIC6NotNullpk
2UUIDUUIDVARCHAR50NotNullpk
3DMDMVARCHAR255Null
4CRTFC_DT인증일시DATE Null
5ENTRPRS_SE_CODE이메일DATE Null

ERD

표준 보안 API

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 관련 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

Device Application

src/kr.go.egovframework.hyb.pkiapi.xecuresmart.PKIXecureSmartAPIGuide_AndroidActivity

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

    //XecureSmart 사용을 위한 라이브러리 로드
    CoreWrapper.load();
	
    super.clearCache();
    super.loadUrl("file:///android_asset/www/intro.html");
}

res/xml/config.xml

    <!--전자정부 Interface 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="EgovInterfacePlugin" value="kr.go.egovframework.hyb.plugin.EgovInterfacePlugin" />
    <!--전자정부 NPKI 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="XSPGPlugin" value="com.softforum.xecure.phonegap.XecureSmartPGPlugin"/>

res/values/serverinfo.xml

    <!--전자정부 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>

AndroidManifest.xml

허가 기능 설정

<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" />

Main Activity 설정

<application android:name="com.softforum.xecure.XApplication" 
             android:icon="@drawable/ic_launcher" 
             android:label="@string/app_name" 
             android:debuggable="true">
    <activity android:name=".PKIXecureSmartAPIGuide_AndroidActivity" 
              android:label="@string/app_name" android:configChanges="orientation|keyboardHidden">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" /> 
            <category android:name="android.intent.category.LAUNCHER" /> 
        </intent-filter>
    </activity>
    <activity android:name="com.phonegap.DroidGap" android:label="@string/app_name" 
              android:configChanges="orientation|keyboardHidden">
        <intent-filter>
        </intent-filter> 
    </activity>
</application>

Server Application

pom.xml

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

resource/egovframework/sqlmap/sql-map-config_[DB명].xml

<sqlMap resource="egovframework/sqlmap/hyb/add/dvc/EgovPKIAndroidAPIGuide_SQL_[DB명].xml"/>
구분설정방법
Class 경로 설정방법 1. java 옵션 이용 : java -classpath jar_directory\libgpkiapi_jni.jar
방법 2. 환경 변수 등록 : “내컴퓨터→속성→고급→환경변수” 에서 새로 만들기를 클릭하여 classpath 변수를 등록

npkiclasspath.jpg

구분설정방법
라이브러리 경로 설정1. JNI를 비롯한 C/C++용 표준보안API와 LDAP 라이브러리가 위치해 있는 경로를 환경 변수에 등록한다.
2. “내컴퓨터→속성→고급→환경변수” 에서 기존 “path” 변수에 “라이브러리가 설치된 디렉토리”를 추가한다.

npkipath.jpg

관련기능

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

모바일 기기 인증서 선택/인증하기

비즈니스 규칙

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

관련코드

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

// 인증서 리스트 조회
function fn_egov_go_certlist() {
    console.log('DeviceAPIGuide fn_egov_go_certlist');
    $.mobile.showPageLoadingMsg('a');
    XecureSmart.getCertTree(fn_egov_getcerttree_success, fn_egov_getcerttree_fail, 2, 0, 5, '', '');
}

// 인증서 서명
function fn_egov_make_sign()
{
    console.log('DeviceAPIGuide fn_egov_make_sign');
    XecureSmart.signDataCMS (fn_egov_makesign_ok, fn_egov_makesign_fail, document.getElementById("issuerDN").value, document.getElementById("certSerial").value, $("#loginPasswd").val(), "usrId=&password=&name=");		
}

// 인증서 서명 데이터 서버로 인증 요청
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: 'PKI03'};
    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');
        }
    });	
}

관련화면 및 수행매뉴얼

ActionURLController methodQueryID
인증서 인증/pki/xml/addPKIInfo.doaddPKIInfoXml“PKIAndroidAPIDAO.insertPKIInfo”
인증서 리스트인증서 인증

인증서 리스트 화면에서 인증 할 인증서를 선택하고 인증서 인증 화면에서 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);	
    });
}

관련화면 및 수행매뉴얼

기능URLControllermethodQueryID
인증서 인증 결과 로그 조회/pki/xml/pkiInfoList.doEgovPKIAndroidAPIControllerselectPKIInfoListXmlPKIAndroidAPIDAO.selectPKIInfoList

컴파일 디버깅 배포

컴파일

NPKIAPI(XecureSmart) Device Applicaton 컴파일 방법



DeviceInfoAPI Server Applicaton 컴파일 방법

디버깅

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

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

function fn_egov_getcerttree_success(result) {	
    console.log('DeviceAPIGuide fn_egov_getcerttree_success Success');
    $.mobile.hidePageLoadingMsg('a');
    var certInfoArray = result.split ("\t\n");
    ...
}

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

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

디버그 코드디버깅 내용
DeviceAPIGuide fn_egov_getcerttree_success Success 인증서 리스트 조회 성공 시
DeviceAPIGuide fn_egov_getcerttree_fail Fail 인증서 리스트 조회 실패 시
DeviceAPIGuide fn_egov_makesign_ok Success 인증서 서명 성공 시
DeviceAPIGuide fn_egov_makesign_fail Fail 인증서 서명 실패 시
DeviceAPIGuide fn_egov_makesign_ok request Complete 웹 서버 어플리케이션으로 부터 인증서 인증 성공 시
DeviceAPIGuide fn_egov_go_loginInfoList request Complete 인증서 인증 로그 정보 조회 성공 시

배포

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

참고자료