From 27fb69688a5de7e291ce5a2fd348becb1a722ad5 Mon Sep 17 00:00:00 2001 From: Andreas Fitzek Date: Wed, 5 Feb 2014 09:21:35 +0100 Subject: Javadoc for public API --- .../gv/egiz/pdfas/lib/api/ByteArrayDataSink.java | 7 +++ .../gv/egiz/pdfas/lib/api/ByteArrayDataSource.java | 3 ++ .../at/gv/egiz/pdfas/lib/api/Configuration.java | 24 +++++++++ .../java/at/gv/egiz/pdfas/lib/api/DataSink.java | 7 +++ .../java/at/gv/egiz/pdfas/lib/api/DataSource.java | 16 ++++++ .../main/java/at/gv/egiz/pdfas/lib/api/PdfAs.java | 25 +++++++++ .../at/gv/egiz/pdfas/lib/api/PdfAsFactory.java | 61 ++++++++++++---------- .../at/gv/egiz/pdfas/lib/api/PdfAsParameter.java | 16 ++++++ .../at/gv/egiz/pdfas/lib/api/StatusRequest.java | 43 +++++++++++++++ .../gv/egiz/pdfas/lib/api/sign/IPlainSigner.java | 36 ++++++++++--- .../gv/egiz/pdfas/lib/api/sign/SignParameter.java | 35 +++++++++++++ .../egiz/pdfas/lib/api/verify/VerifyParameter.java | 24 ++++++++- .../gv/egiz/pdfas/lib/api/verify/VerifyResult.java | 9 +++- 13 files changed, 270 insertions(+), 36 deletions(-) diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSink.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSink.java index 6cc63338..a8931963 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSink.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSink.java @@ -3,6 +3,9 @@ package at.gv.egiz.pdfas.lib.api; import java.io.ByteArrayOutputStream; import java.io.OutputStream; +/** + * A simple byte array data sink + */ public class ByteArrayDataSink implements DataSink { protected ByteArrayOutputStream bos = new ByteArrayOutputStream(); @@ -12,6 +15,10 @@ public class ByteArrayDataSink implements DataSink { return bos; } + /** + * Returns the output data + * @return the output data + */ public byte[] getData() { return bos.toByteArray(); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSource.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSource.java index cd670cea..6adfde51 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSource.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/ByteArrayDataSource.java @@ -1,5 +1,8 @@ package at.gv.egiz.pdfas.lib.api; +/** + * A simple byte array data source + */ public class ByteArrayDataSource implements DataSource { private byte[] byteData; diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/Configuration.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/Configuration.java index 89acc747..d2f00a59 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/Configuration.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/Configuration.java @@ -1,7 +1,31 @@ package at.gv.egiz.pdfas.lib.api; +/** + * Configuration interface + * + * This interface is used to configure one PDF-AS run. It contains the configuration values + * from the configuration file. Use this interface to override properties during runtime. + */ public interface Configuration { + + /** + * Gets a specific Value + * @param key The configuration key + * @return The configured value + */ public String getValue(String key); + + /** + * Is the configuration key set + * @param key The configuration key + * @return true | false + */ public boolean hasValue(String key); + + /** + * Sets or overrides a configuration value + * @param key The configuration key + * @param value The configuration value + */ public void setValue(String key, String value); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSink.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSink.java index 4a3fb52c..258141b5 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSink.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSink.java @@ -2,6 +2,13 @@ package at.gv.egiz.pdfas.lib.api; import java.io.OutputStream; +/** + * Data Sink interface. + */ public interface DataSink { + /** + * Creates an output stream to receive the data + * @return an output stream for the data + */ public OutputStream createOutputStream(); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSource.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSource.java index 73487c7b..093a3777 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSource.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/DataSource.java @@ -1,6 +1,22 @@ package at.gv.egiz.pdfas.lib.api; +/** + * Data Source interface + * + * All data sources in PDF-AS implement this interface. Also custom data sources have to + * implement this interface to allow PDF-AS to use them. + */ public interface DataSource { + + /** + * Gets the MIME Type of the contained data. + * @return MIME Type + */ public String getMIMEType(); + + /** + * Gets the contained data + * @return the contained data + */ public byte[] getByteData(); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAs.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAs.java index 2711afe2..3ae329cf 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAs.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAs.java @@ -33,7 +33,32 @@ public interface PdfAs { */ public Configuration getConfiguration(); + /** + * Starts a signature process + * + * After the process has to be startet the status request has to be services by the user application + * + * @param parameter The sign parameter + * @return A status request + * @throws PdfAsException + */ public StatusRequest startSign(SignParameter parameter) throws PdfAsException; + + /** + * Continues an ongoing signature process + * + * @param statusRequest The current status + * @return A status request + * @throws PdfAsException + */ public StatusRequest process(StatusRequest statusRequest) throws PdfAsException; + + /** + * Finishes a signature process + * + * @param statusRequest The current status + * @return A signature result + * @throws PdfAsException + */ public SignResult finishSign(StatusRequest statusRequest) throws PdfAsException; } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsFactory.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsFactory.java index 3f5888fc..02d217c2 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsFactory.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsFactory.java @@ -1,6 +1,5 @@ package at.gv.egiz.pdfas.lib.api; -import iaik.cms.IaikCCProvider; import iaik.security.ec.provider.ECCelerate; import iaik.security.provider.IAIK; @@ -38,6 +37,7 @@ public class PdfAsFactory { private static final String MAN_ATTRIBUTE = "JARMANIFEST"; private static final String PDF_AS_LIB = "PDF-AS-LIB"; private static final String IMPL_VERSION = "Implementation-Version"; + private static final String SCM_REVISION = "SCMREVISION"; static { @@ -50,6 +50,7 @@ public class PdfAsFactory { System.out.println("+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"); System.out.println("+ PDF-AS: " + getVersion()); + System.out.println("+ PDF-AS SCM Revision: " + getSCMRevision()); System.out.println("+ IAIK-JCE Version: " + IAIK.getVersionInfo()); System.out.println("+ ECCelerate Version: " + ECCelerate.getInstance().getVersion()); System.out.println("+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"); @@ -64,6 +65,11 @@ public class PdfAsFactory { } } + /** + * Create a new instance of PDF-AS + * @param configuration The PDF-AS configuration + * @return + */ public static PdfAs createPdfAs(File configuration) { if (!log_configured) { synchronized (log_mutex) { @@ -91,12 +97,24 @@ public class PdfAsFactory { return new PdfAsImpl(configuration); } + /** + * Creates a sign parameter + * @param configuration The configuration to be used + * @param dataSource The data source to be used + * @return + */ public static SignParameter createSignParameter( Configuration configuration, DataSource dataSource) { SignParameter param = new SignParameterImpl(configuration, dataSource); return param; } + /** + * Creates a verification parameter + * @param configuration The configuration to be used + * @param dataSource The data source to be used + * @return + */ public static VerifyParameter createVerifyParameter( Configuration configuration, DataSource dataSource) { VerifyParameter param = new VerifyParameterImpl(configuration, @@ -177,35 +195,22 @@ public class PdfAsFactory { } } } - + + /** + * Gets the PDF-AS SCM Revision + * @return + */ + public static String getSCMRevision() { + Package pack = PdfAsFactory.class.getPackage(); + return pack.getSpecificationVersion(); + } + + /** + * Gets the PDF-AS Version + * @return PDF-AS Verison string + */ public static String getVersion() { Package pack = PdfAsFactory.class.getPackage(); return pack.getImplementationVersion(); - /* - try { - - - Enumeration resources = PdfAsFactory.class.getClassLoader() - .getResources("META-INF/MANIFEST.MF"); - while (resources.hasMoreElements()) { - Manifest manifest = new Manifest(resources.nextElement() - .openStream()); - Attributes attributes = manifest.getAttributes(MAN_ATTRIBUTE); - if (attributes != null) { - if(attributes.isEmpty()) { - String value = attributes.getValue(new Attributes.Name(MAN_ATTRIBUTE)); - if(value != null && value.equals(PDF_AS_LIB)) { - // Got my manifest - return manifest.getAttributes(IMPL_VERSION).getValue(IMPL_VERSION); - } - } - } - } - } catch (Throwable e) { - e.printStackTrace(); - logger.error("Failed to read Version!"); - return "0.0.0"; - } - return "0.0.0";*/ } } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsParameter.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsParameter.java index 8ab9a4be..0ef5f876 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsParameter.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/PdfAsParameter.java @@ -2,11 +2,27 @@ package at.gv.egiz.pdfas.lib.api; public interface PdfAsParameter { + /** + * Gets the configuration associated with the parameter + * @return + */ public Configuration getConfiguration() ; + /** + * Sets the configuration associated with the parameter + * @param configuration + */ public void setConfiguration(Configuration configuration); + /** + * Gets the data source of the parameter + * @return + */ public DataSource getDataSource(); + /** + * Sets the data source of the parameter + * @param dataSource + */ public void setDataSource(DataSource dataSource); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/StatusRequest.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/StatusRequest.java index fb6ceb44..2c283900 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/StatusRequest.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/StatusRequest.java @@ -2,15 +2,58 @@ package at.gv.egiz.pdfas.lib.api; import java.security.cert.CertificateException; +/** + * Status of a signture process + */ public interface StatusRequest { + /** + * If true PDF-AS requires the signature certificate + * + * Retrieve the signing certificate and set it via setCertificate + * @return + */ public boolean needCertificate(); + + /** + * If true PDF-AS requires a the CAdES signature + * + * use getSignatureData() and getSignatureDataByteRange() to retrieve the + * data to be signed and set the signature via setSigature + * + * @return + */ public boolean needSignature(); + + /** + * If true finishSign in PdfAs can be called to retrieve the signed pdf + * @return + */ public boolean isReady(); + /** + * Gets the data to be signed + * @return + */ public byte[] getSignatureData(); + + /** + * Gets the byte range of the data to be signed + * @return + */ public int[] getSignatureDataByteRange(); + + /** + * Sets the signing certificate + * @param encodedCertificate + * @throws CertificateException + */ public void setCertificate(byte[] encodedCertificate) throws CertificateException; + + /** + * Sets the signature + * @param signatureValue + */ public void setSigature(byte[] signatureValue) ; } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/IPlainSigner.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/IPlainSigner.java index 0ad40cc4..70945678 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/IPlainSigner.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/IPlainSigner.java @@ -1,17 +1,41 @@ package at.gv.egiz.pdfas.lib.api.sign; import iaik.x509.X509Certificate; - -import java.io.IOException; - -import org.apache.pdfbox.cos.COSName; -import org.apache.pdfbox.exceptions.SignatureException; - import at.gv.egiz.pdfas.common.exceptions.PdfAsException; +/** + * Signer interface + * + * PDF-AS uses an IPlainSigner instance to create the signature. Also custom IPlainSigner + * may be used to sign PDF-AS documents. + */ public interface IPlainSigner { + + /** + * Gets the signing certificate + * @return + * @throws PdfAsException + */ public X509Certificate getCertificate() throws PdfAsException; + + /** + * Sign the document + * @param input + * @param byteRange + * @return + * @throws PdfAsException + */ public byte[] sign(byte[] input, int[] byteRange) throws PdfAsException; + + /** + * Gets the PDF Subfilter for this signer + * @return + */ public String getPDFSubFilter(); + + /** + * Gets the PDF Filter for this signer + * @return + */ public String getPDFFilter(); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/SignParameter.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/SignParameter.java index 87ec4068..0b4fb389 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/SignParameter.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/sign/SignParameter.java @@ -5,19 +5,54 @@ import at.gv.egiz.pdfas.lib.api.PdfAsParameter; public interface SignParameter extends PdfAsParameter { + /** + * Gets the signature profile to use + * @return + */ public String getSignatureProfileId(); + /** + * Sets the signature profile to use + * + * @param signatureProfileId The signature profile + */ public void setSignatureProfileId(String signatureProfileId); + /** + * Gets the signature position + * @return + */ public String getSignaturePosition(); + /** + * Sets the signature position + * @param signaturePosition The signature position string + */ public void setSignaturePosition(String signaturePosition); + /** + * Sets the data sink for the signature process + * @param output + */ public void setOutput(DataSink output); + /** + * Gets the data sink for the signature process + * @return + */ public DataSink getOutput(); + /** + * Sets the signer to use + * + * + * @param signer + */ public void setPlainSigner(IPlainSigner signer); + /** + * Gets the signer to use. + * @return + */ public IPlainSigner getPlainSigner(); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyParameter.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyParameter.java index da777343..cd973146 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyParameter.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyParameter.java @@ -5,12 +5,34 @@ import java.util.Date; import at.gv.egiz.pdfas.lib.api.PdfAsParameter; public interface VerifyParameter extends PdfAsParameter { - + + /** + * Gets which signature should be verified + * + * This is a 0 based index of the signatures + * @return + */ public int getWhichSignature(); + /** + * Sets which signature should be verified + * + * This is a 0 based index of the signatures + * + * @param which The index + */ public void setWhichSignature(int which); + /** + * Gets the verification time + * @return + */ public Date getVerificationTime(); + /** + * Sets the verification time. + * + * @param verificationTime + */ public void setVerificationTime(Date verificationTime); } diff --git a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyResult.java b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyResult.java index 436bfb25..7aa391b5 100644 --- a/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyResult.java +++ b/pdf-as-lib/src/main/java/at/gv/egiz/pdfas/lib/api/verify/VerifyResult.java @@ -49,8 +49,15 @@ public interface VerifyResult { */ public boolean isQualifiedCertificate(); - + /** + * Gets the signer certificate + * @return + */ public X509Certificate getSignerCertificate(); + /** + * Gets the signed data for the signature + * @return + */ public byte[] getSignatureData(); } -- cgit v1.2.3