< 목차 > 표준 API 설치가이드 - 2017. 07. - 1. 표준API 1 2. 웹보안API 6 3. 에러코드 9 [ 붙임 1] 표준API 샘플프로그램 10 [ 붙임 2] 신규표준API 교체방법 12 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.2. 웹보안API 설치 6 2.2.1. 라이브러리등록 6 2.2.2. WAS 환경설정 6 2.2.3. 웹보안API 환경설정파일 7 2.3. 웹보안API Demo 구동테스트 8 행정전자서명인증관리센터 3. 에러코드 9 [ 붙임 1] 표준 API Sample 프로그램 10 [ 붙임 2] 신규표준 API 교체방법 [ 버전 1.3.0.0 => 1.4.0.0/1.5.x] 12
1 표준 API 1.1. 표준 API 개요 인터넷상에서공무원및행정기관신원확인, 전자문서위변조방지등을보장하고전자문서의안정적유통을위하여개발된 API입니다. 1.2. 표준 API 적용대상 각급행정기관 1.3. 용어 암호알고리즘 : 정보통신망에서소통되는중요전자문서의비밀성확보를위해원문암호화및복호화에사용되는방법및절차. 전자서명 : 전자문서의작성기관및변경여부를확인할수있도록전자서명알고리즘을이용하여개인키로생성한정보로서당해전자문서에고유한것. 개인키 : 전자서명을생성하기위하여이용하는소유자만사용할수있는전자적정보. 공개키 : 개인키에의해생성된전자서명을검증하기위하여이용하는전자적정보. 인증서 : 공개키가기관또는담당자가소유하는개인키에합치된다는사실등에대하여행정인증기관이확인 증명하는전자적정보 1.4. 표준 API 종류 배포모듈명 배포버전 표준API ( gpkiapiv1.5.1 ) V1.5.1 개발언어운영체제 / WAS 98 2000 2003 Windows XP Vista Windows7 11.00 11i HP-UX 11.11 11.23 ia64 AIX 4.3 C++/JAVA AIX 5.1 IBM AIX 5.2 AIX 5.3 Solaris 5.8 Solaris 5.9 Sun OS Solaris 5.10 Solaris 5.10 (intel계열cpu) Kernel 2.4.x Kernel 2.6.x Linux ia64 32bits 32bits 개발중 웹보안 API ( gpkisecureweb.v1.0.1.5 ) V1.5 ASP JSP Unixware 7.1.2 32bits Windows IIS, Tomcat, JEUS 등 Weblogic 8.X 9.X, JEUS 4.X 5.X Websphere, Tomcat 4.X 5.X 6.X 등 - 1 - - 1 -
1.5. 표준 API 디렉토리구조 구분 ( 폴더 ) 파일명 conf gpkiapi.conf 인증서검증에필요한정보포함환경파일 gpkiapi.lic 표준API 라이센스 info gpkiaip_info 표준API 버전을확인할수있는프로그램 jar libgpkiapi_jni.jar 표준API jar 파일 javadoc 표준API 설치적용가이드 (html) /java 테스트 Sample 자바코드표준API jtest /class 테스트 Sample 실행파일 (v1.5.1) gpkiapi.dll 윈도우용 libgpkiapi.so Sun, Linux, UnixWare lib / lib64 libgpkiapi.a IBM AIX libgpkiapi.sl HP UX 기타 Ldap 라이브러리등표준API에서참조하는라이브러리파일 Sample jtest 또는 ctest시테스트파일 1.6. 표준 API 기능 기능 인증서정보확인모듈 X.509 인증서의주요필드정보확인 개인키모듈 인증서소유자의중요한정보인개인키의암호화 / 복호화 저장매체모듈 인증서개인키를저장매체로부터읽기, 저장, 삭제 유선용전자서명, 암호메세지생성 / 처리모유선환경에서보안서비스를제공하기위해서사용하는 듈 보안메시지생성 / 처리 무선용전자서명, 암호메세지생성 / 처리모무선환경에서보안서비스를제공하기위해서사용하는 듈 보안메시지생성 / 처리 시점확인서비스이용모듈 시점확인서버를이용하여특정메시지에대한시점확인토큰발급받음 인증서내정보를이용한본인확인모듈 인증서내에포함되어있는정보를이용하여인증서소유자에대한보인확인 보안알고리즘모듈 다양한보안서비스제공을가능하게하기위한보안알고리즘 BASE64 모듈 BASE64 인코딩 / 디코딩 디렉토리접근모듈 인증서와인증서폐지목록과같은디렉토리서버에게시되어있는데이터획득 객체인증모듈 상대방을확인하기위한객체인증프로토콜 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 라이브러리환경설정 - 라이브러리경로설정 C/C++ 용표준API 와 LDAP 라이브러리가위치해있는경로를환경변수에 등록합니다. 내컴퓨터 => 속성 => 고급 => 환경변수 에서기존 path" 변수에 라이브러리가 설치된디렉토리 를설정합니다. Windows 인경우 C 또는 TC shell setenv LD_LIBRARY_PATH=" 라이브러리가설치된디렉토리 Solaris, Unix, Unixware Corn shell export LD_LIBRARY_PATH=" 라이브러리가설치된디렉토리 LD_LIBRARY_PATH=" 라이브러리가설치된디렉토리 export LIBPATH C 또는 TC shell setenv LIBPATH=" 라이브러리가설치된디렉토리 Corn shell export LIBPATH=" 라이브러리가설치된디렉토리 IBM AIX LIBPATH=" 라이브러리가설치된디렉토리 export LIBPATH C 또는 TC shell setenv SHLIB_PATH=" 라이브러리가설치된디렉토리 Corn shell export SHLIB_PATH=" 라이브러리가설치된디렉토리 HP UX SHLIB_PATH=" 라이브러리가설치된디렉토리 exprot SHLIB_PATH - 2 - - 3 -
- classpath 설정 ( 자바사용할경우 ) java용표준api의 libgpkiapi_jni.jar 가위치해있는경로를환경변수에등록합니다. 내컴퓨터 => 속성 => 고급 => 환경변수 에서기존 CLASSPATH" 변수에 라이브러리가설치된디렉토리 ( 절대경로 )/libgpkiapi_jni.jar;." 를설정합니다. 1.7.4. 표준 API 구동테스트 - command 창실행 => sample 프로그램이동 (java) => java Main 실행 Windows 인경우 Solaris, Unix, Unixware IBM AIX HP UX C 또는 TC shell Corn shell C 또는 TC shell Corn shell C 또는 TC shell Corn shell setenv CLASSPATH=" 라이브러리가설치된디렉토리 export CLASSPATH=" 라이브러리가설치된디렉토리 CLASSPATH=" 라이브러리가 설치된 디렉토리 export CLASSPATH setenv CLASSPATH=" 라이브러리가설치된디렉토리 export CLASSPATH=" 라이브러리가설치된디렉토리 CLASSPATH=" 라이브러리가 설치된 디렉토리 export CLASSPATH setenv CLASSPATH=" 라이브러리가설치된디렉토리 export CLASSPATH=" 라이브러리가설치된디렉토리 CLASSPATH=" 라이브러리가 설치된 디렉토리 export CLASSPATH [sample 프로그램실행 ] - 4 - - 5 -
2 웹보안 API 2.1. 웹보안 API 디렉토리구조 구분 ( 폴더 ) certs 서버인증서, 개인키파일이위치하는디렉토리이며, 클라이언트와의암호키교환시사용디렉토리. conf 환경설정파일디렉토리 ( 라이센스포함 ) gpkisecureweb demo 데모 Sample 디렉토리 doc 웹보안API 매뉴얼디렉토리 (v.1.0.1.5) 클라이언트에배포되는설치관련프로그램 (ActiveX, 보안프로 gpkisecureweb 그램 ) 디렉토리 lib 서버라이브러리디렉토리 log 2.2. 웹보안 API 설치 2.2.1. 라이브러리등록 로그디렉토리 - gpkisecureweb.jar, libgpkiapi_jni.jar( 표준 API) 라이브러리등록 WAS 구분 Tomcat JEUS WebLogic 2.2.2. WAS 환경설정 1) Tomcat 설치위치 $TOMCAT_HOME/shared/lib $JEUS_HOME/lib/application $WEBLOGIC_HOME/lib - $Tomcat_HOME/bin/catalina.sh 또는 Catalina.bat 에아래부분을추가합니다. set JAVA_OPTS="-Dcom.dsjdf.config.file=/gpkisecureweb/conf/dsjdf.properties" 2) JEUS - $Jeus_HOME/config/$hostname/JEUSMain.xml 파일에아래부분을추가합니다. <command-option> -Dcom.dsjdf.config.file=/gpkisecureweb/conf/dsjdf.properties </command-option> 3) WebLogic - $WebLogic_HOME/workshop/workshop.sh 또는 workshop.cfg 파일에아래부분을추가합니다. /bea/java141_05/jre/bin/java "-XX:-UseThreadPrioritite -Xmx256m -Xms64m -client -Djava.system.class.loader="workshop.core.AppClassLoader" -Dcom.dsjdf.config.file="/gpkisecureweb/conf/dsjdf.properties" [ 현재많이사용되는 WAS 에대한예 ] 2.2.3. 웹보안 API 환경설정파일 $gpkisecureweb/conf/dsjdf.properties $gpkisecureweb/conf/gpkisecureweb.properties ~(Web Root)/gpkisecureweb/install.html ~(Web Root)/gpkisecureweb/client/var.js ~(Web Root)/gpkisecureweb/client/GPKIFunc.js - $gpkisecureweb/conf/dsjdf.properties logger.dir=[gpkisecureweb]/log 항목 ( 변수 ) pbf.propertiesfile=[gpkisecureweb]/conf/gpkisecureweb.prop erties - $gpkisecureweb/conf/gpkisecureweb.properties 항목 ( 변수 ) GPKISecureWeb.crypto.algo=SEED/CBC GPKISecureWeb.errorPage=/gpkisecureweb/GPKIError.jsp $: 웹용표준 API 설치위치, ~(Web Root): 웹홈디렉토리 Log 관련경로지정 프로젝트설정파일경로지정 암호알고리즘세팅 에러페이지설정 GPKISecureWeb.CertFilePathName= GPKI 서버인증서위치 ( 인증서파일, 인증서키파일, 비밀번호 ) 서버인증서는 GPKISecureWeb.PrivateKeyFileName= 행정안전부를통해발급받아설치후설정해야하며변경시 WAS 를재구동 GPKISecureWeb.PrivateKeyPasswd= 해야함. GPKISecureWeb.gpkiapi.ConfFilePath= GPKISecureWeb.AnyPolicy=yes GPKISecureWeb.Policy=1 2 410 20005 1 1 4 GPKISecureWeb.VerifyCertMethod=CRL OCSP IVS GPKISecureWeb.TrustedROOTCACert.count=2 표준 API gpkiapi.conf, gpkiapi.lic 파일이있는절대경로지정 인증서정책검증설정 인증서검증방법 ROOTCA 인증서의개수 GPKISecureWeb.TrustedROOTCACert.FilePathName.1=C:/g pkisecureweb/certs/npkirootca1.der ROOTCA 인증서의위치 (NPKI, GPKI) GPKISecureWeb.TrustedROOTCACert.FilePathName.2=C:/g pkisecureweb/certs/gpkirootca1.der - ~(Web Root)/gpkisecureweb/install.html <script language='javascript' src='/gpkisecureweb/var.js'></script> <script language='javascript' src='/gpkisecureweb/install.js'></script> - 6 - - 7 -
- ~(Web Root)/gpkisecureweb/client/var.js ServerCert = "MIID5..." 서버인증서세팅 : 서버용인증서 ( 암호용 ) 의 Base64Encode 값세팅 => [ 붙임1 참조 ] AlogMode = 0x30 암복호화알고리즘 ( 0x20:3DES, 0x30:SEED, 0x40:NEAT, 0x50:ARIA ) CNCertType = 0x00 인증서사용자인터페이스에로딩할인증서종류세팅 ( GPKI, NPKI:0x03, GPKI:0x01, NPKI:0x02 ) ServerAddr = "10.1.1.1:8080" 웹서버 IP : Port CodeBase_GPKIInstaller = "CODEBASE='http://"+ServerAddr+"/gpkisecureweb/ 실제서비스를하는웹서버 IP:Port 설정및 gpkisecureweb/setup/gpkisecurewebx.cab#versio GPKIInstaller.cab 파일위치지정 n=2,0,2,1'"; var Object_GPKIInstaller = "<OBJECT ID ='GPKISecureWeb' CLASSID = 'CLSID:C8223F3A-1420-4245-88F2-D874FC081572' width=0height =0 "; Object_GPKIInstaller +=CodeBase_GPKIInstaller; GPKIInstaller ActiveX 지점 Object_GPKIInstaller +="></OBJECT>"; 2.3. 웹보안 API Demo 구동테스트 - ~(Web Root)/gpkisecureweb/client/GPKIFunc.js 항목 ( 변수 ) 인증서선택창발급기관명변경 * 웹보안 API 는표준 API 가먼저설치되어있어야합니다. - 8 - - 9 -
붙임 1 표준 API Sample 프로그램코드 3 에러코드 - Exception 발생시, 에러메시지에포함되어있는에러코드는 1000번부터 ~ 5000번까지나올수있으며, 에러코드범위별로다음과같은의미를가지고있습니다. ( 자세한내용은표준API javadoc 폴더의 html 문서확인 ) * 표준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 <%@ page import="com.gpki.gpkiapi.storage.disk" %> <%@ page import="com.gpki.gpkiapi.util.base64" %> <%@ page import="com.gpki.gpkiapi.cert.x509certificate" %> 에러코드범위 1000 ~ 1099 API 초기화와 API 사용중포괄적으로일어날수있는에러코드 1100 ~ 1199 라이센스검증과관련한에러코드 1200 ~ 1299 인증서검증과정보조회와관련한에러코드 1300 ~ 1399 개인키암 / 복호와와관련한에러코드 1400 ~ 1499 저장매체와관련한에러코드 1500 ~ 1599 유무선서명, 암호메시지와관련한에러코드 1600 ~ 1699 시점확인서비스와관련한에러코드 1700 ~ 1799 본인확인과관련한에러코드 1800 ~ 1899 보안알고리즘과관련한에러코드 1900 ~ 1999 BASE64 인코딩 / 디코딩과관련한에러코드 2000 ~ 2099 디렉토리서버 (LDAP) 과관련한에러코드 2100 ~ 2199 통합검증서버와관련한에러코드 4000 ~ 4099 객체인증프로토콜과관련한에러코드 <% String SERVER_KM_CERT_PATH = " 서버인증서파일경로 / 서버인증서파일 (SVR_env.cer)"; Base64 base64 = new Base64(); byte[] bbase64 = null; String strbase64 = ""; X509Certificate srvcert = Disk.readCert(SERVER_KM_CERT_PATH); bbase64 = srvcert.getcert(); strbase64 = new String(base64.encode(bBase64)); %> 나 ) Ldap에서인증서키를구함 <%@ page import="com.gpki.gpkiapi.gpkiapi" %> <%@ page import="com.gpki.gpkiapi.cert.x509certificate " %> <%@ page import="com.gpki.gpkiapi.util.ldap" %> <%@ page import="com.gpki.gpkiapi.storage.disk " %> <%@ page import="com.gpki.gpkiapi.util.base64 " %> <% GpkiApi.init("."); X509Certificate reccert1; Ldap ldap = new Ldap(); ldap.setldap("ldap 도메인 ",389); - 10 - - 11 -
// 인증키를 ldap에서구함 ldap.searchcn(ldap.data_type_km_cert," 서버인증서 ID"); byte[] sn=ldap.getdata() ; // 인증서 reccert1 = Disk.readCert(path); %> 붙임 2 신규표준API 교체방법 [ 버전 1.3.0.0 => 1.4.0.0/1.5.x] - 컴퓨팅기술의급속한발달로인해기존인증서암호알고리즘의안전성이저하되어보다고도화된암호알고리즘이요구됨으로전자서명키길이상향조정, 해쉬알고리즘교체등인증서암호체계고도화적용에따라표준API 변경에대한내용을기술함 ( 기설치한표준API 를새로배포하는표준API 로재설치 ) 1) 라이브러리변경 * 기존라이브러리백업또는삭제후새로배포하는라이브러리복사 구분 기존라이브러리 변경라이브러리 Windows gpkiapi.dll gpkiapi.dll gpkiapi_jni.dll Solaris, Linux, Unixware liblber.so libgpkiapi.so libgpkiapi.so libgpkiapi_jni.so IBM AIX libgpkiapi.a libgpkiapi.a libgpkiapi_jni.a liblber.sl liblber.sl HP UX libgpkiapi.sl libgpkiapi.sl libgpkiapi_jni.sl WAS libgpkiapi_jni.jar libgpkiapi_jni.jar gpkisecureweb.jar gpkisecureweb.jar * 라이브러리변경후가이드의 1.7.4 표준API 구동테스트필수 2) 라이센스추가 - 인증체계고도화에따라재배포이전의표준API 설치운영시스템은신규표준API 와같이배포되는 라이센스를추가하여야합니다. - 디렉토리위치 ( 라이센스파일 : gpkiapi.lic ) 는표준API 설치위치의 conf 디렉토리에복사 가 ) 표준API ~/libgpkiapi/conf/gpkiapi.lic 나 ) 웹보안API ~/gpkisecureweb/conf/gpkiapi.lic * 행정전자서명적용시스템운영서버1식 (IP) 에라이센스 1개적용합니다. - 12 - - 13 -