====== API USAGE ======

===== Signature Creation =====

====  (ES-BES) Signature Creation ====
<sxh java;highlight:[8,11] ;title:Java & .NET>
// create signature contained
SignatureContainer container = 	SignatureFactory.createContainer(SignatureFormat.CAdES, context);

// create signature object in the container
Signature signature = container.createSignature(certificate);

// add content to be signed
signature.addContent(new SignableFile(file), false);

// sign
signature.sign(cardSigner);

// write the signature to a File
container.write(new FileOuputStream(fileName));
</sxh>



==== ES-T Signature Creation ====
<sxh java;highlight:[11];title:Java & .NET Code>
// create signature object in the container
Signature signature = container.createSignature(certificate);

// add content to be signed
signature.addContent(new SignableFile(file), false);

// sign
signature.sign(cardSigner);

// upgrade the signature to ES-T
signature.upgrade(SignatureType.ES_T);

// write the signature to a File
container.write(new FileOuputStream(fileName));
</sxh>

===== Signatue Upgrades =====

==== Converting ES-BES to ES-T ====

<sxh java; highlight:[8]; title:Java Code>
// Read the signature container from a file
SignatureContainer container = SignatureFactory.readContainer(fileInputStream);

// Take the first signature
Signature signature = container.getSignatures().get(0);

// Upgrade the signature to ES-T
signature.upgrade(SignatureType.ES_T);

// write the signature to a File
container.write(new FileOuputStream(fileName));
</sxh>

<sxh csharp; highlight:[8]; title:.NET Code>
// Read the signature container from a file
SignatureContainer container = SignatureFactory.readContainer(fileInputStream);

// Take the first signature
Signature signature = container.getSignatures()[0];

// Upgrade the signature to ES-T
signature.upgrade(SignatureType.ES_T);

// write the signature to a File
container.write(new FileOuputStream(fileName));
</sxh>
==== ES-XL Signature ====

In order to create a signature of type ES-XL, it is enough to change the line in the ES-T signature creation 
sample 

<sxh java>
// create
...
// upgrade
signature.upgrade(SignatureType.ES_T);
</sxh>

with the line below 

<sxh java>
// upgrade
signature.upgrade(SignatureType.ES_XL);
</sxh>


===== Signature Verification =====

''verifyAll()'' method in ''SignatureContainer'' is used for signature verification.

<sxh java; highlight:[6]; title:Java Code>
// read the signature
SignatureContainer container = SignatureFactory.readContainer(inputstream);
inputstream.close();

// verify
ContainerValidationResult cvr = container.verifyAll();

// are all the signatures in the container valid?
assertEquals(ContainerValidationResultType.ALL_VALID, cvr.getResultType());
</sxh>

<sxh csharp; highlight:[6]; title:.NET Code >
// read the signature
SignatureContainer container = SignatureFactory.readContainer(inputstream);
inputstream.Close();

// verify
ContainerValidationResult cvr = container.verifyAll();

// are all the signatures in the container valid?
Assert.AreEqual(ContainerValidationResultType.ALL_VALID, cvr.getResultType());
</sxh>

==== Signature Verification Result Object ==== 

The method ''toString()'' in signature verification result object  returns  the signature object hierarchy as a tree.
The verification result of ''SignatureContainer'' is ''ContainerValidationResult'' where as that of each signature is ''SignatureValidationResult''. ''ContainerValidationResult'' object includes those ''SignatureValidationResult'' objects. 

To interpret the signature verification result the field ''ContainerValidationResultType'' in the class ''ContainerValidationResult'' is used. 

To identify which signatures are invalid, the corresponding signature results must be inspected.

<sxh java; title: Java Code>
// NOTE this method already exists in ContainerValidationResult !!! 
public List<SignatureValidationResult> getInvalidValidationResults()
{
    List<SignatureValidationResult> invalids = 
                                 new ArrayList<SignatureValidationResult>();
    // scan root signatures
    for (Signature signature : results.keySet()) {
        // scan counter signatures
        traceResults(results.get(signature), invalids);
    }
    return invalids;
}

private void traceResults(SignatureValidationResult svr, 
                          List<SignatureValidationResult> invalids)
{
    // is valid?
    if (svr.getResultType() != ValidationResultType.VALID) {
        invalids.add(svr);
    }
    // counter signatures
    if (svr.getCounterSignatureValidationResults() != null) {
        for (SignatureValidationResult counter :   
                                 svr.getCounterSignatureValidationResults())
        {
            traceResults(counter, invalids);
        }
    }
}
</sxh>

<sxh csharp; title:.NET Code>
ContainerValidationResult cvr = container.verifyAll();

// scan all verification results in the container
for (Signature signature : cvr.getAllResults().Keys){
    // signature verification result
    SignatureValidationResult svr = cvr.getAllResults().get(signature);

    // is valied?
    if (svr.getResultType != ValidationResultType.VALID)
        Console.WriteLine("Geçersiz imza "+svr);
}
</sxh>
===== Multiple Signatures ===== 
==== Adding Signature ====

=== Counter Signature ===

The signature of another signature is named as counter signature. For example, the employee signs a request and
the manager signs that signature as a confirmation of the request. To create counter signature, you can use the method ''createCounterSignature(Certificate)'' in ''Signature''.

