Introduction
The ID-One Cosmo V8-n is part of the Idemia IAS ECC family of cryptographic modules called ID-One Cosmo V8. Modules within this family share the same functionalities and the description of the ID-One Cosmo V8 applies to all versions including the ā-nā subject to this validation. This document describes the functionality provided by the Idemia IAS ECC ID-One smartcard - which is a PKI container - on the T1C-GCL (Generic Connector Library) implemented version:
ID-One Cosmo V8-n; FIPS 140-2 Security Policy
Interface
Copy export interface AbstractIdemia {
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
Examples
Create the Idemia module
Copy T1cSdk .initialize (config) .then (res => {
const idemia = res . client .createIdemia (readerId);
} , err => {
console .error (error)
});
When initialisation is finished you can continue using the aventra object to execute the functions below.
All certificate filters
Copy idemia .allCertFilters () .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data: ['rootCertificate', 'authenticationCertificate', 'encryptionCertificate', 'nonRepudiationCertificate', 'issuerCertificate']
}
all Key references
Copy idemia .allKeyRefs () .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : [ 'authenticate' , 'sign' , 'encrypt' ]
}
all Certificates
When additional parsing of the certificate is needed you can add a boolean to indicate if you want to parse the certificate or not.
Copy const filter = [ 'rootCertificate' , 'authenticationCertificate' , 'encryptionCertificate' ];
idemia .allCerts (filter) .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : {
authenticationCertificate ?: {
certificate? : string ,
certificates? : Array < string > ,
certificateType? : string ,
id? : string ,
parsedCertificate? : Certificate ,
parsedCertificates? : Array < Certificate >
} ,
citizenCertificate ?: {
certificate? : string ,
certificates? : Array < string > ,
certificateType? : string ,
id? : string ,
parsedCertificate? : Certificate ,
parsedCertificates? : Array < Certificate >
} ,
nonRepudiationCertificate ?: {
certificate? : string ,
certificates? : Array < string > ,
certificateType? : string ,
id? : string ,
parsedCertificate? : Certificate ,
parsedCertificates? : Array < Certificate >
} ,,
rootCertificate ?: {
certificate? : string ,
certificates? : Array < string > ,
certificateType? : string ,
id? : string ,
parsedCertificate? : Certificate ,
parsedCertificates? : Array < Certificate >
} ,,
encryptionCertificate ?: {
certificate? : string ,
certificates? : Array < string > ,
certificateType? : string ,
id? : string ,
parsedCertificate? : Certificate ,
parsedCertificates? : Array < Certificate >
} ,
}
}
Token data
This will return information of the Aventra card.
Copy idemia .tokenData () .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : {
version ?: string ,
serialNumber ?: string ,
label ?: string ,
changeCounter ?: number ,
}
}
Certificate
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:
Copy idemia .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:
Copy idemia .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:
Copy idemia .nonRepudiationCertificate (parseCertsBoolean) .then (res => {
} , err => {
console .error (err)
})
Issuer certificate
Copy idemia .issuerCertificate (parseCertsBoolean) .then (res => {
} , err => {
console .error (err)
})
Encryption certificate
Copy aventra .encryptionCertificate (parseCertsBoolean) .then (res => {
} , err => {
console .error (err)
})
The expected response for these calls should be in the following format;
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string
}
}
Verify pin
Copy const data = {
pin : "1234" , // optional
osDialog : true // optional
}
idemia .verifyPin (data) .then (res => {
} , err => {
console .error (err)
})
The expected response for these calls should be in the following format;
Copy {
success : true ,
data : {
certificate ?: string ,
certificates ?: Array < string > ,
certificateType ?: string ,
id ?: string
}
}
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)
To sign data, an algorithm must be specified in the algorithm
property (see 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 method is called.
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.
Copy const data = {
algorithm : "sha256" ,
data : "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=" ,
id : "123"
}
const bulk = false ;
idemia .sign (data , bulk) .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : {
data : string
}
}
Bulk PIN Reset
The PIN set for bulk signing can be reset by calling this method.
Copy idemia .resetBulkPin () .then (res => {
} , err => {
console .error (err)
})
Response will look like:
Copy {
"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
An authentication can be interpreted as a signature use case, the challenge is signed data, that can be validated in a back-end process
Copy const data = {
algorithm : "sha256" ,
data : "E1uHACbPvhLew0gGmBH83lvtKIAKxU2/RezfBOsT6Vs=" ,
id : "123"
}
idemia .authenticate (data) .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : {
data : string
}
}
Retrieve supported algorithms
Copy idemia .allAlgoRefs (data) .then (res => {
} , err => {
console .error (err)
})
The expected response for this call should be;
Copy {
success : true ,
data : {
ref : [ 'sha256' , 'md5' ]
}
}