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 디바이스 API 구성 라이브러 중 아래 코드 라이브러리는 보안 Native Module로서 라이선스를 가지고 있다. 그에 따라, 표에 기재된 라이브러리의 경우 NPKI 디바이스 API 배포 시 배포 리소스에서 제외하여 배포되고, 해당 모듈을 적용하여, 테스트 및 실제 구현을 진행하고자 하는 정부기관이나, 업체에서는 아래 기술협력 업체로 연락 문의해야 한다.
업체명 | 연락처 | |
---|---|---|
주식회사소프트포럼 | (031)622-6223 | sukbum@softforum.com |
전자정부 보안표준 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 가이드 프로그램은 크게 모바일 기기내의 인증서를 선택 및 서명 데이터를 만들어 웹 서버 어플리케이션으로 전송하여 인증서 인증하는 기능과 인증서 인증된 로그 데이터를 조회하는 기능으로 구성되어 있다.(관련기능 부분참조)
유형 | 대상소스명 | 비고 |
---|---|---|
Activity | kr.go.egovframework.hyb.pkiapi.xecuresmart.PKIXecureSmartAPIGuide_AndroidActivity | NPKI 가이드 프로그램 Activity Class |
Activity | com.softforum.xecure.XApplication.java | NPKI 가이드 프로그램(XecureSmart) Main Activity Class |
Class | com.softforum.xecure.util.EnvironmentConfig.java | XecureSmart 환경 설정 관련 Class |
CSS | assets/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 |
HTML | assets/www/PKIXecureSmartAPI.html | NPKIAPI 메인 페이지 |
HTML | assets/www/Intro.html | NPKIAPI Intro 페이지 |
HTML | assets/www/license.html | NPKIAPI 라이센스 페이지 |
HTML | assets/www/overview.html | NPKIAPI 기능설명 페이지 |
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) |
void XecureSmartPlugin.signDataCMS ( successCB , failCB , issuerDN , serial , password , plainText )
Option | 설명 | 비고 |
---|---|---|
successCB | 성공 시 콜백함수 | (out)전자서명 텍스트 |
failCB | 실패 시 콜백함수 | (out)에러코드$에러메세지 |
issuerDN | 인증서의 발급자 | (in) |
serial | 인증서의 일련번호 | (in |
password | 인증서의 암호 | (in) |
plainText | 평문 | (in) |
유형 | 대상소스명 | 비고 |
---|---|---|
Controller | egovframework.hyb.add.pki.web.EgovPKIAndroidAPIController.java | NPKIAPI 가이드 프로그램 Controller Class |
Service | egovframework.hyb.add.pki.service.EgovPKIAndroidAPIService.java | NPKIAPI 가이드 프로그램 Service Class |
ServiceIimpl | egovframework.hyb.add.pki.service.impl.EgovPKIAndroidAPIServiceImpl.java | NPKIAPI 가이드 프로그램 ServiceImpl Class |
VO | egovframework.hyb.add.pki.service.PKIAndroidAPIDefaultVO.java | NPKIAPI 가이드 프로그램 VO Class |
VO | egovframework.hyb.add.pki.service.PKIAndroidAPIVO.java | NPKIAPI 가이드 프로그램 VO Class |
VO | egovframework.hyb.add.pki.service.PKIAndroidAPIXmlVO.java | NPKIAPI 가이드 프로그램 XML 관련 VO Class |
DAO | egovframework.hyb.add.pki.service.impl.PKIAndroidAPIDAO.java | NPKIAPI 가이드 프로그램 Dao Class |
QUERY XML | resources/egovframework/sqlmap/hyb/add/pki/EgovPKIAndroidAPIGuide_SQL_XXX.xml | NPKIAPI 가이드 프로그램 QUERY XML |
Idgen XML | resources/egovframework/spring/context-idgen.xml | NPKIAPI 가이드 프로그램 Id생성 Idgen XML |
테이블명 | 테이블명(영문) | 비고 |
---|---|---|
PKI | PKI | 인증서 인증 로그 관리 |
No. | 컬럼 | 컬럼명 | 타입 | 길이 | Null | KEY |
---|---|---|---|---|---|---|
1 | SN | 일련번호 | NUMERIC | 6 | NotNull | pk |
2 | UUID | UUID | VARCHAR | 50 | NotNull | pk |
3 | DM | DM | VARCHAR | 255 | Null | |
4 | CRTFC_DT | 인증일시 | DATE | Null | ||
5 | ENTRPRS_SE_CODE | 이메일 | DATE | Null |
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); //XecureSmart 사용을 위한 라이브러리 로드 CoreWrapper.load(); super.clearCache(); super.loadUrl("file:///android_asset/www/intro.html"); }
<!--전자정부 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"/>
<!--전자정부 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" />
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>
<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"/>
구분 | 설정방법 |
---|---|
Class 경로 설정 | 방법 1. java 옵션 이용 : java -classpath jar_directory\libgpkiapi_jni.jar 방법 2. 환경 변수 등록 : “내컴퓨터→속성→고급→환경변수” 에서 새로 만들기를 클릭하여 classpath 변수를 등록 |
구분 | 설정방법 |
---|---|
라이브러리 경로 설정 | 1. JNI를 비롯한 C/C++용 표준보안API와 LDAP 라이브러리가 위치해 있는 경로를 환경 변수에 등록한다. 2. “내컴퓨터→속성→고급→환경변수” 에서 기존 “path” 변수에 “라이브러리가 설치된 디렉토리”를 추가한다. |
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'); } }); }
Action | URL | Controller method | QueryID |
---|---|---|---|
인증서 인증 | /pki/xml/addPKIInfo.do | addPKIInfoXml | “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); }); }
기능 | URL | Controller | method | QueryID |
---|---|---|---|---|
인증서 인증 결과 로그 조회 | /pki/xml/pkiInfoList.do | EgovPKIAndroidAPIController | selectPKIInfoListXml | PKIAndroidAPIDAO.selectPKIInfoList |
디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 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