API 명세서

개요

TSA서버로 PDF에 서명을 추가하는 TimeStamp 요청을 위한 API를 정의합니다.

API 목록

분류

API 명

설

비

PDF 파일

로컬 PDF파일 서명

WAS내부에 저장되어 있는 PDF파일을 타임스탬프 서명을 추가해서 다른 위치에 저장

PDF 파일

원격 PDF파일 서명

클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환

회사코드 누락 및 등록되지 않은 코드 사용시 서비스 불가

PDF 파일

PDF파일 검증

클라이언트가 업로드한 PDF파일의 서명을 검증.

API 상세정보

1. 로컬 PDF파일 서명

WAS내부에 저장되어 있는 PDF파일을 타임스탬프 서명을 추가해서 다른 위치에 저장

* 유의사항 : API 사용을 위해서는 사본파일과 원본파일의 저장 위치가 TSA가 설치된 서버가 파일경로에 접근할 수 있는 동일 서버(Local)에 존재해야 사용 가능합니다.

URL

  • Method : POST

  • Endpoint : $SERVER/api/ext/signpdf

  • Content-Type: application/x-www-form-urlencoded

  • 입력 파라미터

필드명

타입

비고

in

string

서명을 추가할 pdf파일 경로. 절대경로

예) /opt/pdfs/raw/fileA.pdf

out

string

서명이 추가된 pdf파일 경로. 절대경로

예) /opt/pdfs/signed/fileA_signed.pdf

category

string

서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행

companyId

string

DTT Alliance가 발급한 companyid

응답

  • Content-Type: plain/text

  • HTTP status:

    • 200 성공

    • 400 잘못된 요청으로 인한 실패

    • 500 서버쪽 문제로 실패

  • BODY:

    • 성공시: 결과 파일명 (UTF-8 인코딩 바이트)

    • 실패시: 오류종류

오류 종류

이름

설명

NotFound

입력 파일이 없음

Invalid

입력 파일을 읽는데 실패함, 혹은 잘못된 category 값.

WriteFail

출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로

Internal

TSA서버 이상

샘플코드

import java.io.ByteArrayOutputStream;

import java.io.IOException;

import java.io.InputStream;

import java.net.HttpURLConnection;

import java.net.MalformedURLException;

import java.net.URL;

import java.net.URLEncoder;

import java.util.HashMap;

import java.util.Map;

public class SignByPathSender {

private static final int API_TIMEOUT = 300 * 1000; // 30 seconds

public static void main(String[] args) throws MalformedURLException {

URL url = new URL("http://localhost:8080/api/ext/signpdf"); //Aergo TSA서버의 주소로 변경

Map<String, String> params = new HashMap<>();

params.put("in", args[0]);

params.put("out", args[1]);

params.put("category", args[2]);

try {

byte[] result = postForm(url, params);

System.out.println("success: result file is in " + new String(result));

} catch (IllegalArgumentException e) {

String cause = e.getMessage(); // 서버쪽에서 알린 실패 이유

System.out.println("server response error: " + cause);

} catch (IOException e) {

String cause = e.getMessage();

System.out.println("unexpected failure: " + cause);

}

}

private static byte[] postForm(URL url, Map<String, String> params) throws IllegalArgumentException, IOException {

try {

HttpURLConnection con = (HttpURLConnection) url.openConnection();

con.setConnectTimeout(API_TIMEOUT); //서버에 연결되는 Timeout 시간 설정

con.setReadTimeout(API_TIMEOUT); // InputStream 읽어 오는 Timeout 시간 설정

con.setRequestMethod("POST"); //POST 방식 선언

con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded"); //content-type 선언

con.setDoInput(true);

con.setDoOutput(true); //POST 데이터를 OutputStream으로 넘겨 주겠다는 설정

con.setUseCaches(false);

con.setDefaultUseCaches(false);

StringBuilder sb = new StringBuilder();

for (Map.Entry<String, String> ent : params.entrySet()) {

sb.append(ent.getKey()).append('=').append(URLEncoder.encode(ent.getValue(), "UTF-8"));

sb.append('&');

}

sb.deleteCharAt(sb.length() - 1);

con.getOutputStream().write(sb.toString().getBytes());

con.getOutputStream().flush();

if (con.getResponseCode() == HttpURLConnection.HTTP_OK) {

byte[] bytes = readToByteArray(con.getInputStream());

return bytes;

} else {

int responseCode = con.getResponseCode();

byte[] bytes = readToByteArray(con.getErrorStream());

throw new IllegalArgumentException(new String(bytes));

}

} catch (IOException e) {

// FIXME

throw new IOException("io exception", e);

}

}

private static byte[] readToByteArray(InputStream is) throws IOException {

ByteArrayOutputStream buffer = new ByteArrayOutputStream();

int nRead;

byte[] data = new byte[4096];

while ((nRead = is.read(data, 0, data.length)) != -1) {

buffer.write(data, 0, nRead);

}

return buffer.toByteArray();

}

}

