# Aventra MyEID PKI

{% hint style="warning" %}
Sample code uses ES6 language features such as arrow functions and promises. For compatibility with IE11, code written with these features must be either transpiled using tools like Babel or refactored accordingly using callbacks.
{% endhint %}

## Introduction

Aventra MyEID PKI Card is a cryptographic smart card conforming to common Public Key Infrastructure standards like ISO/IEC-7816 and PKCS#15v1.0 specification. It can be used for various tasks requiring strong cryptography, e. g. logging securely to Windows, encrypting e-mail, authentication, and electronic signatures. The card is also available as a Dual Interface version, compatible with T=CL protocol and also emulating Mifare™. The card is a JavaCard with Aventra MyEID applet that implements the functionality.

The applet implements the FINEID S1 v1.12 specification and it can be configured to include all or any subset of the features specified in FINEID S4-1 or S4-2 specifications. Starting from version 2.2.0 the applet supports both 1024 and 2048 bit RSA keys. From version 3.0.0 (MyEID3) the applet supports keys from 512 bit up to 2048 bit in increments of 64 bits. The applet is fully compatible with JavaCard 2.1.1 and GlobalPlatform 2.0.1 specifications. The new MyEID version 3 (MyEID3) is now released and it uses the new JavaCard 2.2.1 and GlobalPlatform 2.1.1 platform. The new MyEID3 now supports RSA keys from 512 up to 2048 bits in 64 bit increments. MyEID3 supports file sizes up to 32767 bytes and 14 different PIN-codes can be created and used. The number of RSA keys is only limited by the available memory and maximum numbers of files (see PUT DATA: INITIALISE APPLET).

**References**

The most relevant specifications and standards are:

* ISO/IEC 7816-4
* ISO/IEC 7816-8
* ISO/IEC 7816-9
* JavaCard 2.1.1, MyEID3: 2.2.1
* GlobalPlatform 2.0.1 ' (Open Platform), MyEID3: GlobalPlatform 2.1.1
* FINEID S1 and S4 documentation

This document describes the functionality provided by the Aventra smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:

* MyEID - reference manual v1.7.36

## Interface

```javascript
export interface AbstractAventra {
    allCertFilters(): string[];
    allKeyRefs(): string[];
    allCerts(parseCerts?: boolean, filters?: string[] | Options, callback?: (error: T1CLibException, data: TokenAllCertsResponse) => void): Promise<TokenAllCertsResponse>;
    tokenData(callback?: (error: T1CLibException, data: TokenDataResponse) => void): Promise<TokenDataResponse>;
    rootCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    authenticationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    nonRepudiationCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    encryptionCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>;
    issuerCertificate(parseCerts?: boolean, callback?: (error: T1CLibException, data: TokenCertificateResponse) => void): Promise<TokenCertificateResponse>
    verifyPin(body: TokenVerifyPinData, callback?: (error: T1CLibException, data: TokenVerifyPinResponse) => void): Promise<TokenVerifyPinResponse>;
    authenticate(body: TokenAuthenticateOrSignData, callback?: (error: T1CLibException, data: TokenAuthenticateResponse) => void): Promise<TokenAuthenticateResponse>;
    sign(body: TokenAuthenticateOrSignData, bulk?: boolean, callback?: (error: T1CLibException, data: TokenSignResponse) => void): Promise<TokenSignResponse>;
    resetPin(body: TokenResetPinData, callback?: (error: T1CLibException, data: TokenResetPinResponse) => void): Promise<TokenResetPinResponse>
    allAlgoRefs(callback?: (error: T1CLibException, data: TokenAlgorithmReferencesResponse) => void): Promise<TokenAlgorithmReferencesResponse>
    resetBulkPin(callback?: (error: T1CLibException, data: BoolDataResponse) => void): Promise<BoolDataResponse>;
}

```

### Models