<sxh java;title:Java Code;>
// read the signature container
SignatureContainer sc = SignatureFactory.readContainer(fileInputStream);

// take the first signature
Signature s = sc.getSignatures().get(0);

// create counter signature object
Signature counter= s.createCounterSignature(counterSignersCertificate);

// sign
counter.sign(cardSigner);

// write the signature container to a file
sc.write(new FileOuputStream(fileName));
</sxh>

<sxh csharp; title:.NET Code;>
// read the signature container
SignatureContainer sc = SignatureFactory.readContainer(fileInputStream);

// take the first signature
Signature s = sc.getSignatures()[0];

// create counter signature object
Signature counter= s.createCounterSignature(counterSignersCertificate);

// sign
counter.sign(cardSigner);

// write the signature container to a file
sc.write(new FileOuputStream(fileName));
</sxh>

=== Parallel Signature ===

Whenever the method ''createSignature()'' in ''SignatureContainer'' is caleed, a signature is created and added into the container. These independent signatures in the container are called as **paralel signature**. 


<sxh java; title:Java & .NET Code;>
// read the signature container
SignatureContainer container =    
        SignatureFactory.readContainer(fileInputStream);

Signature s1 = container.createSignature(certificate1);
s.addContent(new SignableFile(file), true);
s.sign(signer1);

Signature s2 = container.createSignature(certificate2);
s2.addContent(new SignableFile(file), true);
s2.sign(signer2);

// write the signature to a file
container.write(new FileOuputStream(fileName));
</sxh>

==== Extracting Signature   ====

To extract the signature from a signed document the method ''detachFromParent()'' is used. If the signature to be extracted is a counter signature it is extracted from the parent signature. The extracted signatures contains all of its children counter signatures.

<sxh java;title:Java Code>
// take the first signature
Signature s = sc.getSignatures().get(0);

// take the first counter signature
Signature counterSignature = s.getCounterSignatures().get(0);

// extract the counter signature and its children
counterSignature.detachFromParent();

// write the signature
container.write(stream);
.NET Code
// take the first signature
Signature s = sc.getSignatures()[0];

// take the first counter signature
Signature counterSignature = s.getCounterSignatures()[0];

// extract the counter signature and its children
counterSignature.detachFromParent();

// write the signature
container.write(stream);
</sxh>

===== Creation of Signatures with Profiles  ===== 

For the detailed information about signature profiles, see [[en:esya:eimza:profiller|Signature Profiles]]
The class ''TurkishESigProfiles'' contains the policies for the signature profiles defined in Turkey.


==== P1 Signature Creation ====

P1 is ES-BES which generally contains the signing time.

<sxh java; title:Java & .NET Code;>
SignatureContainer container = SignatureFactory.createContainer(format);
Signature signature = container.createSignature(signersCertificate);
signature.addContent(contentToSign, true);
signature.setSigningTime(Calendar.getInstance());
signature.sign(cardSigner);
// write
container.write(stream);
</sxh>

==== P2 Signature Creation ====

P2 signature contains timestamp.

<sxh java; title:Java & .NET Code>
SignatureContainer container = SignatureFactory.createContainer(format);
Signature signature = container.createSignature(signersCertificate);
signature.addContent(contentToSign, true);
// signature time
signature.setSigningTime(Calendar.getInstance());
// signature policy
signature.setSignaturePolicy(TurkishESigProfiles.SIG_POLICY_ID_P2v1);
// sign
signature.sign(cardSigner);	
// upgrade to ES-T (add timestamp)
signature.upgrade(SignatureType.ES_T);
// write
container.write(stream);
</sxh>

==== P3 Signature Creation ====

The signature profile P3 is used for long-term signatures where CRL is available.

<sxh java;title:Java & .NET Code;>
// create context 
Context context = new Context(new File(workingDir).toURI());

// proper certificate validation policy (use always OCSP when available)
context.getConfig().setCertificateValidationPolicy(crlOnlyPolicy);

// create signature container
SignatureContainer c = SignatureFactory.createContainer(format, context);
Signature signature = c.createSignature(signersCertificate);

// content to be signed
signature.addContent(contentToSign, true);
// signature time
signature.setSigningTime(Calendar.getInstance());

// signature policy
signature.setSignaturePolicy(TurkishESigProfiles.SIG_POLICY_ID_P3v1);

// sign
signature.sign(cardSigner);	
// upgrade to ES-XLong)
signature.upgrade(SignatureType.ES_XL);
// sign
c.write(stream);
</sxh>

==== P4 Signature Creation ====

The signature profile P4 is used for long-term signatures where OCSP is available.

<sxh java; title:Java & .NET Code>
// create context
Context context = new Context(new File(workingDir).toURI());

// proper certificate validation policy (use always OCSP when available)
context.getConfig().setCertificateValidationPolicy(ocspFirstPolicy);

// create signature
SignatureContainer c = SignatureFactory.createContainer(format, context);
Signature signature = c.createSignature(signersCertificate);

// content to be signed
signature.addContent(contentToSign, true);
// signature time
signature.setSigningTime(Calendar.getInstance());

// signature policy
signature.setSignaturePolicy(TurkishESigProfiles.SIG_POLICY_ID_P4v1);

// sign
signature.sign(cardSigner);	
// upgrade to ES-XLong)
signature.upgrade(SignatureType.ES_XL);
// write
c.write(stream);
</sxh>