# Oberthur Cosmo One v7.3

{% 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

The ID-One Cosmo V7-n is part of the Oberthur family of cryptographic modules called ID-One Cosmo V7. Modules within

this family share the same functionalities and the description of the ID-One Cosmo V7 applies to all versions including the “-n” subject to this validation.

This document describes the functionality provided by the Oberthur ID-One smartcard - which is a PKI container:

* ID-One Cosmo V7-n; FIPS 140-2 Security Policy

## Interface

```javascript
export interface AbstractOberthur73 {
    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>;
    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](https://t1t.gitbook.io/t1c-js-guide-v3/t1c-js-sdk/token-typing-models#models)

## Examples

### Create the Oberthur module

```javascript
T1cSdk.initialize(config).then(res => {
    const oberthur = res.client.oberthur(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
oberthur.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
oberthur.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'];
oberthur.allCerts(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
oberthur.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.\
The service can be called:

```javascript
oberthur.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 singing.\
The service can be called:

```javascript
oberthur.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.\
The service can be called:

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

#### Issuer certificate

```javascript
oberthur.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?: string,
        certificates?: Array<string>,
        certificateType?: string,
        id?: string,
        parsedCertificate?: Certificate,
        parsedCertificates?: Array<Certificate>
    }    
}
```

### Verify pin

```javascript
const data = {
    pin: "1234", // optional
    osDialog: true // optional
}
oberthur.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

Data can be signed using the smartcard. To do so, the SDK facilitates in:

* Retrieving the certificate chain (root, intermediate and non-repudiation certificate)
* Perform a sign operation (private key stays on the smart card)
* Return the signed has

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;
oberthur.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
diplad.resetBulkPin().then(res => {
}, err => {
    console.error(err)
})
```

Response will look like:

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

### Authenticate

The SDK is able to authenticate a card holder based on a challenge. The challenge can be:

* provided by an external service
* provided by the smart card &#x20;

  An authentication can be interpreted as a signature use case, the challenge is signed data, that can be validated in a back-end process.

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

The expected response for this call should be;

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

### Retrieve supported algorithms

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

The expected response for this call should be;

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