All model information can be found in the [Token typings model page](../token-typing-models#models)

## Examples

### Create the Aventra module

```javascript
T1CSdk.T1CClient.initialize(config).then(res => {
    const aventra = res.client.createAventra(readerId);
}, err => {
    console.error(error)
});
```

When initialisation is finished you can continue using the aventra object to execute the functions below.

### All certificate filters

```javascript
aventra.allCertFilters().then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate', 'nonRepudiationCertificate', 'issuerCertificate']
}
```

### all Key references

```javascript
aventra.allKeyRefs().then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: ['authenticate', 'sign', 'encrypt']
}
```

### all Certificates

Exposes all the certificates publicly available on the smart card. The following certificates can be found on the card:

* Root certificate
* Signing certificate
* Authentication certificate
* Issuer certificate
* Encryption certificate

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

```javascript
const filter = ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate'];
aventra.allCerts(parseCertsBoolean, filter).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
       authenticationCertificate?: {
            certificate?: TokenCertificateObject,
            certificates?: Array<TokenCertificateObject>
       },
       citizenCertificate?: {
            certificate?: TokenCertificateObject,
            certificates?: Array<TokenCertificateObject>
       },
       nonRepudiationCertificate?: {
            certificate?: TokenCertificateObject,
            certificates?: Array<TokenCertificateObject>
       },,
       rootCertificate?: {
            certificate?: TokenCertificateObject,
            certificates?: Array<TokenCertificateObject>
       },,
       encryptionCertificate?: {
            certificate?: TokenCertificateObject,
            certificates?: Array<TokenCertificateObject>
       },
    }
}
```

### Token data

This will return information of the Aventra card.

```javascript
aventra.tokenData().then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
       version?: string,
       serialNumber?: string,
       label?: string,
       changeCounter?: number,
    }
}
```

### Certificate

&#x20;When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.

#### Root certificate

Contains the 'root certificate' stored on the smart card.

```javascript
aventra.rootCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})
```

#### Authentication certificate

Contains the 'authentication certificate' stored on the smart card. The 'authentication certificate' contains the public key corresponding to the private RSA authentication key. The 'authentication certificate' is needed for pin validation, authentication and signing.

```javascript
aventra.authenticationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})
```

#### Non repudiation certificate

Contains the 'non-repudiation certificate' stored on the smart card. The 'non-repudiation certificate' contains the public key corresponding the private RSA non-repudiation key.

```javascript
aventra.nonRepudiationCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})
```

#### Issuer certificate

```javascript
aventra.issuerCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})
```

#### Encryption certificate

```javascript
aventra.encryptionCertificate(parseCertsBoolean).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for these calls should be in the following format;

```javascript
{
    success: true,
    data: {
        certificate?: TokenCertificateObject,
        certificates?: Array<TokenCertificateObject>    
    }    
}
```

### Verify pin

```javascript
const data = {
    pin: "1234", // optional
    osDialog: true // optional
}
aventra.verifyPin(data).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for these calls should be in the following format;

```javascript
{
    success: true,
    data: {
        "verfied": true
    }
}
```

### Sign

To sign data, an algorithm must be specified in the `algorithm` property (see [Supported Algorithms](#retrieve-supported-algorithms)), and a Base64-encoded string representation of the digest bytes of the same algorithm in the `data` property.

Additionally, it is possible to bulk sign data without having to re-enter the PIN by adding an optional `bulk` parameter set to `true` to the request. Subsequent sign requests will not require the PIN to be re-entered until a request with `bulk` being set to `false` is sent, or the [Bulk PIN Reset](#bulk-pin-reset) method is called.

{% hint style="danger" %}
When using bulk signing, great care must be taken to validate that the first signature request was successful prior to sending subsequent requests. Failing to do this will likely result in the card being blocked.
{% endhint %}

```javascript
const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
const bulk = false;
aventra.sign(data, bulk).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
        data: string
    }
}
```

### Bulk PIN Reset

The PIN set for bulk signing can be reset by calling this method.

```javascript
aventra.resetBulkPin().then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

```javascript
{
    "success": true,
    "data": true
}
```

### Authenticate

```javascript
const data = {
    algorithm: "sha256",
    data: "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=",
    id: "123"
}
aventra.authenticate(data).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
        data: string
    }
}
```

### Reset pin

```javascript
const data = {
    pin: "3214", //optional
    puk: "123123"
}
aventra.resetPin(data).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
        verified: boolean
    }
}
```

### Retrieve supported algorithms

```javascript
aventra.allAlgoRefs(data).then(res => {
}, err => {
    console.error(err)
})
```

The expected response for this call should be;

```javascript
{
    success: true,
    data: {
        ref: ['sha256', 'md5']
    }
}
```
