이미지 출처: QZ Tray-2.0.10

📘 QZ Tray 무료 증명서 발급 및 적용

1. 시작하며

1.1 문제 정의

• 필자가 맞닥드린 문제는 다음과 같다.

• 성공적인 프로그램 설치 후, 프로그램 폴더 안에 있는 sample.html 웹 페이지 파일을 통해 테스트로 페이지를 출력하려고 시도 하자 다음과 같은 작업 확인 다이어로그가 띄워진다.
  

이미지 1.1_1: 어떤 함수든 QZ Tray를 사용하게 되면 매번 띄워지는 다이어로그

이미지 1.1_2: 'Certificate Information' 을 누르면 출력됨

2. 원하는 결과

• 이 작업을 통해서 우리 모두가 원하는 결과는 다음과 같다.

• 맨 처음 QZ Tray 에 사용자 증명서 정보와 함께 인증을 하고 해당 값을 기억할 수 있게 해주는 페이지를 볼 수 있게 해야 한다.

  

  이미지 2_1: 인증 성공

• 정상적인 인증이 완료되면, 'Certificate Information' 을 클릭 했을 때 다음과 같은 화면을 볼 수 있어야 한다.

  

  이미지 2_2: 인증 성공 인증 세부 사항

  자 그럼, 이제 증명서를 발급 하고 실 프로그램에 적용하는 방법을 알아보자.

3. 인증 방법

• 먼저, 다운 받은 QZ Tray 의 바이너리 폴더를 재인증 하고 리컴파일 하기위해 다음과 같은 설치가 필요하다.

3.1. 사전 설치 작업

1. JDK 7 혹은 이상 (14 이상은 QZ Tray 가 지원하지 않을 수 있음으로, 여기에서 QZ Tray 버전에 대한 Java 버전 지원을 확인한다.)

   • 필자는 여기서 Azul Zulu Open JDK 11.0.x 를 사용했다. (다운로드 링크 참고)

2. Apache Ant

   • 설치 후 환경변수를 등록함으로 cmd/terminal 에서 'ant --version' 이 확인이 가능하게끔 준비한다.
   • 필자 (윈도우) 다운로드 버젼: Apache Ant-1.10.12

3. NSIS 3.0x

   • 리컴파일 시 Ant 와 함께 필요한 프로그램이다.

4. (선택사항) Git

   • 사이트 다운로드에서 .tar 나 .zip 을 받거나,
     git 설치후 'git clone https://github.com/qzind/tray.git' 을 해도 된다.

5. OpenSSL

   • QZ Tray 바이너리 소스코드를 재 컴파일 하기 전, 사용자를 위한 새로운 인증서를 만들기 위한 프로그램이다.
   • 필자는 'Win64 OpenSSL v3.0.0.msi' 를 다운받아 설치했다.

* 다운 받은 qz-tray-2.0.10 의 압축 파일의 해제 경로가 주 경로가 될 것이니, 참고하여 경로를 지정하기 바란다.

* 필자는 C:\Utilities 라는 경로 아래 모든 작업을 진행했다.

3.2. 인증 작업

• 설치가 모두 완료 되었다면, cmd/terminal 을 열고 openssl 을 통해 암호 파일을 만든다.
• 해당 구문을 실행하는 곳이 암호 파일들이 생성될 곳 임으로, 위치를 지정하고 싶다면 cmd/terminal 에서 'cd ' 명령어로 원하는 위치에서 입력하기 바란다.

3.2.1. 암호키 생성

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 11499 -nodes

• key.pem 은 private key 의 값을 담을 파일명을 정의
• cert.pem 은 certificate key 의 값을 담을 파일명을 정의
• days 11499 는 입력 가능한 최댓값으로 5년 이다.

• 위 명령어를 입력하고 아래의 값을 순서에 따라 입력한다. (아래는 필자가 입력한 값이다.)

  '..+..+..........+.....+.+..................+..+.......+..+...+......+.+...+...........+....+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++...'
  //// (--를 대체)
  You are about to be asked to enter information that will be incorporated
  into your certificate request.
  What you are about to enter is what is called a Distinguished Name or a DN.
  There are quite a few fields but you can leave some blank
  For some fields there will be a default value,
  If you enter '.', the field will be left blank.
  ////
  Country Name (2 letter code) [AU]: KR
  State or Province Name (full name) [Some-State]: Seoul
  Locality Name (eg, city) []: Seocho-gu
  Organization Name (eg, company) [Internet Widgits Pty Ltd]: AWS Ltd.
  Organizational Unit Name (eg, section) []: IT
  Common Name (e.g. server FQDN or YOUR name) []: *.aws.com
  Email Address []: dev.jongjinkim@gmail.com

  • 중요!!: Common Name 을 입력할 때는, '*' 과 같은 와일드 카드 포맷을 따라 다음과 같이 정의 하는데, 운영하는 웹 페이지의 도메인 명을 기준으로 해야한다.
    예) *.naver.com *.google.com *.velog.io *.kakao.com

