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서버 이상
Last modified 5mo ago