====== ASiC Signature API ======

ASiC signature packages as decribed in [[http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.01.01_60/ts_102918v010101p.pdf | ETSI TS 102 918]] can be created by using ESYA ASiC Signature API. By using this structure, one ore more signature, signed data and validation data can be bundled into a single zip file.

===== Requirements =====

ASiC Signature API requires the licence file, certificate validation policy file and certificate store file. CAdES or XAdES API is also required according to the signature format used in the ASiC package..

For qualified signatures, use of a secure hardware is compulsory. Usually, smartcards are used for this purpose. To access smartcard, the driver for the smartcard reader and the smartcard must be set up in the target machine. A utility application to view the contents of smartcard can be obtained from card manufacturers.

===== Concepts =====

==== Package Type ====

<code java>
public enum PackageType
{
    ASiC_S,
    ASiC_E 
}
</code>

| **Basit (ASIC_S)** | Single signature and single data. |
| **Extended (ASIC_E)** | One or more signature and one or more data. Single signature for multiple data may also exist. |

===== Key Interfaces and Design ======

==== SignaturePackageFactory ====

It contains static methods used for signature creation.

==== SignaturePackage ====

It represents the ZIP structure containing ''SignatureContainer'' and signed data.
For the interfaces  ''SignatureContainer'', ''Signature'', and ''Signable'', see [[en:esya:ortakimza:eimza-ortak-kutuphanesi|Common Signature API]].

===== API Usage =====

==== A Simple Package Creation ====

<sxh java>
Context c = new Context();
SignatureFormat format = SignatureFormat.CAdES; // Can also be SignatureFormat.XAdES

SignaturePackage signaturePackage = SignaturePackageFactory
    .createPackage(c, PackageType.ASiC_S, format);

// Add data to be signed
Signable inPackage = signaturePackage.addData(new SignableFile(dataFile, "text/plain"), "sample.txt");
SignatureContainer container = signaturePackage.createContainer();
Signature signature = container.createSignature(CERTIFICATE);

// Add data to be signed(false=data is not included in the signature) 
signature.addContent(inPackage, false);
signature.sign(SIGNER);

// write the package
signaturePackage.write(new FileOutputStream(fileName));
</sxh>

==== Multiple signatures ====

<sxh java; title: Reading and Updating Package(SignatureContainer)>
// read package from file
SignaturePackage sp = SignaturePackageFactory.readPackage(new Context(), inputFile);

// create new container in package
SignatureContainer sc = sp.createContainer();
// create new signature in container
Signature s = sc.createSignature(CERTIFICATE);

// get signable from package
s.addContent(sp.getDatas().get(0), false);
s.sign(SIGNER);

// write
sp.write(new FileOutputStream(outFileName));
</sxh>
==== Verification ====

<sxh java>
// read package from file
SignaturePackage sp = SignaturePackageFactory.readPackage(new Context(), inputFile);

// verify
PackageValidationResult pvr = sp.verifyAll();

// check result
assert pvr.getResultType() == PackageValidationResultType.ALL_VALID;
</sxh>
==== Signature Upgrade ====

<sxh java>
// read package from file 
Context c = new Context();
SignaturePackage sp = SignaturePackageFactory.readPackage(c, new File(fileName));

// get first signature container
SignatureContainer sc = signaturePackage.getContainers().get(0);

// get first signature in container
Signature signature = sc.getSignatures().get(0);

// upgrade
signature.upgrade(SignatureType.ES_T);

signaturePackage.write(new FileOutputStream(outFileName));
</sxh>

For more examples, see [[en:esya:ortakimza:eimza-ortak-kutuphanesi|Common Signature API]]. The codes listed here are kept short for the sake of readability. You can also  check [[esya:ortakimza:imza-api-kullanim|here]].

|Previous: [[en:esya:xades:eimza-xades-kutuphanesi|XAdES Signature API]]|[[:start_en|Home]]| Next: [[en:esya:cmszarf:cms-zarf|CMS Envelope]]|