• 위 작업을 마치면, 해당 폴더에 두개의 암호 파일이 생성된 것을 확인할 수 있다.
• 이제 생성된 파일에 대해 아래와 같은 암호문 변경을 진행한다.

3.2.2. 암호키 변경

openssl pkcs12 -inkey key.pem -in cert.pem -export -out privateKey.pfx

• 여기서 입력하는 비밀번호는 안전한 비밀번호로 설정할 것을 권고.

3.2.3. 생성된 암호키를 활용한 리컴파일

C:\Utilities\tray-2.0.10> ant nsis -Dauthcert.use="C:\Utilities\cert.pem"

꼭 기억하세요.

1. 필자는 위에서 설명한 것 처럼 ant 를 환경변수 등록을 해 놓았기에 'ant' 입력을 했습니다.
2. 위 리컴파일 명령어를 실행 위치는, QZ Tray.zip/tar 파일을 다운 받고 압축 해제 한 경로 안 입니다.

3.2.4. 컴파일 작업이 결과 모니터링

• 컴파일 결과가 실패할 수 있으니 결과에서 '' 가 나왔는지 확인한다.
• 컴파일 완료 후 컴파일 작업 폴더 내 /out 폴더와 함께 안에 '' 가 아래와 같이 생성되었는지 확인한다.
• 소요시간은 컴퓨터의 성능에 따라 상이하며, 약 50s ~ 5m 정도 소요된다.
• 처리 결과:

BUILD SUCCESSFUL
Total time: 1 minute 31 seconds

이미지 3.4_1: 설치 성공 화면_1

이미지 3.4_2: 설치 성공 화면_2

사진에서 보는 설치 응용 프로그램이 있어야 한다.

3.2.5. Demo 파일을 통한 테스트

