====== NPKI(XecureSmart) 디바이스API 가이드 프로그램 ====== ===== 개요 ===== NPKI 가이드 프로그램(XecureSmart)은 모바일 디바이스 API 실행환경을 활용하여 하이브리드 앱을 개발 시 참고 및 활용될 수 있도록 구현된 전자정부 디바이스 API에 대한 가이드 앱으로써, 모바일 스마트 디바이스의 NPKI 관련 기능을 JavaScript 기반으로 구성 된 NPKI DeviceAPI를 통하여 이용할 수 있도록 지원한다. \\ 또한, 전자정부 표준프레임워크 기반의 웹 서버 어플리케이션과 연계하여 모바일기기에 저장된 인증서를 정부에서 제공하는 인증을 이용하여 인증서 인증을 하고 결과를 서버에 저장하며 인증서 인증 결과 로그를 조회하는 기능으로 구성되어 있다. \\ ==== 특징 ==== 본 가이드 프로그램 에서는 NPKI 기능을 가이드 할 수 있도록 ** 모바일 기기 인증서 선택/인증하기 **, ** 인증 로그 정보 보기 ** 기능을 제공하고 있으며 웹 서버 어플리케이션에 ** 표준 보안 API ** 를 적용하여 인증서 정보를 확인 할 수 있는 기능으로 구현되었다. ==== 기능흐름도 ==== {{:egovframework:hyb3.6:guide:ios:magicxsign:magicxsign_flow.png?540|}} ==== 기능시퀀스 ==== {{:egovframework:hyb:guide:add:NPKI시퀀스다이어그램.png?400|}} ==== 전제조건 ==== ^ 구분 ^ 내용 ^ |Local 디바이스 개발 환경| Xcode 8.0 (8A218a), Cordova 6.4.0 | |서버 사이드 개발 환경| 전자정부표준프레임워크 개발환경3.6| |Mash up Open API 연계| N/A| |테스트 디바이스 | iPhone 6 , iPad Air | |테스트 플랫폼 | iOS 9.3, iOS 10.0 | |추가 라이브러리 적용|XecureSmart 라이브러리 적용\\ wizsXSCore.js, \\ libKeySharpiPhone.a, \\ libXecureSmartPG.a, \\ XecureSmartPG.h, \\ XWUIErrorCode.h, \\ CopyCertificate.h, \\ libXecureSmartPG.a, \\ bridge, crypto| ==== 제약사항 ==== === NPKI 라이브러리 === * NPKI 디바이스 API 가이드 프로그램에는 보안모듈이 포함되어있지 않기 때문에 해당 보안 모듈회사로 라이센스 계약 및 지원 요청을 해야한다. \\ ^업체명^담당자^전화번호^홈페이지^ |소프트포럼 주식회사|신민규 선임|031-622-6300|[[http://www.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)를 참고한다. \\ \\ === 지원 디바이스 및 플랫폼 === == iPhone 의 경우 장치의 연산속도에 따른 문제가 발생할 수 있다. == * 문제 : 폰갭 오류시. * 해결방안 : 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); == CallBack 함수에서 alert() 를 포함하면 문제가 발생할수 있다 (phoneGap) == * 문제 : 폰갭에 지정한 콜백 함수에서 alert() 메시지 호출시 동작 오류. * 해결 방안 : 비동기 함수를 사용하거나 alert()처럼 스레드를 잡는 함수는 사용하지 않는다. == Xcode 4.5에서 실행 시 주의 사항 == Xcode 4.5부터 iOS 6, iPhone 5를 지원하는데, 해당 디바이스와 OS를 지원을 할 경우 PhoneGap 1.9.0의 라이브러리는 Xcode 4.X에서 컴파일되어 배포되는 라이브러리라 프로젝트 옵션을 조정할 필요가 있다.\\ 1. 옵션 설정\\ {{:egovframework:hyb:guide:ios:xcode4.5_제약사항1.png|}} 2. armv7s 삭제\\ {{:egovframework:hyb:guide:ios:xcode4.5_제약사항2.png|}} === 크로스 도메인 사용 === 폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,\\ [Project_Name]/Supproting Files/config.xml에서 항목에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다. ===== 설명 ===== NPKI 디바이스API 가이드 프로그램은 크게 모바일 기기내의 인증서를 선택 및 서명 데이터를 만들어 웹 서버 어플리케이션으로 전송하여 인증서 인증하는 기능과 인증서 인증된 로그 데이터를 조회하는 기능으로 구성되어 있다.(관련기능 부분참조) === 클래스 다이어그램 === {{:egovframework:hyb:guide:ios:pki_class.png?1024}} ==== Device Application ==== === 관련 소스 === ^유형^대상소스명^비고^ |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/PKIXSCoreAPI.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| |HTML|assets/www/NPKIXecureSmartAPI.html|NPKIAPI 메인 페이지| |HTML|assets/www/license.html|NPKIAPI 라이센스 페이지| |HTML|assets/www/overview.html|NPKIAPI 기능설명 페이지| |HTML| assets/www/intro.html|NPKIAPI Intro 페이지| |RES | [Project_Name]/Resources/ |NPKIAPI 가이드 프로그램 주요 Resource 폴더| |PLIST | [Project_Name]/Resources/[Project_Name]-Info.plist | iOS 어플리케이션 설정 파일| === 전체 기능 API === [[egovframework:hyb2.7:guide:ios:npki_소프트포럼:xecuresmart_doc|XecureSmart API DOC]] === 활용 API === == XecureSmartPlugin.getCertTree == * 장치의 인증서 목록을 가져온다. searchType과 searchValue를 함께 사용하여 검색이 가능하며, searchSerial를 이용해 일련 번호로 검색도 가능하다. \\ 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 ==== === 관련 소스 === ^유형^대상소스명^비고^ |Controller|egovframework.hyb.ios.pki.web.EgovPKIiOSAPIController.java|NPKIAPI 가이드 프로그램 Controller Class| |Service|egovframework.hyb.ios.pki.service.EgovPKIiOSAPIService.java|NPKIAPI 가이드 프로그램 Service Class| |ServiceIimpl|egovframework.hyb.ios.pki.service.impl.EgovPKIiOSAPIServiceImpl.java|NPKIAPI 가이드 프로그램 ServiceImpl Class| |VO|egovframework.hyb.ios.pki.service.PKIiOSAPIDefaultVO.java|NPKIAPI 가이드 프로그램 VO Class| |VO|egovframework.hyb.ios.pki.service.PKIiOSAPIVO.java|NPKIAPI 가이드 프로그램 VO Class| |VO|egovframework.hyb.ios.pki.service.PKIiOSAPIXmlVO.java|NPKIAPI 가이드 프로그램 XML 관련 VO Class| |DAO|egovframework.hyb.ios.pki.service.impl.PKIiOSAPIDAO.java|NPKIAPI 가이드 프로그램 Dao Class| |QUERY XML|resources/egovframework/sqlmap/hyb/ios/pki/EgovPKIiOSAPIGuide_SQL_XXX.xml|NPKIAPI 가이드 프로그램 QUERY XML| |Idgen XML|resources/egovframework/spring/context-idgen.xml|NPKIAPI 가이드 프로그램 Id생성 Idgen XML| === 관련 테이블 === ^테이블명^테이블명(영문)^비고^ |PKI|PKI|인증서 인증 로그 관리| === 테이블 정의서 === * PKI ^No^컬럼ID^컬럼명^타입^길이^Null^ |1|SN|일련번호|NUMERIC|6|NotNull| |2|UUID|UUID|VARCHAR|50|NotNull| |3|DN|인증데이터|VARCHAR|255|Null| |4|CFTFC_DT|인증날짜시간|DATETIME| |Null| |5|ENTRPRS_SE_CODE|업체구분|CHAR|15|Null| === ERD === {{:egovframework:hyb:guide:ios:erd.jpg|}} === 표준 보안 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 ==== === config.xml === == Plugin == === [Project_Name]/eGovModule/EGovComModule.h === #define kSERVER_URL @"Server_URL" ==== Server Application ==== === resource/egovframework/sqlmap/sql-map-config_[DB명].xml === === 표준 보안 API === 설정 참조 ===== 관련기능 ===== 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('PKIXSCoreAPIGuide 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 signDataCMS_success (result) { console.log("PKIXSCoreAPIGuide signDataCMS_success Success"); console.log('result : ' + result); if ('전자서명에 실패했습니다.' == result) { alert('전자서명에 실패했습니다.'); return; } // var signedData = arg['signedData']; var params = {uuid : device.uuid, sign: result, entrprsSeCode: 'PKI03'}; $.mobile.showPageLoadingMsg('a'); alert('Http Method:POST\nAcceptType:JSON\n전송데이터:' + JSON.stringify(params)); EgovInterface.submitAsynchronous( [params, "/pki/addPKIiOSInfo.do"], function(result) { console.log("PKIXSCoreAPIGuide signDataCMS_success request 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("PKIXSCoreAPIGuide signDataCMS_success request Failed"); var str = '{'; for (myKey in error){ str += myKey + ' : ' + error[myKey] + '\n'; } str += '}'; alert('응답방식:RESTful\n전송Type:json, post\nParam:\n' + str); $.mobile.hidePageLoadingMsg('a'); } ); } === 관련화면 및 수행매뉴얼 === ^Action^URL^Controller method^QueryID^ |인증서 인증|/pki/xml/addPKIiOSInfo.do|addPKIInfoXml|"PKIiOSAPIDAO.insertPKIInfo"| ^인증서 리스트^인증서 인증^ |{{:egovframework:hyb:guide:ios:xs_cert_list.png|}}|{{:egovframework:hyb:guide:ios:xs_log.png|}}| 인증서 리스트 화면에서 인증할 인증서를 선택하고 인증서 인증 화면에서 PASSWD 항목에 패스워드를 입력 후 "인증 확인" 버튼을 클릭한다. \\ 단, PASSWD 항목에서 validation을 확인하고, 조건이 불충분할 경우 오류 메시지가 출력된다. 인증 확인 : 인증서 인증을 하기 위해서 PASSWD 항목에 인증서 패스워드를 입력 후 "인증 확인" 버튼을 클릭한다. \\ Back 버튼 : **NPKI 디바이스 API 가이드 프로그램 메뉴** 화면 또는 **인증서 리스트** 화면으로 이동한다. \\ ==== 인증 로그 정보 보기 ==== === 비즈니스 규칙 === 웹 서버 어플리케이션으로 부터 인증서 인증 결과 로그를 조회한다. \\ === 관련코드 === function fn_egov_go_loginInfoList() { $.mobile.changePage("#loginInfoList", "slide", false, false); // get the data from server console.log('fn_egov_go_loginInfoList()'); $.mobile.showPageLoadingMsg('a'); var accept_type = "json"; // get the data from server EgovInterface.submitAsynchronous( ["/pki/pkiInfoList.do"], function(result) { console.log("PKIXSCoreAPIGuide fn_egov_go_loginInfoList request 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 += "

  • subjdn : " + data.dn + "

    "; list_html += "

    Date : " + data.crtfcDt + "

    "; list_html += "

    NPKI : " + entrprsSe + "

    • "; } 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("PKIXSCoreAPIGuide fn_egov_go_loginInfoList request Failed"); var str = '{'; for (var myKey in error){ str += myKey + ' : ' + error[myKey] + '\n'; } str += '}'; alert('응답방식:RESTful\n전송Type:json, post\nParam:\n' + str); $.mobile.hidePageLoadingMsg('a'); } ); }     === 관련화면 및 수행매뉴얼 === ^기능^URL^Controller^method^QueryID^ |인증서 인증 결과 로그 조회|/pki/xml/pkiInfoList.do|EgovPKIiOSAPIController|selectPKIInfoListXml|PKIiOSAPIDAO.selectPKIInfoList| {{:egovframework:hyb:guide:ios:xs_log.png|}} ===== 컴파일 디버깅 배포 ===== ==== 컴파일 ==== === Device Applicaton 컴파일 방법 === * 왼쪽 상단의 삼각형 버튼을 클릭하면 가이드 프로그램이 빌드되어 아이폰 디바이스에 설치 된다. {{:egovframework:hyb3.6:guide:mbl:ios_app_compile.png?740|}} * 빌드가 성공하면 아래와 같은 어플리케이션 실행화면을 확인 할 수 있다. {{:egovframework:hyb3.6:guide:ios:xecuresmart:xecuresmart_run.png?320|}} === Server Applicaton 컴파일 방법 === * 서버사이드 가이드 프로그램의 실행은 프로젝트를 마우스 오른쪽 버튼을 클릭 한후 Run As>Run On Server 버튼을 통해 실행 할 수 있다. {{:egovframework:hyb:guide:ios:서버실행.png?640|}} * 빌드가 성공적으로 수행 되면 이클립스의 콘솔 창에서 'Server Startup in xxx ms' 메시지를 확인 할 수 있다. {{:egovframework:hyb:guide:add:서버실행결과_콘솔.png?840|}} ==== 디버깅 ==== 디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 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 콘솔 창 {{:egovframework:hyb:guide:ios:cameradebugxcode.png?700|}}\\ NPKI API 가이드 프로그램 에서는 디버깅을 위하여 다음과 같이 콘솔 정보를 출력한다. ^디버그 코드^디버깅 내용^ |PKIXSCoreAPIGuide deviceready Success|device 준비 완료 성공| |PKIXSCoreAPIGuide getCertTree_success Success|인증서 가져오기 성공 시| |PKIXSCoreAPIGuide getCertTree_fail Failed|인증서 가져오기 실패 시| |PKIXSCoreAPIGuide signDataCMS_success Success|서명 값 가져오기 성공 시| |PKIXSCoreAPIGuide signDataCMS_fail Failed|서명 값 가져오기 실패 시| |PKIXSCoreAPIGuide signDataCMS_success request Completed|서명된값 서버로 전송 성공 시| |PKIXSCoreAPIGuide signDataCMS_success request Failed|서명된값 서버로 전송 실패 시| |PKIXSCoreAPIGuide fn_egov_go_loginInfoList request Completed|서버에서 인증 목록 가져오기 성공 시| |PKIXSCoreAPIGuide fn_egov_go_loginInfoList request Failed|서버에서 인증 목록 가져오기 실패 시| ==== 배포 ==== NPKI 디바이스 API 가이드 다운로드 : [[http://www.egovframe.go.kr/cop/bbs/selectBoardArticle.do?bbsId=BBSMSTR_000000000161&nttId=1274&menu=3&submenu=9|Click]] ===== 참고자료 ===== * Cordova : [[https://cordova.apache.org|Click]] \\ * UX/UI 라이브러리 : jQuery Mobile[[http://jquerymobile.com/demos/1.4.5/|Click]] \\ * 표준보안API : http://www.gpki.go.kr/ \\