Manual de SDK
Manual de SDK
Manual de SDK
do Cartão de Cidadão
Versão 3.0
Índice
1. Histórico............................................................................................................. 4
2. Introdução.......................................................................................................... 5
3. Abreviaturas e acrónimos.................................................................................. 6
4. Instalação........................................................................................................... 7
4.3 Compiladores.......................................................................................................7
4.4.1. Windows.......................................................................................................... 8
4.4.2. Linux................................................................................................................ 8
4.4.3. MacOS............................................................................................................. 8
5. Procedimentos.................................................................................................... 9
5.1 Pré-condições......................................................................................................9
5.5 PINs...................................................................................................................22
6. Tratamento de erros........................................................................................ 33
8. Notas do Utilizador.......................................................................................... 37
4.3 Compiladores
A lista de compiladores suportados são:
• C++:
◦ Windows: Visual Studio 2013
◦ Linux: GCC ou LLVM (clang);
◦ MacOS: Compilador distribuído pela Apple. Dependendo da versão
pode ser GCC ou LLVM (clang).
• Java - Oracle JDK 8 ou superior
4.4.1. Windows
Para instalar o SDK basta efectuar o download do fcheiro MSI de instalação
e executar.
As bibliotecas C++ (pteidlibCpp.lib e respectivos header fles), Java e C#
fcarão disponíveis em
C:\ Program Files\Portugal Identity Card\sdk\
4.4.2. Linux
Para instalar o SDK é necessario efectuar o download do pacote em formato
deb ou rpm conforme a distribuição Linux que utiliza.
As bibliotecas C++ (libpteidlib.so) e Java (pteidlibj.jar) estão disponíveis em
/usr/local/lib e os respectivos C++ header fles estão em /usr/local/include
Se a instalação for feita a partir do código fonte disponível em
https://svn.gov.pt/projects/ccidadao será necessário instalar as seguintes
dependências (pacotes Ubuntu 18.04, para outras distribuições Linux os nomes
serão diferentes):
◦ libpcsclite-dev ◦ zlib1g-dev
◦ libpoppler-qt5-dev ◦ libpng-dev
◦ openjdk-8-jdk ◦ libopenjp2-7-dev
◦ qtbase5-dev ◦ libzip-dev
◦ qt5-qmake ◦ qt5-default
◦ qtbase5-private-dev ◦ qtdeclarative5-dev
◦ libxerces-c-dev ◦ qtquickcontrols2-5-dev
◦ libxml-security-c-dev ◦ qml-module-qtquick-
controls2
◦ swig
◦ libssl1.0-dev
◦ libcurl4-nss-dev
4.4.3. MacOS
Para instalar o SDK é necessário efectuar o download do pacote de
instalação e executar. O SDK Java fcará disponível em /usr/local/lib/pteid_jni.
No que diz respeito ao SDK C++, os header fles fcam localizados em
/usr/local/include e a biblioteca à qual as aplicações deverão linkar está no
caminho /usr/local/lib/libpteidlib.dylib
5.1 Pré-condições
1. C/C++
Windows/Visual Studio
Adicionar a import library pteidlibCpp.lib ao projecto.
Por forma a conseguir incluir os header fles do SDK adicionar a directoria
“C:\Program Files\ Portugal Identity Card\sdk” nas propriedades do projecto em
“C/C++” → “General” → “Additional Include Directories”
2. Java
Incluir o fcheiro pteidlibj.jar como biblioteca no projecto e adicionar à
library path do java a localização das bibliotecas nativas do SDK (se necessário).
De notar que as classes e métodos de compatibilidade estão disponíveis
no package pteidlib enquanto que as novas classes estão no package
pt.gov.cartaodecidadao
3. C#
Adicionar a biblioteca pteidlib_dotnet.dll às references do projecto Visual
Studio.
As classes e métodos de compatibilidade estão no namespace eidpt
enquanto que as novas classes estão no namespace pt.portugal.eid
#include "eidlib.h"
(…)
int main(int argc, char **argv){
PTEID_InitSDK();
(…)
PTEID_ReleaseSDK();
}
package pteidsample;
import pt.gov.cartaodecidadao.*;
(...)
static {
try {
System.loadLibrary("pteidlibj");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. \n" + e);
System.exit(1);
}
}
public class SamplePTEID {
public static void main(String[] args) {
PTEID_ReaderSet.initSDK();
(…)
PTEID_ReaderSet.releaseSDK();
}
}
namespace PTEIDSample {
class Sample{
(...)
public static void Main(string[] args){
PTEID_ReaderSet.initSDK();
(…)
PTEID_ReaderSet.releaseSDK();
}
}
}
2. Exemplo Java
PTEID_EIDCard card;
PTEID_ReaderContext context;
PTEID_ReaderSet readerSet;
readerSet = PTEID_ReaderSet.instance();
for( int i=0; i < readerSet.readerCount(); i++){
context = readerSet.getReaderByNum(i);
if (context.isCardPresent()){
card = context.getEIDCard();
(...)
}
}
3. Exemplo C#
PTEID_EIDCard card;
PTEID_ReaderContext context;
PTEID_ReaderSet readerSet;
readerSet = PTEID_ReaderSet.instance();
for( int i=0; i < readerSet.readerCount(); i++){
context = readerSet.getReaderByNum(i);
if (context.isCardPresent()){
card = context.getEIDCard();
(...)
}
}
(...)
PTEID_EIDCard& card = context.getEIDCard();
PTEID_EId& eid = card.getID();
2. Exemplo Java
(...)
PTEID_EIDCard card = context.getEIDCard();
PTEID_EId eid = card.getID();
3. Exemplo C#
(...)
PTEID_EIDCard card = context.getEIDCard();
PTEID_EId eid = card.getID();
string nome = eid.getGivenName();
string nrCC = eid.getDocumentNumber();
(...)
(...)
PTEID_EIDCard& card = context.getEIDCard();
PTEID_EId& eid = card.getID();
PTEID_Photo& photoObj = eid.getPhotoObj();
PTEID_ByteArray& praw = photoObj.getphotoRAW(); // formato jpeg2000
PTEID_ByteArray& ppng = photoObj.getphoto(); // formato PNG
(...)
2. Exemplo Java
(...)
PTEID_EIDCard card = context.getEIDCard();
PTEID_EId eid = card.getID();
PTEID_Photo photoObj = eid.getPhotoObj();
PTEID_ByteArray praw = photoObj.getphotoRAW(); // formato jpeg2000
PTEID_ByteArray ppng = photoObj.getphoto(); // formato PNG
(...)
3. Exemplo C#
(...)
PTEID_EIDCard card = context.getEIDCard();
PTEID_EId eid = card.getID();
PTEID_Photo photoObj = eid.getPhotoObj();
PTEID_ByteArray praw = photoObj.getphotoRAW(); // formato jpeg2000
PTEID_ByteArray ppng = photoObj.getphoto(); // formato PNG
(...)
PTEID_EIDCard &card;
unsigned long triesLeft;
(...)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, &triesLeft, true){
PTEID_Address &addr = card.getAddr();
const char * municipio = addr.getMunicipality();
}
2. Exemplo Java
PTEID_EIDCard card;
PTEID_ulwrapper triesLeft = new PTEID_ulwrapper(-1);
PTEID_Address addr;
(...)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, triesLeft, true){
addr = card.getAddr();
String municipio = addr.getMunicipality();
}
3. Exemplo C#
PTEID_EIDCard card;
uint triesLeft;
PTEID_Address addr;
(...)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, ref triesLeft, true){
addr = card.getAddr();
string municipio = addr.getMunicipality();
}
1. Exemplo C++
PTEID_EIDCard &card;
PTEID_ByteArray pb;
bool bOk;
(...)
// leitura
string pdata = card.readPersonalNotes();
// escrita
bOk = card.writePersonalNotes( pb,
card.getPins().getPinByPinRef(PTEID_Pin.AUTH_PIN));
2. Exemplo Java
PTEID_EIDCard card;
(...)
// leitura
String pdata = card.readPersonalNotes();
//escrita
String notes = “a few notes”;
PTEID_ByteArray pb = new PTEID_ByteArray(notes.getBytes(),
notes.getBytes().length);
boolean bOk = card.writePersonalNotes(pb,
card.getPins().getPinByPinRef(PTEID_Pin.AUTH_PIN));
(...)
3. Exemplo C#
PTEID_EIDCard card;
PTEID_ByteArray pb;
boolean bOk;
(...)
// leitura
string pdata = card.readPersonalNotes();
//escrita
bOk = card.writePersonalNotes( pb,
card.getPins().getPinByPinRef(PTEID_Pin.AUTH_PIN));
(...)
Método Descrição
PTEID_Address
Método Descrição
getSide() lado
getLocality() localidade
getPlace() lugar
Método Descrição
getForeignCountry() país
getForeignAddress() endereço
getForeignCity() cidade
getForeignRegion() região
getForeignLocality() localidade
Método Descrição
2. Exemplo em Java
String resultXml;
PTEID_EIDCard card;
PTEID_ulwrapper triesLeft = new PTEID_ulwrapper(-1);
(...)
card.getPins().getPinByPinRef(PTEID_Pin.ADDR_PIN).verifyPin("", triesLeft, true);
PTEID_XmlUserRequestedInfo requestedInfo = new PTEID_XmlUserRequestedInfo();
requestedInfo.add(XMLUserData.XML_CIVIL_PARISH);
(...)
requestedInfo.add(XMLUserData.XML_GENDER);
PTEID_CCXML_Doc result = idCard.getXmlCCDoc(requestedInfo);
resultXml = result.getCCXML();
3. Exemplo em C#
string resultXml;
PTEID_EIDCard card;
uint triesLeft;
(...)
card.getPins().getPinByPinRef(PTEID_Pin.ADDR_PIN).verifyPin("", ref triesLeft,
true);
PTEID_XmlUserRequestedInfo requestedInfo = new PTEID_XmlUserRequestedInfo();
requestedInfo.add(XMLUserData.XML_CIVIL_PARISH);
(...)
requestedInfo.add(XMLUserData.XML_GENDER);
PTEID_CCXML_Doc result = idCard.getXmlCCDoc(requestedInfo);
resultXml = result.getCCXML();
1. Exemplo C++
PTEID_EIDCard& card;
unsigned long triesLeft;
(...)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, &triesLeft, true){
bool bResult = pin.changePin("","", triesLeft, pin.getLabel());
if (!bResult && -1 == triesLeft) return;
}
2. Exemplo Java
PTEID_EIDCard card;
PTEID_ulwrapper triesLeft = new PTEID_ulwrapper(-1);
(...)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, triesLeft, true){
bool bResult = pin.changePin("","", triesLeft, pin.getLabel());
if (!bResult && -1 == triesLeft) return;
}
3. Exemplo C#
PTEID_EIDCard card;
uint triesLeft;
(…)
PTEID_Pins pins = card.getPins();
PTEID_Pin pin = pins.getPinByPinRef(PTEID_Pin.ADDR_PIN);
if (pin.verifyPin(“”, ref triesLeft, true){
bool bResult = pin.changePin("","", triesLeft, pin.getLabel());
if (!bResult && -1 == triesLeft) return;
}
2. Exemplo Java
#include “eidlib.h”
(...)
PTEID_EIDCard &card = readerContext.getEIDCard();
//Ficheiro PDF a assinar
PTEID_PDFSignature signature(“/home/user/input.pdf”);
signature.enableSmallSignatureFormat();
//Assinatura com selo temporal
signature.enableTimestamp();
//No caso de assinatura em batch este parâmetro deve apontar para a directoria de
destino
const char * output = “/home/user/output_signed.pdf”;
card.SignPDF(signature, page, sector, is_landscape, location, reason,
output_file);
PTEID_ByteArray data_to_sign;
(...)
PTEID_EIDCard &card = readerContext.getEIDCard();
(...)
PTEID_ByteArray output = card.Sign(data_to_sign, true);
(...)
2. Exemplo Java
PTEID_ByteArray data_to_sign;
(...)
PTEID_EIDCard card = context.getEIDCard();
(...)
PTEID_ByteArray output= card.Sign(data_to_sign, true);
(...)
3. Exemplo C#
#include “eidlib.h”
(...)
PTEID_EIDCard &card = readerContext.getEIDCard();
//Ficheiro PDF a assinar
PTEID_PDFSignature signature(“/home/user/input.pdf”);
2. Exemplo Java
GetLastWebErrorMessage
CVC_WriteFile
CVC_WriteAddr
CVC_WriteSOD
CVC_WriteFile
CVC_R_DH_Auth
CVC_R_Init