2. 원격 PDF파일 서명

클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환

URL

  • Method : POST

  • Endpoint : $SERVER/api/ext/pdf/sign

  • Content-Type: multipart/form-data

  • 입력 파라미터

필드명

타입

비고

inpdf

binary

서명을 추가할 pdf파일 데이터

filename

string

결과 pdf파일의 이름. 추후 서버 검색용도로 사용함

category

string

서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행

companyId

string

회사코드는 반드시 등록된 회사코드로 사용해야 함.

만약 등록되지 않은 회사코드로 접근시 InvalidParam에러 발생

응답

  • Content-Type: application/json

  • HTTP status:

    • 200 성공

    • 400 잘못된 요청으로 인한 실패

    • 500 서버쪽 문제로 실패

  • BODY:

    • 성공시: SignResult

    • 실패시: 오류종류

SignResult

필드명

타입

비고

docHash

string

hexa-decimal 인코딩된 문서 해시

txhash

string

base58 인코딩된 블록체인 tx해시

filename

string

결과 pdf파일의 이름. 요청때 보낸 것과 동일한 이름

outpdf

byte[]

서명이 추가된 PDF파일 데이터. base64로 인코딩된 바이트 배열

오류 종류

이름

설명

NotFound

입력 파일이 없음

Invalid

입력 파일을 읽는데 실패함, 혹은 잘못된 category 값. 혹은 회사코드 누락

WriteFail

출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로

Internal

TSA서버 이상

3. PDF파일 검증

클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환

URL

  • Method : GET

  • Endpoint : $SERVER/api/ext/pdf/sign

  • Content-Type: multipart/form-data

  • 입력 파라미터

필드명

타입

비고

inpdf

binary

서명을 추가할 pdf파일 데이터

filename

string

결과 pdf파일의 이름. 추후 서버 검색용도로 사용함

category

string

서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행

응답

  • Content-Type: application/json

  • HTTP status:

    • 200 성공

    • 400 잘못된 요청으로 인한 실패

    • 500 서버쪽 문제로 실패

  • BODY:

    • 성공시: SignResult

    • 실패시: 오류종류

SignResult

필드명

타입

비고

docHash

string

hexa-decimal 인코딩된 문서 해시

txhash

string

base58 인코딩된 블록체인 tx해시

filename

string

결과 pdf파일의 이름. 요청때 보낸 것과 동일한 이름

outpdf

byte[]

서명이 추가된 PDF파일 데이터. base64로 인코딩된 바이트 배열

오류 종류

이름

설명

NotFound

입력 파일이 없음

Invalid

입력 파일을 읽는데 실패함, 혹은 잘못된 category 값.

WriteFail

출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로

Internal

TSA서버 이상

PreviousDTT-Xangle 원본확인 서비스NextDTT 얼라이언스에 대한 질문

Last updated