표준 API 설치가이드 (v1.1) 1. 표준API 1 2. 웹보안API 6 3. 에러코드 45 붙임1. 표준API 샘플프로그램코드 48 붙임2. 신규표준API 교체방법 49 붙임3. 로그인용웹보안API 필수설정 50 행정전자서명인증운영지원단
< 목차 > 1. 표준API 1 1.1. 표준API 개요 1 1.2. 표준API 적용대상 1 1.3. 용어설명 1 1.4. 표준API 종류 1 1.5. 표준API 디렉토리구조 2 1.6. 표준API 기능 2 1.7. 표준API 설치 3 1.7.1. 표준API 설치파일시스템에올리기 3 1.7.2. 표준API 설치위치에옮기기 3 1.7.3. 표준API 라이브러리환경설정 3 1.7.4. 표준API 구동테스트 5 2. 웹보안API 6 2.1. 웹보안API 디렉토리구조 6 2.1.1. 세부사항 7 2.2. 웹보안API 설치 10 2.2.1. 라이브러리등록 10 2.2.2. WAS 환경설정 10 2.2.3. 웹보안API 환경설정파일 10 2.2.4. 설치방법 12 2.2.5. 함수 ( 웹보안API) 22 2.2.6. 키보드보안연동 (INCA) 33 2.3. 웹보안API ( 데모 ) 구동테스트 35 2.3.1. 인증서로그인 35 2.3.2. 서버인증서인증후보안세션만들기 38 2.3.3. 보안세션 ( 세션키 ) 을이용한암호메세지생성및처리 39 2.3.4. 전자서명메시지 ( 위변조방지 ) 41 2.3.5. 로그아웃 44 2.3.6. 에러대처방안 44 3. 에러코드 45 3.1. 클라이언트 (CS) 에러 45 3.2. 스크립트에러 47 붙임1 48 붙임2 49 붙임3 50
1. 표준API 1.1. 표준API 개요 인터넷상에서공무원및행정기관신원확인, 전자문서위변조방지등을보장하고전자문서의안정적유통을위하여개발된 API입니다. 1.2. 표준 API 적용대상 각급행정기관 1.3. 용어설명 암호알고리즘 : 정보통신망에서소통되는중요전자문서의비밀성확보를위해원문암호화및복호화에사용되는방법및절차. 전자서명 : 전자문서의작성기관및변경여부를확인할수있도록전자서명알고리즘을이용하여개인키로생성한정보로서당해전자문서에고유한것. 개인키 : 전자서명을생성하기위하여이용하는소유자만사용할수있는전자적정보. 공개키 : 개인키에의해생성된전자서명을검증하기위하여이용하는전자적정보. 인증서 : 공개키가기관또는담당자가소유하는개인키에합치된다는사실등에대하여행정인증기관이확인 증명하는전자적정보 1.4. 표준 API 종류 - 1 -
1.5. 표준 API 디렉토리구조 1.6. 표준 API 기능 - 2 -
1.7. 표준API 설치 1.7.1. 표준API 설치파일시스템에올리기 표준API 설치파일을보안서비스를제공할시스템에복사합니다. FTP 로설치파일을올릴때는반드시 "binary" 모드로올려야합니다. 1.7.2. 표준API 설치위치에옮기기표준API 가구동될위치를정하고표준API 모듈 (ex. libgpkiapi.so, libgpkiapi_jni.jar) 과환경파일 (gpkiapi.conf) 을해당위치로옮깁니다. 만약, 표준API에포함되어있는 LDAP 라이브러리가해당시스템에설치되어있지않다면 LDAP 라이브러리도함께설치합니다. 1.7.3. 표준 API 라이브러리환경설정 가. 라이브러리경로설정 - 3 -
나. classpath 설정 ( 자바사용할경우 ) - 4 -
1.7.4. 표준 API 구동테스트 가. command 창실행 => sample 프로그램이동 (java) => java Main 실행 [sample 프로그램실행 ] - 5 -
2. 웹보안 API 2.1. 웹보안 API 디렉토리구조 - 6 -
2.1.1. 세부사항 가. /gpkisecureweb 데모사이트 HTML의화면구성파일이포함되어있습니다. 나. /gpkisecureweb/client 클라이언트설치프로그램의환경을설정하고구동하기위한자바스크립트 파일이들어있습니다. 클라이언트설치프로그램의게시위치, 버전, 키보드 보안적용, 사용가능한인증서저장매체설정등프로그램관련환경설정과, 대칭키암호화알고리즘, 서버인증서등보안관련설정을할수있습니다. - 7 -
다. /gpkisecureweb/client/setup 클라이언트설치프로그램이게시된위치입니다. Windows 용클라이언트설치 프로그램이포함되어있습니다. 라. /gpkisecureweb/client/ui GPKI 사용자용표준보안 API 클라이언트사용을위한화면을구성하는스크립트 파일이포함되어있습니다. - 8 -
마. /gpkisecureweb/jsp GPKI 서버용표준보안 API 라이브러리를호출해서사용자를인증하고데이터를 암복호화하는예제프로그램들이포함되어있습니다. /gpkisecureweb 에포함된 데모사이트 HTML 의화면구성과연동되어데이터를처리합니다. - 9 -
2.2. 웹보안 API 설치 2.2.1. 라이브러리등록 gpkisecureweb-1.0.6.3.jar, libgpkiapi_jni.jar( 표준 API) 라이브러리등록 2.2.2. WAS 환경설정 [ 현재많이사용되는 WAS 에대한예 ] 2.2.3. 웹보안 API 환경설정파일 가. $gpkisecureweb/conf/dsjdf.properties - 10 -
나. $gpkisecureweb/conf/gpkisecureweb.properties 다. ~(Web Root)/gpkisecureweb/client/var.js 라. ~(Web Root)/gpkisecureweb/client/GPKISecureWebNP.js $: 웹용표준 API 설치위치, ~(Web Root): 웹홈디렉토리 - 11 -
2.2.4. 설치방법가. 요구사항제공되는소프트웨어는 JAVA 및 WAS가설치된서버환경에서동작합니다. WAS Session을사용하므로 Session 유지설정이필요합니다. (Session 설정관련부분은 WAS 제조사에문의하시기바랍니다.) 나. 서버용표준보안 API 설치 서버용표준보안 API 가이드문서를참고하시기바랍니다. 다. 사용자용표준보안 API 설치 1) 파일설치위치 웹서버와 WAS 가분리된환경에설치할경우, 일반적인경우와같이 HTML, 자바스크립트, 이미지등정적인콘텐츠는웹서버에설치하고서버스크립트및 라이브러리관련파일은 WAS 에설치합니다. 예제에적용된환경 2) GPKI 사용자용표준보안 API 설치 (1) 패키지압축해제 암호체계고도화가적용된자바용 GPKI 사용자용표준 API 패키지의압축 파일이름형식은아래와같습니다. - 12 -
(2) 서버라이브러리및환경정보를제외한파일 gpkisecureweb/web-inf 디렉터리를제외한 gpkisecureweb 디렉터리및하위 디렉터리를 WAS 의가상호스트루트경로아래로복사합니다. 예제환경에설치할경우, 설치후아래와같은경로를가집니다. gpkisecureweb/client 디렉터리를 WAS 의가상호스트루트경로아래로 복사합니다. ( 상용환경에는데모페이지의구성인 gpkisecureweb/jsp, gpkisecureweb/css, gpkisecureweb/image 디렉터리는복사하지않습니다.) 라. 클라이언트프로그램환경설정 (var.js) 1) 사용자 PC 에배포하는프로그램환경 클라이언트환경설정을위한자바스크립트파일 은아래경로에있습니다 파일의게시위치 실행옵션을설정할수있습니다 2) 필수환경설정 (1) aspxxssvaildate ASP.net 환경에서암호화데이터태그 <gpki:encrypted DATA></gpki:ENCRYPTED DATA> 의 <> 기호가 IIS 서버에서공격으로인식되는문제를막기위해 <> 를 < >로교체합니다. (2) host host 설정의경우설정할필요없습니다. - 13 -
(3) serveraddr 서버의기본경로. host 등록된경로로설정됩니다. (4) ServerLangExt 서버개발언어에따른서버스크립트파일의확장자를지정합니다. 가상키보드사용및데모사이트의코드에서사용되는변수입니다. (5) gpkiscriptbase 클라이언트설치프로그램의위치및자바스크립트의위치를결정하기위한기본경로를지정하는데사용됩니다. 매뉴얼의설치예에따라WAS의가상호스트루트경로 ( / ) 에 GPKI 사용자용표준API 의 gpkisecureweb/client 디렉터리를복사할경우, gpkiscriptbase의설정값은 /gpkisecureweb/client 이됩니다. (6) clientmodulepath 클라이언트설치프로그램의위치를지정합니다. 일반적인경우 gpkiscriptbase 경로의 /setup 디렉터리아래에클라이언트설치프로그램이위치합니다. (7) ServiceStartPageURL 클라이언트설치페이지에서설치가완료된후돌아갈메인페이지의경로를지정합니다. - 14 -
(8) clientinstallpath 클라이언트설치프로그램을배포하는페이지의경로를지정합니다. (9) smartcertuse 인증서선택창저장매체의스마트인증사용여부입니다. (10) mobileuse 인증서선택창저장매체의휴대폰사용여부입니다 (11) storagecount 인증서선택창에출력할저장매체의갯수입니다 (12) tokendriversetuppage 인증서저장매체를보안토큰이용시필요한구동프로그램다운로드경로입니다. (13) versionuse 인증서선택창하단에클라이언트 (cs) 버전정보출력여부입니다. (14) passwordcount 인증서선택창에서비밀번호입력가능횟수이며, 횟수이상입력시인증서선택창이닫힙니다. - 15 -
(15) checkcount 사용자가입력한비밀번호횟수를저장하는변수입니다. 수정할필요가없습니다. (16) submitusedn 비밀번호오류입력이입력가능횟수이상인경우인증서의사용자DN을서버로전송할지여부입니다. (17) userdn 비밀번호입력횟수초과시사용된인증서의사용자DN을저장하는변수입니다. 수정할필요없습니다. (18) WorkDir 클라이언트프로그램을설치할 Windows PC의폴더이름을지정합니다. GPKISecureWebNP 로고정된값을사용하며, 수정할필요없습니다. (19) clientversion 클라이언트프로그램의버전입니다. 버전정보는. 로자리를구분합니다. (20) CsUrl 클라이언트프로그램과스크립트가통신하는주소입니다. (21) CsPort 클라이언트프로그램과스크립트가통신하는주소입니다. (22) Version API 버전입니다. 수정할필요없습니다. (23) setsessiontimeout 클라이언트와브라우저간세션유지시간입니다. - 16 -
(24) iscookie 쿠키를이용하기위한설정입니다. (25) session 클라이언트와브라우저간생성되는세션입니다. 스크립트에서자동생성되므로설정할필요가없습니다. (26) ServiceID 클라이언트와브라우저간통신을위한 id입니다. (27) SiteID 세션정보를관리하는고유ID입니다. (28) ServerCert 기관에발급된서버인증서를지정합니다. 이인증서는 base64 형식으로 인코딩되어있으며, 세셩키교환및데이터암호화에사용됩니다. (29) AlgoMode 클라이언트와서버간데이터교환시사용할대칭키암호알고리즘을지정합니다. SEED, ARIA 알고리즘을사용할수있습니다. 이알고리즘은서버측환경파일, gpkisecureweb.properties 의대칭키암호알고리즘설정 (GPKISecureWeb.crypto.algo) 에 지정한대칭키암호알고리즘값과일치해야합니다. ㅅ - 17 -
(30) HashAlo 클라이언트프로그램에서사용할해쉬알고리즘을지정합니다. SHA256 알고리즘만 지원합니다. (31) GNCertType 사용가능한인증서도메인 (GPKI 또는 NPKI) 을설정합니다. (32) ReadCertType 클라이언트가읽어들일인증서의종류 ( 서명용또는암호화용 ) 를지정합니다. (33) smartcardtype 지원하는스마트카드의종류를지정합니다. (34) CertOption 전자서명시에사용할인증서의종류를지정합니다. 전자서명시에인증서목록창에 표시할인증서를 ( 인터넷뱅킹시이체과정과유사하게 ) 로그인시에사용한인증서로 한정하거나, 사용자 PC 에저장된인증서중설정된인증서종류 (ReadCertType) 과 인증서로드정책 (ValidCertInfo) 에부합하는모든인증서를읽어서목록에표시할수 있습니다. - 18 -
(35) phoneopt 휴대폰인증서저장매체 (UbiKey) 사용여부를지정합니다. (36) keysecopt 입력보안설정 (37) keyboardsecopt 키보드보안제품설정 (38) langopt 인증서사용자인터페이스에적용된언어입니다. (39) servercharenc 서버의인코딩설정입니다. - 19 -
3) 옵션설정 다음은클라이언트프로그램에대한옵셜설정사항입니다. (1) VaildCertInfo 특정정책의인증서만허용할경우, 인증서정책 OID 를지정합니다. 인증서정책 OID 가여러개일경우 로연접합니다. (2) UbikeyVersion 휴대폰인증서저장매체 (UbiKey) 클라이언트프로그램의버전을설정합니다. (3) UbikeyPopuoURL 휴대폰인증서저장매체 (UbiKey) 클라이언트프로그램의게시위치를지정합니다. (4) UbikeyWParam 휴대폰인증서저장매체 (UbiKey) 서비스를사용하는기관의 ID 를지정합니다. 반드시 인포바인에서발급받은값을지정하십시오. (5) UbikeyCompany 휴대폰인증서저장매체 (UbiKey) 서비스를사용하는인증서사용자인터페이스의제작사. GPKI 인증센터에서배포한제품을사용함을 인포바인에알리고, 발급받은값을 지정하십시오. - 20 -
(6) UbikeyKeyboardSec 휴대폰인증서저장매체 (UbiKey) 클라이언트프로그램에서사용할키보드보안솔루션의종류. 인포바인의안내에따라설정하십시오. (7) LogoURL 인증서선택창상단에들어갈로고이미지경로입니다. - 21 -
2.2.5. 함수 ( 웹보안API) 가. 필요사항 1) 스크립트링크기능함수사용을위해서는함수를호출하는페이지에스크립트링크가포함되어야합니다. [GPKISecureWeb 인증서검증 UTF-8 버전 ] [GPKISecureWeb 인증서검증 EUC-KR 버전 ] - 22 -
2) 서버세션생성 암호화사용을위해서서버에서생성한세션이필요합니다. 하단의코드를이용하여 세션을생성합니다. 3) challenge 생성 Reply Attack 방지를위해서버에서생성하는값입니다. 하단의코드를이용하여 challenge 를생성합니다. 4) 가상키보드 (1) 페이지진입시가상키보드를초기화하는함수를호출합니다. (2) 전송될 form 안에 id = keysec 으로키보드사용여부를체크합니다. (3) /gpkisecureweb/jsp/ 경로에다음의페이지를복사합니다. - requestsecurekeyboard.jsp - makedskeysecure.jsp - pleasedskeysecure.jsp 샘플페이지와같은경로에있으므로샘플삭제시유의하시기바랍니다. - 23 -
나. 함수목록 1) rungpki() GPKI 사용자용표준보안 API 클라이언트 (EXE) 사용을위해설치체크를진행. 설치체크 중임을나타내는팝업과인스톨체크가함께동작 2) GPKISecureWeb.InitCheck() GPKI 사용자용표준보안 API 클라이언트 (EXE) 실행여부체크 3) GPKISecureWebUi.Installcheck() GPKI 사용자용표준보안 API 클라이언트 (EXE) 실행여부체크및버전확인 GPKISecureWeb.InstallCheckCount 에설정된숫자만큼설치체크후 EXE 와통신이되지 않으면설치팝업출력, EXE 와통신후버전체크후 var.js 에기재된버전보다낮으면 다운로드팝업출력 4) GPKISecureWebUi.Init() GPKI 사용자용표준보안 API 클라이언트 (EXE) 의초기화진행 5) GPKISecureWebUi.downLoadFile() 설정된경로에있는 EXE 파일을다운로드 - 24 -
6) GPKISecureWebUi.setupCheck() EXE 파일을다운로드후설치, 실행체크및버전확인 7) Login(target, form, isembedded) form 객체를이용한로그인. popup 형태의인증서선택창을이용하여사용자인증서를 선택할수있으며, form 객체를파라미터로받아로그인메시지를생성하여서버에전송. 로그인후보안세션구성을위한세션키도암호화하여서버와공유. 8) LoginEmbedded(form) form 객체를이용한임베디드로그인. 브라우저에 Embedded 된형태로인증서선택창이 제공되며, form 객체를파라미터로받아로그인메시지를생성하여서버에전달. 로그인 후보안세션구성을위한세션키도암호화하여서버와공유. - 25 -
9) LoginLink(link) URL 링크를이용한로그인. popup 형태의인증서선택창을이용하여사용자인증서를 선택할수있으며, URL Link 를파라미터로받아로그인메시지를생성하여서버에전달. 로그인후보안세션구성을위한세션키도암호화하여서버와공유. 10) EnvelopedSignData(target, form) 전달받은 Form 객체내파라미터에대해전자서명후서버인증서를이용하여공개키 암호화메시지를생성. 서버로전송되어복호화후서명검증. 11) EnvelopData(form) 서버인증서검증후보안세션구성을위한세션키를교환. Form 객체내파라미터로 받아로그인메시지를생성하여서버로전송. Form 객체내파라미터에대한암호화 지원 - 26 -
12) SignedDataForm(target, form) 전달받은 Form 객체내파라미터값들에대해전자서명메시지생성후서버로전송. 서버에서는전자서명검증을통해절달파라미터의위변조여부를확인. 13) SignedData(target, form) 전달된파라미터에대해웹브라우저에서전자서명데이터를생성생성된전자서명 데이터는결과값으로리턴 14) EncryptedSignData(target, form) 클라이언트에서생성한암호화된전자서명메시지를서버에서복호화한후전자서명 유효여부를확인. - 27 -
15) Encrypt(form) from 객체에포함된파라미터를암호화하여서버로전송. 16) Decrypt(encData) 보안세션형성후클라이언트와서버간공유된세션키를이용하여서버에서암호화된 메시지를클라이언트에서복호화. 17) EncryptLink(link, issubmit, sessionid) URL Link 에포함된파라미터를암호화하여 URL Target 위치로전송. 18) Logout() 로그인정보, 세션키를삭제하고현재세션종료 - 28 -
다. 설치체크 1) 사용자 pc 에클라이언트프로그램 (GPKISecureWeb) 미설치인경우, 제공함수 (rungpki) 를이용하여프로그램을설치합니다. 2) 설치시설치페이지로이동하여프로그램을다운로드및설치하며, GPKISecureWebNP.js 에서다운로드페이지등경로설정을합니다. [ GPKISecureWebNP.js 설정사항 ] 3) 콜백함수 (1) GPKISecureWeb.setupCheckCallback 인증서검증 EXE의설치가완료된후호출되는함수입니다. 설치체크를수행하는페이지 (rungpki() 함수를실행하는페이지 ) 에함수명 (GPKISecureWeb.setupCheckCallback) 으로선언하여설치완료후수행해야하는로직을작성합니다. 아래목차 4) Sample Code 의 (3) Callback 함수예제를참고하시기바랍니다. 사용하지않는경우함수를선언하지않습니다. - 29 -
4) 샘플코드 (1) 로그인페이지 로그인버튼클릭후 EXE 가실행되어있으면인증서선택창출력한다. EXE 가실행되어있지않거나설치되어있지않으면설치체크를진행한다. 설치체크가끝난후버튼클릭시인증서선택창출력 [ 버튼클릭후설치체크및로그인 Sample Code] (2) install page 를이용한다운로드 설치체크후출력되는팝업에서설치클릭시인스톨페이지로이동한다. 샘플에서제공된인스톨페이지외에다른인스톨페이지를이용할경우아래의함수를 이용하여파일다운및설치체크를진행한다. 함수의자세한설명은아래함수설명을참고한다. (3) Callback 함수이용 GPKISecureWeb.setupCheckCallback 인증서검증 EXE 설치완료수행할동작을 GPKISecureWeb.setupCheckCallback 함수명으로생성한다. 콜백함수는 rungpki() 함수위에선언한다. - 30 -
5) 동작확인 (1) 설치체크진행 (2) 팝업에서설치버튼클릭 (3) 설치페이지로이동후 EXE 다운로드 (4) 다운받은 EXE 를클릭하여설치진행 (5) 설치완료후 returnindexpage 에설정된페이지로이동 (6) 로그인버튼클릭시인증서선택창출력 - 31 -
6) 비밀번호입력횟수체크 (1) var.js 설정 다음의두변수에값을설정합니다. - passwordcount 인증서선택창에서비밀번호오류입력이설정한횟수에도달시인증서선택창이 닫힙니다. - submitusedn 비밀번호오류입력이설정한횟수에도달하면인증서의사용자 DN 을서버로전송할지 여부입니다. (2) 서버에서사용자 DN 확인 (3) submitusedn = true 로설정한경우서버에서비밀번호입력횟수에도달한인증서의 사용자 DN 을확인할수있습니다. (4) /gkisecureweb/jsp/createsecuresession_1_1_response_checkpassword.jsp 파일명을 createsecuresession_1_1_response.jsp 로변경하면해당오류코드및사용자 DN 값을 확인할수있습니다. [ 검증페이지예제 ] 라. 발급자명변경 (Issuer.js) /gpkisecureweb/client/ui/issuer.js 파일에인증서의 CN과해당명칭이정의되어있습니다. 발급자명의변경 / 추가가필요한경우 CN을확인하여해당명칭을변경 / 추가합니다. 여러개의 CN이같은명칭을사용하는경우도있습니다. 예 ) 발급자를행정자치부 -> 행정안전부로변경 - 32 -
2.2.6. 키보드보안연동 (INCA) 인증서선택창에키보드보안적용시키보드보안프로그램이선행하여실행되어있어야합니다. 인증서검증모듈설정 (var.js) 에 " 키보드보안 " 으로되어있는경우, 키보드보안프로그램이정상동작하지않으면인증서검증 EXE도사용할수없습니다. 키보드보안프로그램관련설정은키보드보안프로그램개발사에서제공한매뉴얼을확인합니다. 가. 설정변수 (var.js) 아래의두변수를 /gpkisecureweb/client/var.js 에설정합니다. 팝업을이용한인증서선택창사용시아래의두변수설정만으로키보드보안을사용할수있습니다. - 키보드보안연동시설정항목 : keysecopt, keyboardsecopt 임베디드로그인의경우키보드보안에서제공한가이드에맞춰작업해야합니다. 비밀번호입력시암호화되어야합니다. 키보드보안적용방법에대해서는키보드보안제품매뉴얼을참고합니다. 아래의샘플페이지를이용하여테스트를진행합니다. - 샘플페이지 /gpkisecureweb/jsp/createsecuresession_1_5.jsp ( 팝업 ) /gpkisecureweb/jsp/createsecuresession_1_6.jsp ( 임베이드 ) /gpkisecureweb/jsp/createsecuresession_1_7.jsp ( 링크 ) 나. 샘플코드 해당샘플은키보드보안업체에서제공한것이며, 키보드보안제품및버전별로 다를수있으므로키보드보안업체에서제공한매뉴얼를이용하여설치체크를 진행합니다. - 33 -
다. 적용확인 인증서선택창에키보드보안이적용된경우, 비밀번호입력창이초록색으로 나타납니다. - 34 -
2.3. 웹보안 API ( 데모 ) 구동테스트 웹보안 API 는표준 API 가먼저설치되어있어야합니다. 2.3.1. 인증서로그인 가. 폼 (Form) 객체를이용한팝업로그인 보안세션요청 ( 로그인 ) 클릭시인증서선택창이뜨면정상동작 초기페이지에서키보드보안가상키보드선택시인증서선택창에가상키보드가 출력되면정상동작 - 35 -
나. 폼 (Form) 객체를이용한임베디드로그인 인증서선택 패스워드입력후보안세션요청 ( 로그인 ) 클릭시결과페이지로 이동하면정상동작 - 36 -
다. 링크 (URL Link) 를이용한로그인 보안세션요청 ( 로그인 ) 클릭시인증서선택창이뜨면정상동작 - 37 -
2.3.2. 서버인증서인증후보안세션만들기 가. 보안세션생성 보안세션요청 ( 로그인 ) 클릭시결과페이지로이동하면정상동작 - 38 -
2.3.3. 보안세션 ( 세션키 ) 을이용한암호메세지생성및처리 가. 폼 (Form) 객체파라미터암호화하기 (Encrypt) 보안세션암호화클릭시결과페이지로이동하면정상동작 나. 링크 (URL Link) 내파라미터암호화하기 (EncryptLink) 보안세션암호화클릭시결과페이지로이동하면정상동작 - 39 -
다. 서버에서암호화메시지만들어클라이언트에서복호화하기 서버에서만든암호메시지보기클릭시경고창이출력되면정상동작 - 40 -
2.3.4. 전자서명메시지 ( 위변조방지 ) 가. 평문메시지에전자서명하기 (SignedData) 서명할데이터를입력후전자서명메시지생성클릭시인증서선택창이뜨면정상동작인증서선택창에비밀번호를입력후확인버튼클릭시전자서명데이터에값이들어오면정상동작 전자서명메시지전송클릭후결과페이지로이동하면정상동작 - 41 -
나. 폼 (Form) 객체파라미터에전자서명하기 (SignedDataForm) 전자서명메시지전송클릭시인증서선택창이뜨면정상동작 다. 보안세션으로전자서명메시지보고하기 (EncryptedSignData) 암호화된전자서명클릭시인증서선택창이뜨면정상동작 인증서선택 비밀번호입력후확인클릭시결과페이지로이동하면정상동작 - 42 -
라. 서버인증서를이용하여더강력한전자서명메시지 보고하기 (EnvelopedSignData) 암호전자서명메시지전송클릭시인증서선택창이뜨면정상동작 인증서선택 비밀번호입력후확인클릭시결과페이지로이동하면정상동작 - 43 -
2.3.5. 로그아웃 현재세션을종료 (Logout) 클릭시초기화면으로넘어가면정상동작 2.3.6. 에러대처방안 가. 올바른경로에파일이존재하는경우에도아래와같은에러가뜨는경우 dsjdf.properties 와 lib 설정이 WAS 의 runtime 옵션에설정되어있는지 확인합니다. 나. 인증서선택창이뜨지않는경우 1) 함수의필수파라미터가입력되어있는지확인합니다. 각함수의필수파라미터는 2.2.5. 함수를참고하시기바랍니다. 2) 인코딩이통일되어있는지확인합니다. - 44 -
3. 에러코드 Exception 발생시, 에러메시지에포함되어있는에러코드는 1000번부터 ~ 5000번까지 나올수있으며, 에러코드범위별로다음과같은의미를가지고있습니다. ( 자세한내용은표준API javadoc 폴더의 html 문서확인 ) 3.1. 클라이언트 (CS) 에러 - 45 -
- 46 -
3.2. 스크립트에러 스크립트에러메시지의경우 GPKIErrorText.js에서변경및추가가능합니다. - 47 -
붙임 1 표준 API 샘플프로그램코드 가 ) 표준 API 가이드참조 java : ~/gpkiapiv1.5.1/javadoc/index.chm C : ~gpkiapiv1.5.1/doc/manual.pdf 나 ) 웹보안 API 가이드참조 ~/gpkisecureweb/doc/ 웹용표준 API_ 매뉴얼 ( 유선 )_v2.0.1.0.chm 다 ) 인증서 Base64Encoding 라 ) Ldap 에서인증키를구하기 - 48 -
붙임 2 신규표준 API 교체방법 [ 버전 1.3.0.0 1.4.0.0/1.5.x] 컴퓨팅기술의급속한발달로인해기존인증서암호알고리즘의안전성이저하되어보다고도화된암호알고리즘이요구됨으로전자서명키길이상향조정, 해쉬알고리즘교체등인증서암호체계고도화적용에따라표준API 변경에대한내용을기술함 ( 기설치한표준API를새로배포하는표준API 로재설치 ) 가 ) 라이브러리변경 기존라이브러리백업또는삭제후새로배포하는라이브러리복사 라이브러리변경후가이드의 1.7.4 표준 API 구동테스트필수 나 ) 라이센스추가인증체계고도화에따라재배포이전의표준API 설치운영시스템은신규표준API 와같이배포되는라이센스를추가하여야합니다. 디렉토리위치 ( 라이센스파일, gpkiapi.lic) 는표준API 설치위치의 conf 디렉토리에복사 A) 표준API B) 웹보안API 행정전자서명적용시스템운영서버1식 (IP) 에라이센스 1개적용합니다. - 49 -
붙임 3 로그인용웹보안 API 필수설정사항및가이드 로그인용웹보안API를통해 OCSP, SCVP(IVS) 검증을예정하고있는경우, 웹보안 API 환경설정중아래파일의설정을권고한다. gpkisecureweb.properties 에설정한서버인증서와 var.js에설정한서버인증서 base64 값이다를경우, 1507 에러등발생 가 ) gpkisecureweb.properties A) 암복호화용키쌍설정 - GPKISecureWeb.CertFilePathName 암복호화용인증서 예 의서버내전체 절대경로를입력한다 예 - GPKISecureWeb.PrivateKeyFilePathName 암복호화용개인키 예 의서버내전체 절대경로를입력한다 예 - GPKISecureWeb.PrivateKeyPasswd 인증서개인키암호를기입한다 예 B) 서명용키쌍설정 - GPKISecureWeb.SignCertFilePathName 서명용인증서 예 의서버내전체 절대경로를입력한다 예 - GPKISecureWeb.SignPrivateKeyFilePathName 서명용개인키 예 의서버내전체 절대경로를입력한다 예 - 50 -
- GPKISecureWeb.SignPrivateKeyPasswd 인증서개인키암호를기입한다 예 나 ) var.js 사용자가웹페이지접속시 var.js 에선언된내용통해암복호화용인증서를받아가게되어있으므로, 인증서의 Base64값을수정해야하며, 인증서가재발급 / 갱신등으로변경된경우재수정이필요하다. A) 암복호화인증서 X.509 Base64 형식으로변환방법 - 인증서열기 ( 더블클릭 ) 예 - 자세히탭클릭후 파일에복사 클릭 - 51 -
- 인증서내보내기마법사다음클릭 - Base 64 체크및다음클릭 - 52 -
- 파일이름지정후다음클릭 - 파일이름지정후다음클릭 - 내보내기완료후텍스트편집기등으로 Base64 인코딩값확인 B) ServerCert 변수설정 var ServerCert = '( 암복호화인증서의 Base64 값 )'; 형식으로수정한다. - 53 -