1. 새로 생성된 qz-tray-community-2.0.10.exe 를 설치한다.
2. 설치가 완려되면 동일한 폴내에 있는 ../dist/demo/* 파일들을 가지고 테스트를 진행본다.
3. sample.html 을 웹 브라우저로 열어본다.
4. 열자마자 다음과 같은 화면을 보게 될거다.

   

   이미지 3.2.5_1: 허용되지 않은 사이트

   • 여기서 'Allow' 를 누르게 되면 이후에 모든 작업들에 대해서 계속 똑같은 확인 다이어로그가 나오게 된다.
   • 방지하기 위해 'Remember this decision' 을 누르게 되면 'Allow' 버튼을 누를 수 없게 되는데 이부분을 이제 해소해 보자.

     

   이미지 3.2.5_2: 인증 불가

   • Certificate information 을 눌러보면 아래와 같이 인증이 정상적으로 되지 않았음을 알 수 있다.
     

   이미지 3.2.5_3: 인증 불가 세부 내용

   • Block 을 누르게 되면 사용자 삭제 후 'Allow' 를 통해 다시 등록 해줘야 하니 주의 하자.
     3.2.5.5. 이 상태로는 아직까지 실무에 사용할 수 없고, 일반 설치 과정과 동일하게 했을 때와 같은 문제를 야기하기 때문에 다음으로 넘어가서 해소해보자.

3.2.6. 인증 허용 작업

• 지금 현재 sample.html 이 있는 폴더에서 소스코드 몇가지를 조금 바꿔보자.

1. 먼저 'jsrsasign-all-min.js' 를 '..\tray-2.0.10\out\dist\demo\js\dependencies' 에 추가한다.

2. 그리고 이제 sample.html 를 수정할 것인데, 먼저 앞서 추가한 js 파일을 html 에서 불러올 수 있도록 경로를 등록해 준다.

   • 필자는 'jsrsasign-all-min.js' 의 소스코드를 가져와서 파일로 만든 후 프로젝트에 직접 등록 했다.
     

   이미지 3.2.6_1: jsrsasign-all-min.js 불러오기

   • 소스코드를 프로젝트에 담지 않고, 바로 가져오고 싶은사람은 아래와 같이 하면 된다.

   <script src="https://gist.github.com/tresf/f62aeb28d31d382fdb30cad11372d693.js"></script>

3. 마지막으로 'sample.html' 파일의 777 라인 정도 내려가면 setCettificatePromise() 라는 함수가 있는데, 여기부터 80 줄 정도 아래의 858 라인 launchQZ 직전까지의 코드를 아래의 코드로 전체 치환한다.

/// Authentication setup ///
    qz.security.setCertificatePromise(function(resolve, reject) {
        resolve(publicKey);
    });
    qz.security.setSignaturePromise(function(toSign) {
        return function(resolve, reject) {
            try {
                var pk = KEYUTIL.getKey(privateKey);
                var sig = new KJUR.crypto.Signature({
                    "alg": "SHA1withRSA"
                });
                sig.init(pk);
                sig.updateString(toSign);
                var hex = sig.sign();
                // console.log("DEBUG: \n\n" + stob64(hextorstr(hex)));
                resolve(stob64(hextorstr(hex)));
            } catch (err) {
                console.error(err);
                reject(err);
            }
        };
    });
});

function strip(key) {
    if (key.indexOf('-----') !== -1) {
        return key.split('-----')[2].replace(/\r?\n|\r/g, '');
    }
}

• 위 코드에서 publicKey 와 privateKey 는 맨 처음 생성한 암호키(cert.pem&key.pem)의 내용이다.
• 변수대신 파일을 직접 열어 복사해 넣어도 정상 작동한다.

3.2.7. 인증 여부 확인

• 위와 같이 모두 잘 따라 했다면, 적용 후 sample.html 을 열어 보았을 때, 더 이상 접근 허용 다이어로그가 뜨지 않을 것이다.

  

  이미지 3.2.7_1: 인증 성공

  

  이미지 3.2.7_2: 인증 세부 내역

---

4. 문제 해결

4.1. 똑같이 따라 했는데 인증 결과가 아직도 'untrusted website' 라고 뜹니다.

예상 원인:

4.1.1. 암호 키 값이 정상적으로 소스코드에 입혀지지 않았을 수 있습니다. 소스 코드 재확인 해보세요.
4.1.2. 설치 후 바로 sample.html 을 열어 보았다면, 의도치 않은 캐시나 허용되지 않은 증명서를 통한 사용자 접근 기록이 존재할 수 있습니다. 아래와 같이 들어가서 확인 후 사용자를 제거해 보세요.

이미지 4.1_1: QZ Tray 사용자 관리

이미지 4.1_2: QZ Tray 사용자 관리 내역

이미지: 정상 인증된 계정입니다. (착오 없으시길 바랍니다.)(계정은 예시입니다.)
4.1.3. 일반적인 인식 문제일 수 있습니다. 방금 한 작업을 다시 한 번 빼먹은 것이 없는지 암호키 생성 단계부터 다시 해보세요.

4.2. 리컴파일 중, 오류가 발생해요. 'nsis' 를 찾을 수 없다고 나옵니다.

예상 원인:

4.2.1. NSIS 를 잘 설치했는지 확인해 봅니다.
4.2.2. ANT 의 환경변수 설정이 잘 되어 있는지 확인해 봅니다.

5. 마치며

웹 서버가 구축된 환경에서 사용자(클라이언트)의 컴퓨터에 설치된 인쇄기를 통해 '사용자의 아무런 개입 없이' 혹은 '최소한의 사용자 상호작용' 만으로 인쇄가 되도록 하는 것은 생각보다 좀 처럼 간단하기만 한 일은 아니었습니다.

해당 기능을 구현하기 위해 QZ Tray 에 대한 존재를 먼저 알아야 했고, 이후에 해당 프로그램을 무료로 실 사이트에 적용하기 위한 방법을 찾기까지 많지만은 않은 외국 레퍼런스만을 공부하며 참고했어야 했습니다. (외국 레퍼런스를 검색해 보시면, 제가 정리한 글과 겹치는 부분이 있을 겁니다.)

설치하고 적용하는 과정은 생각보다 쉽습니다. 다만, 무료 버전에서는 QZ Tray 를 사용하여도 사용자의 직접적인 상호작용 없이 바로 인쇄를 할 수 있는 기능을 막아 놓았기 때문에, 이 부분을 원활하게 사용하기 위해 진행하는 작업을 적은 레퍼런스 속에서 해내기 쉽지 않았습니다.

정확히 말하면, 그냥 무작정 막아 놓았다는 개념보다는 원격 서버로 부터의 인쇄를 안전하기 위해 설정해 놓은 인증서를 무료로 발급해 주지 않는다는 점으로 하여금 무료 사용을 간접적으로 막아놓았다고 말하는게 맞겠네요. (Self Sign Certificate 을 발급하면 무료로 사용 가능합니다.)

비교적 수월하게 인증서를 발급받고 적용하여 안전하고 편리한 플러그 인을 사용하려면 QZ Tray 의 직접적인 도움을 받은 방법 (직접 제공 라이선스 및 인증서 발급 + 기술 지원)($ 500 ~ $2,500) 이 수월합니다.

제가 나름 열심히 찾아 보았을 때는 한글로 된 레퍼런스가 없었기에, 저 처럼 혹시 다른 분들도 이렇게 헤매시지 않을까 도움이 되고자 설치하여 무료로 이용할 수 있는 방법을 정리해서 공유 합니다.
(다만, 위 방법을 통해 상업적인 목적으로 이용할 시 발생하는 문제에 대해서는 아무런 책임을 지지 않음을 미리 양지 하시기 바랍니다.)

위에 방법을 시도 하고자 하시는 분들은, 서론에 소개된 목적을 통해 본인이 구현하고자 하는 기능을 정말로 충족시켜 주는 지를 먼저 확인하시고, 하나 하나 꼼꼼히 따라서 해보시기 바랍니다. 약간의 오차로 인해 전체가 작동하지 않을 수 있습니다.

궁금한 점, 시간이 지나 변경된 사항이 있거나, 잘못된 설명이나 해석이 있다면 편하게 댓글 남겨주시기 바랍니다.

// 작성자 본인으로서, 무단으로 글을 퍼가거나 복제하는 것을 금합니다.