AAC01 SAMA 4 Middleware CartaoCidadao ManualTecnico v1

Projecto Carto de Cidado
Manual tcnico do Middleware Carto

de Cidado
Julho 2007
Verso 1.0
Este documento apresenta a descrio das interfaces

disponibilizadas pelo middlewaredo Carto de Cidado.
Destina-se a tcnicos, analistas e arquitectos de tecnologias de
informao com o objectivo de promover o desenvolvimento de
aplicaes que interajam com o novo documento de identificao
nacional.
Tabela de Contedos
1.
Viso Global.........................................................................................................4
2.
Documentao CSP.............................................................................................6
3.
2.1.
Introduo ...................................................................................................6
2.2.
A interface Crypto API ..............................................................................6
2.2.1.
CryptAcquireContext..........................................................................7
2.2.2.
CryptReleaseContext...........................................................................8
2.2.3.
CryptGenerateKey...............................................................................8
2.2.4.
CryptDeriveKey...................................................................................9
2.2.5.
CryptDestroyKey.................................................................................9
2.2.6.
CryptSetKeyParam..............................................................................9
2.2.7.
CryptGetKeyParam ...........................................................................10
2.2.8.
CryptSetProvParam...........................................................................10
2.2.9.
CryptGetProvParam..........................................................................10
2.2.10.
CryptSetHashParam..........................................................................11
2.2.11.
CryptGetHashParam.........................................................................11
2.2.12.
CryptExportKey.................................................................................11
2.2.13.
CryptImportKey ................................................................................12
2.2.14.
CryptEncrypt......................................................................................12
2.2.15.
CryptDecrypt......................................................................................13
2.2.16.
CryptCreateHash...............................................................................13
2.2.17.
CryptHashData ..................................................................................14
2.2.18.
CryptHashSessionKey ......................................................................14
2.2.19.
CryptSignHash...................................................................................14
2.2.20.
CryptDestroyHash ............................................................................15
2.2.21.
CryptVerifySignature........................................................................15
2.2.22.
CryptGenRandom .............................................................................15
2.2.23.
CryptGetUserKey ..............................................................................16
2.2.24.
CryptDuplicateHash .........................................................................16
2.2.25.
CryptDuplicateKey............................................................................16
Documentao PKCS#11 .................................................................................17
Technical manual for the Portuguese

eID Middleware 1.0
2/35
May 2007
3.1.
A interface PKCS#11................................................................................17
3.1.1.
4.
Chamadas API implementadas ....................................................17
3.1.1.1.
Funes Gerais...............................................................................17
3.1.1.2.
Funes de gesto de Slot e token ..............................................17
3.1.1.3.
Funes de gesto de sesso........................................................17
3.1.1.4.
Funes de gesto de objectos.....................................................18
3.1.1.5.
Funes de assinatura ..................................................................18
3.1.1.6.
Funes de digest..........................................................................18
3.1.1.7.
Funes de gerao aleatria (a aguardar confirmao).........18
3.1.2.
Mecanismos de assinatura suportados...........................................18
3.1.3.
Informaes de Slot e token .............................................................19
3.1.4.
Comportamento da chave de no-repdio....................................19
Documentao eID Lib API .............................................................................20

4.1.
Gesto de verses e compatibilidade ....................................................20
4.2.
Insero de PIN.........................................................................................20
4.3.
Aplicao Multi-threaded .......................................................................21
4.4.
Organizao API.......................................................................................21
4.5.
Funes de Initialisation e termination.................................................21
4.6.
Funes de Identity..................................................................................21
4.7.
Funes General purpose de alto nvel.................................................22
4.8.
Funes relacionadas com CVC .............................................................22
4.9.
Detalhes da API C/C++ ..........................................................................23
4.10.
Caching de ficheiros.................................................................................33
4.11.
Cdigos de Erro ........................................................................................33

eID Middleware 1.0
3/35
May 2007
1.
Viso Global
As seguintes interfaces podem ser encontradas no middleware do Carto de

Cidado:
-
CryptoAPI/CSP
PKCS#11
eID lib ( = a SDK ou Software Development Kit)
A CSP est apenas disponvel em ambiente Windows; as outras 2 bibliotecas

esto disponveis em Windows, Linux e Mac OS X. As primeiras 2 interfaces
so APIs standard para operaes criptogrficas; a eID lib tem uma API nonstandard que direccionada funcionalidade no-criptogrfica do Carto de
Cidado.
No Windows, estas bibliotecas podem ser encontradas na pasta System32; no
Mac OS X no directrio /usr/local/lib e em Linux depende do directrio de
instalao.
Este documento fornece informao para programadores sobre como
desenvolver aplicaes com base nestas interfaces.
Para informaes ou guias sobre como usar estas bibliotecas, por favor
consulte os Manuais de Utilizador respectivos.
Adicionalmente, as seguintes aplicaes esto presentes no middleware:
eID GUI
Esta aplicao pode ser usada para ver e gerir a informao no carto eID:
-
Ler e mostrar informao sobre o cidado e fotografia
Ler e mostrar a morada do cidado
Ler os certificados do governo e do cidado
Registar os certificados do governo e do cidado (apenas Windows)
Gesto de cdigos PIN (Testar o PIN, Alterar o PIN)
Gerir a Pasta pessoal
Ver informao especfica de ministrios
Tray applet
Esta aplicao instalada como uma funcionalidade da rea de notificao.
No Windows, aparece normalmente no canto inferior direito do ecr, no Mac
no canto superior direito do ecr. Quando activada (o utilizador pode
eID Middleware 1.0
4/35
May 2007
desactiv-la), verifica se um carto eID est inserido. Aps inserir o carto

ser mostrada a fotografia do cidado durante uns segundos.
Ir tambm registar automaticamente (se esta opo estiver activada) os
certificados do carto na Microsoft certificate store, caso ainda no estejam
registados. Quando o carto removido os certificados registados so
automaticamente removidos da certificate store (se esta opo estiver
activada).
Este modo tambm conhecido como modo Kiosk. Esta funcionalidade a
nvel de certificados apenas implementada na plataforma Windows devido
s outras plataformas (Mac e Linux) no suportarem o conceito de certificate
stores.
Por favor consulte o Manual de Utilizador para mais informao sobre estas
aplicaes.

eID Middleware 1.0
5/35
May 2007
2.
Documentao CSP
2.1. Introduo
Para as aplicaes standard Microsoft (Office, Outlook...) criado um

Cryptographic Service Provider (CSP) que implementa as operaes
criptogrficas do smartcard. Uma aplicao nunca chamar esta
implementao directamente mas sim atravs de uma interface standard
chamada Crypto API. A implementao CSP utiliza a segunda interface
implementada, PKCS#11. Esta interface usada por aplicaes no standard
Microsoft.
Quando uma nova aplicao criada, o programador que decide qual das
Aplicaes
Microsoft
Crypto
API
Aplicaes no
Microsoft
Aplicaes
custom
CSP
PKCS#11
duas interfaces utilizar para oferecer funcionalidade criptogrfica ao

utilizador.
2.2. A interface Crypto API

O Microsoft Cryptographic API 2.0 (CryptoAPI) permite a programadores
de aplicaes adicionarem funcionalidade de autenticao, encoding, e
encriptao s suas aplicaes baseadas em Win32. Os programadores de
aplicaes podem usar funes da CryptoAPI sem necessidade de
eID Middleware 1.0
6/35
May 2007
conhecerem a implementao subjacente, da mesma forma que podem usar

uma biblioteca grfica sem terem conhecimento sobre a configurao de
hardware.
A componente CSP do middleware estabelece a ligao entre a abstracta
CryptoAPI e a interface PKCS#11 subjacente. O programador nunca ir
chamar nenhuma das funes do CSP directamente mas sim atravs da
CryptoAPI. Nas seces abaixo ser apresentada uma descrio das chamadas
API que a CryptoAPI encaminha para o CSP para processamento. Este
documento no fornece informao detalhada sobre a operao de cada
chamada API. Para este tipo de informao por favor consulte a Microsoft
Developer Network (MSDN).
O carto de identidade Portugus apenas suporta operaes de assinatura
digital. Todas as funes no relacionadas com esta operao criptogrfica
no so implementadas. O carto contm dois pares de chaves que podem ser
usados para assinaturas digitais; o primeiro para autenticao e o segundo
para no-repudio (assinaturas legalmente vinculativas). Devido a isto alguns
parmetros passados para as funes da CryptoAPI no tm significado. Por
exemplo na chamada API CryptGetUserKey passado um parmetro
chamado dwKeySpec. Este parmetro usado para definir qual o tipo de
chave a obter, AT_KEYEXCHANGE ou AT_SIGNATURE. No entanto, no
caso do CSP do Carto de Cidado este parmetro no suficiente para
determinar qual a chave de assinatura a carregar. Neste caso o contentor que
contm o certificado correcto deve ser passado para CryptAcquireContext e
ento a chamada para a funo CryptGetUserKey ser completada com
sucesso.
Apesar do CSP apenas suportar assinaturas digitais, est mesmo assim
registado como um CSP de tipo PROV_RSA_FULL. Isto feito de forma a
permitir a utilizao do CSP em aplicaes standard Microsoft. Chamar
funes da Crypto API que no so usadas num contexto de assinatura
digital resultar num erro indicando que a funcionalidade no est
implementada.
2.2.1. CryptAcquireContext
BOOL WINAPI CryptAcquireContext(HCRYPTPROV *phProv,
LPCTSTR pszContainer,
LPCTSTR pszProvider,
DWORD dwProvType,
DWORD dwFlags);

eID Middleware 1.0
7/35
May 2007
O parmetro pszContainer contm o nome do key container que tem uma

determinada chave do carto. Os nomes dos containers existentes no carto
podem ser obtidos atravs de uma chamada funo CryptGetProvParam.
O parmetro dwFlags pode ser definido para os seguintes valores (de acordo
com a MSDN):
0 (equivalente a CRYPT_SCKEYSET)
CRYPT_VERIFYCONTEXT
CRYPT_NEWKEYSET
CRYPT_MACHINE_KEYSET
CRYPT_DELETEKEYSET
Como a informao relativa a chaves do Carto de Cidado est guardada
num smartcard e o utilizador no tem permisses para criar novos conjuntos
de chaves, os valores CRYPT_NEWKEYSET, CRYPT_MACHINE_KEYSET e
CRYPT_DELETEKEYSET no so suportados. A utilizao destes valores ir
gerar o erro NTE_BAD_FLAGS.
Est definido para este parmetro um valor extra, CRYPT_SCKEYSET. Com
este valor o programador define que adquirido um contexto para a chave,
definido no parmetro pszContainer.
utilizado base CSP, somente para operaes de hashing. Se por algum
motivo o carregamento do base CSP falhar, ento o seguinte cdigo de erro
ser definido atravs de SetLastError():
ERR_CANNOT_LOAD_BASE_CSP (0x1000)
2.2.2. CryptReleaseContext
BOOL WINAPI CryptReleaseContext(HCRYPTPROV hProv,
DWORD dwFlags);
Esta chamada API implementada tal como definido pela MSDN.
2.2.3. CryptGenerateKey
BOOL WINAPI CryptGenKey( HCRYPTPROV hProv,
ALG_ID Algid,
DWORD dwFlags,
HCRYPTKEY *phKey);
eID Middleware 1.0
8/35
May 2007
Visto que as chaves e certificados do Carto de Cidado so pr-instalados

pelo governo e o utilizador no tem permisses para criar novos pares de
chaves, esta chamada API no implementada. Chamar esta funo ir
gerar o erro E_NOTIMPL definido atravs do SetLastError ().
2.2.4. CryptDeriveKey
BOOL WINAPI CryptDeriveKey(HCRYPTPROV hProv,
ALG_ID Algid,
HCRYPTHASH hBaseData,
DWORD dwFlags,
HCRYPTKEY *phKey);
Visto que esta funcionalidade refere-se apenas a chaves de encryptao e estas
no esto presentes no carto, esta chamada API no implementada.
Chamar esta funo ir gerar o erro E_NOTIMPL definido atravs do
SetLastError ().
2.2.5. CryptDestroyKey
BOOL WINAPI CryptDestroyKey(HCRYPTKEY hKey);
2.2.6. CryptSetKeyParam
BOOL WINAPI CryptSetKeyParam(HCRYPTKEY hKey,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags);

eID Middleware 1.0
9/35
May 2007
2.2.7. CryptGetKeyParam
BOOL WINAPI CryptGetKeyParam(HCRYPTKEY hKey,
DWORD dwParam,
BYTE *pbData,
DWORD *pcbData,
DWORD dwFlags);
Since the key material on the Portuguese identity card is pre-installed by the
government and the user does not have the permissions to create additional
key pairs, this API call is not implemented. Calling this function anyway, will
generate the error E_NOTIMPL set through SetLastError ().
2.2.8. CryptSetProvParam
BOOL WINAPI CryptSetProvParam(HCRYPTPROV hProv,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags);
De acordo com a documentao da MSDN o parmetro dwParam pode ser
definido para os seguintes valores:
PP_CLIENT_HWND
PP_KEYSET_SEC_DESCR
O ltimo parmetro no faz sentido visto que no possvel escrever
informao sobre as chaves no carto. Este parmetro dever ser ignorado.
2.2.9. CryptGetProvParam
BOOL WINAPI CryptGetProvParam(HCRYPTPROV hProv,
DWORD dwParam,
BYTE *pbData,
DWORD *pcbData,
DWORD dwFlags);
Esta chamada API implementada com base na documentao MSDN
excepo do parmetro PP_KEYSET_SEC_DESCR, que ignorado.
eID Middleware 1.0
10/35
May 2007
Para o parmetro PP_IMPTYPE devolvido o valor CRYPT_IMPL_MIXED

porque a operao de assinatura executada pelo hardware (smartcard)
enquanto que a operao de hashing executada pelo base cryptographic
provider.
2.2.10. CryptSetHashParam
BOOL WINAPI CryptSetHashParam(HCRYPTHASH hHash,
DWORD dwParam,
BYTE *pbData,
DWORD dwFlags);
Esta chamada API implementada com base na documentao MSDN.
O parmetro dwParam = HP_HASHVAL implementado mas deve ser usado
com cuidado. Este parmetro foi definido de forma a dar s aplicaes a
possibilidade de assinar hash values, sem ter acesso base data. Porque a
aplicao (e muito menos o utilizador) no pode ter ideia do que est a ser
assinado, esta operao intrinsecamente arrisacada.
2.2.11. CryptGetHashParam
BOOL WINAPI CryptGetHashParam(HCRYPTHASH hHash,
DWORD dwParam,
BYTE *pbData,
DWORD *pcbData,
DWORD dwFlags);
2.2.12. CryptExportKey
BOOL WINAPI CryptExportKey(HCRYPTKEY hKey,
HCRYPTKEY hExpKey,
DWORD dwBlobType,
DWORD dwFlags,
BYTE *pbData,
DWORD *pcbDataLen);
eID Middleware 1.0
11/35
May 2007
Esta funo pode ser usada para exportar a chave pblica associada ao
parmetro hKey. O handle de uma chave pblica pode ser obtido atravs de
uma chamada funo CryptGetUserKey. Visto que as chaves privadas esto
guardadas num smartcard e a exportao destas no permitida, apenas
PUBLICKEYBLOB pode ser definido como dwBlobType. Devido ao facto de
apenas as chaves pblicas poderem ser exportadas, o parmetro hExpKey no
utilizado e deve portanto ser definido como NULL. A chave pblica
retornada como parmetro pbData. Para obter o comprimento dos dados o
parmetro pbData deve ser definido como NULL. O comprimento dos dados
que ser devolvido ento colocado no parmetro pcbDataLen. Se o buffer
para esta funo no for suficientemente grande, ser devolvido o erro
ERROR_MORE_DATA, e o valor correcto para o comprimento do buffer ser
colocado no parmetro pcbDataLen.
2.2.13. CryptImportKey
BOOL WINAPI CryptImportKey(HCRYPTPROV hProv,
BYTE *pbData,
DWORD dwDataLen,
HCRYPTKEY hPubKey,
DWORD dwFlags,
HCRYPTKEY *phKey);
Visto que os chaves e certificados do Carto de Cidado so pr-instalados
pelo governo e o utilizador no tem permisses para criar pares de chaves
adicionais, esta chamada API no implementada. Chamar esta funo ir
gerar o erro E_NOTIMPL definido atravs de SetLastError ().
2.2.14. CryptEncrypt
BOOL WINAPI CryptEncrypt(HCRYPTKEY hKey,
HCRYPTHASH hHash,
BOOL Final,
DWORD dwFlags,
BYTE *pbData,
DWORD *pcbData,
DWORD cbBuffer);

eID Middleware 1.0
12/35
May 2007
Tal como estipulado pelo Governo Portugus, no suportada a utilizao

das chaves para encriptao. Deste modo esta chamada API no
implementada. Chamar esta funo ir gerar o erro E_NOTIMPL definido
atravs de SetLastError ().
Caso no futuro sejam adicionadas chaves de encriptao ao Carto de
Cidado, ento esta funo ser tambm implementada.
2.2.15. CryptDecrypt
BOOL WINAPI CryptDecrypt(HCRYPTKEY hKey,
HCRYPTHASH hHash,
BOOL Final,
DWORD dwFlags,
BYTE *pbData,
DWORD *pcbData);
Tal como estipulado pelo Governo Portugus, no suportada a utilizao
das chaves para encriptao. Deste modo esta chamada API no
implementada. Chamar esta funo ir gerar o erro E_NOTIMPL definido
atravs de SetLastError ().
Caso no futuro sejam adicionadas chaves de encriptao ao Carto de
Cidado, ento esta funo ser tambm implementada.
2.2.16. CryptCreateHash
BOOL WINAPI CryptCreateHash(HCRYPTPROV hProv,
ALG_ID Algid,
HCRYPTKEY hKey,
DWORD dwFlags,
HCRYPTHASH *phHash);
Esta chamada API implementada com base na documentao MSDN. Um
erro adicional pode ser devolvido atravs de SetLastError ():
ERR_INVALID_PROVIDER_HANDLE (0x1001)
Este erro indica que o handle esperado por hProv no foi encontrado (no foi
criado usando CryptAcquireContext ())
O processamento desta chamada delegado a uma base CSP.

eID Middleware 1.0
13/35
May 2007
2.2.17. CryptHashData
BOOL WINAPI CryptHashData(HCRYPTHASH hHash,
BYTE *pbData,
DWORD cbData,
DWORD dwFlags);
Esta chamada API implementada com base na documentao MSDN. No
parmetro dwFlags um valor (excepto 0) pode ser especificado:
CRYPT_USERDATA. Dependendo da base CSP escolhida poder ou no ser
implementado. Por exemplo a Microsoft Base CSP no implementa este
parmetro.
O processamento desta chamada delegado a uma base CSP.
2.2.18. CryptHashSessionKey
BOOL WINAPI CryptHashSessionKey(HCRYPTHASH hHash,
HCRYPTKEY hKey,
DWORD dwFlags);
Visto que algumas das chamadas subjacentes necessrias para usar esta
funo no so de momento implementadas por este CSP, esta chamada
tambm no est disponvel. Chamar esta funo ir gerar o erro
E_NOTIMPL definido atravs de SetLastError ().
2.2.19. CryptSignHash
BOOL WINAPI CryptSignHash(HCRYPTHASH hHash,
DWORD dwKeySpec,
LPCTSTR sDescription,
DWORD dwFlags,
BYTE *pbSignature,
DWORD *pdwSigLen);
Quando esta funo chamada, efectuada uma tentativa de conexo ao
Carto de Cidado (smartcard). Se alguma destas operaes falhar, o seguinte
erro pode ser gerado atravs de SetLastError ():
ERR_CANNOT_LOGON_TO_TOKEN (0x1004)
eID Middleware 1.0
14/35
May 2007
De modo a assinar os dados hash, necessrio ler alguma informao (por

exemplo o comprimento da chave) do smartcard. Caso ocorra um erro
durante esta operao a seguinte mensagem de erro ser gerada atravs de
SetLastError ():
ERR_CANNOT_GET_TOKEN_SLOT_INFO (0x1003)
O mecanismo de assinatura utilizado para produzir assinaturas digitais
CKM_RSA_PKCS. Por favor consulte a documentao PKCS#11 para
informao detalhada sobre este mecanismo.
Os seguintes algoritmos de hashing podem ser usados para assinatura de
dados: MD2, MD4, MD5, SHA-1 e SSL3 SHAMD5. Apesar dos algoritmos de
hashing MDx ainda estarem disponvels para retrocompatibilidade,
aconselhado o uso de SHA-1 para novas aplicaes.
2.2.20. CryptDestroyHash
BOOL WINAPI CryptDestroyHash(HCRYPTHASH hHash);
2.2.21. CryptVerifySignature
BOOL WINAPI CryptVerifySignature(HCRYPTHASH hHash,
BYTE *pbSignature,
DWORD dwSigLen,
HCRYPTKEY hPubKey,
LPCTSTR sDescription,
DWORD dwFlags);
Esta funo implementada por motivos de convenincia. Esta chamada
delegada para a base CSP.
2.2.22. CryptGenRandom
BOOL WINAPI CryptGenRandom(HCRYPTPROV hProv,
DWORD dwLen,
BYTE *pbBuffer);

eID Middleware 1.0
15/35
May 2007
Esta chamada API implementada com base na documentao MSDN. Os

dados inseridos atravs de pbBuffer sero usados como origem para a gerao
aleatria.
2.2.23. CryptGetUserKey
BOOL CryptGetUserKey(HCRYPTPROV hProv,
DWORD dwKeySpec,
HCRYPTKEY *phUserKey);
Esta chamada devolve um handle para a chave pblica do contentor de
chaves que foi definido atravs de CryptAcquireContext. Especificar
AT_SIGNATURE para o parmetro dwKeySpec no suficiente porque com
essa informao o CSP no consegue determinar que chave de assinatura
devolver. Por este motivo a chave a carregar tem de ser primeiro especificada
atravs de CryptAcquireContext.
2.2.24. CryptDuplicateHash
BOOL WINAPI CryptDuplicateHash(HCRYPTHASH hHash,
DWORD *pdwReserved,
DWORD dwFlags,
HCRYPTHASH phHash);
2.2.25. CryptDuplicateKey
BOOL WINAPI CryptDuplicateKey(HCRYPTKEY hKey,
DWORD *pdwReserved,
DWORD dwFlags,
HCRYPTKEY* phKey);
Visto que as chaves e certificados so guardados no smartcard, esta chamada
API no implementada. Chamar esta funo ir gerar o erro E_NOTIMPL
definido atravs de SetLastError ().

eID Middleware 1.0
16/35
May 2007
3.
Documentao PKCS#11
3.1. A interface PKCS#11
A interface PKCS#11 (v2.20) utilizada por aplicaes no Microsoft como

por exemplo o Netscape. Aplicaes desenvolvidas podem recorrer a este
interface em vez do interface CryptoAPI. A interface PKCS#11 por vezes
chamada de Cryptoki.
Uma descrio detalhada desta interface est disponvel no website da RSA
Laboratories (http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/).
3.1.1. Chamadas API implementadas

3.1.1.1.
Funes Gerais
C_Initialize,
C_Finalize
C_GetInfo
C_GetFunctionList
3.1.1.2.
Funes de gesto de Slot e token
C_GetSlotList
C_GetSlotInfo
C_GetTokenInfo
C_GetMechanismList
C_GetMechanismInfo
C_WaitForSlotEvent (only non-blocking)
C_SetPin
3.1.1.3.
Funes de gesto de sesso
C_OpenSession
C_CloseSession
C_CloseAllSessions
C_GetSessionInfo
eID Middleware 1.0
17/35
May 2007
C_Login
C_Logout
3.1.1.4.
Funes de gesto de objectos
C_FindObjectsInit
C_FindObjects
C_FindObjectsFinal
C_GetAttributeValue
3.1.1.5.
Funes de assinatura
C_SignInit
C_Sign
C_SignUpdate
C_SignFinal
3.1.1.6.
Funes de digest
C_DigestInit
C_Digest
C_DigestUpdate
C_DigestFinal
3.1.1.7.
Funes de gerao aleatria (a aguardar confirmao)
C_SeedRandom
C_GenerateRandom
3.1.2. Mecanismos de assinatura suportados

Para assinaturas:
-
CKM_RSA_PKCS: both ASN.1-wrapped e hashes puros (MD5, SHA1,

SHA1+MD5, RIPEMD160)
CKM_RIPEMD160_RSA_PKCS, CKM_SHA1_RSA_PKCS,
CKM_MD5_RSA_PKCS
Para digests:
eID Middleware 1.0
18/35
May 2007
CKM_SHA_1, CKM_RIPEMD160, CKM_MD5
3.1.3. Informaes de Slot e token

O carto ser representado como um token PKCS#11 com o PIN de
Autenticao do Cidado servindo como User PIN; no est presente nenhum
SO PIN.
O PIN de Assinatura do Cidado estar ocultado; caso seja necessrio este
ser requisitado atravs de uma caixa de dilogo.
As chaves pblicas, chaves privadas e os certificados que faam parte do
mesmo conjunto tero o mesmo atributo no objecto CKA_ID.
3.1.4. Comportamento da chave de no-repdio

Se uma assinatura for solicitada com esta chave, a prpria biblioteca PKCS#11
mostrar uma caixa de dilogo pedindo ao utilizador para inserir o PIN.

eID Middleware 1.0
19/35
May 2007
4.
Documentao eID Lib API
A SDK est destinada a organizaes cujo objectivo seja desenvolver

aplicaes que utilizam o Carto de Cidado. Este kit de desenvolvimento
lida apenas com os dados identificativos do cidado e no com operaes
criptogrficas.
O kit de desenvolvimento fornecido como:
-
Uma interface C/C++, como biblioteca dinmica
Uma biblioteca Java wrapper (JNI) sobre uma interface C/C++
Uma biblioteca C# wrapper para .NET sobre uma interface C/C++
4.1. Gesto de verses e compatibilidade

O Toolkit gere automaticamente todas as diferentes verses dos cartes. Ao
trabalhar com o Toolkit no h necessidade de preocupao com a forma
como os dados esto gravados no carto, visto estes estarem disponveis de
maneira uniforme atravs da API.
Existem funes de baixo nvel para obter as vrias verses dos componentes
do carto, mas isto apenas direccionado a programadores que necessitam de
aceder a caractersticas muito especficas do carto uma aplicao comum
no dever ter que se preocupar com a verso do carto.
4.2. Insero de PIN

Vrias funes aceitam um parmetro de insero de referncia PIN. Caso
uma referncia PIN seja fornecida e a funo obtiver um access denied
quando tenta aceder a um recurso no carto, esta ir automaticamente pedir
ao utilizador para fornecer um PIN e tentar aceder novamente ao recurso
(caso a verificao do PIN tenha sido bem sucedida). Isto uma verificao
just-in-time do PIN, visto que este s ser solicitado quando necessrio. Por
exemplo, um PIN permanente pode ter sido inserido previamente e ainda ser
vlido. Neste caso, no ser solicitado novamente.

eID Middleware 1.0
20/35
May 2007
4.3. Aplicao Multi-threaded

A biblioteca no thread-safe. da responsabilidade da aplicao que a
chama de no usar a biblioteca simultaneamente em threads paralelas.
Nota: O CSP thread-safe, mas no poder chamar o CSP numa thread e o
Toolkit noutra thread.
4.4. Organizao API

As funes esto divididas em 4 categorias:
Funes Initialisation e termination, mandatrias para iniciar e

terminar a utilizao do toolkit
Funes de Identity, usadas para obter dados identificativos (nome,

morada, etc.) do carto
Funes General purpose de alto nvel, usadas para aceder a dados de

uma forma genrica (ficheiros, PIN), principalmente em outras
aplicaes que no as de Identity. No h necessidade de usar estas
funes para aceder a dados identificativos.
4.5. Funes de Initialisation e termination

Estas funes so necessrias para inicializar e terminar a eID Lib.
Funes:
- PTEID_Init()
- PTEID_Exit()
4.6. Funes de Identity

Todas as funes de Identity so auto-suficientes. Isto , no necessrio
chamar nenhuma outra funo em conjunto com uma funo identity (excepto
as de inicializao e trmino). No necessrio inserir um PIN para ler
ficheiros de identity. Todas estas funes podem ser chamadas
independentemente do estado presente do carto caso outra DF (Data File)
que no a identity estiver seleccionada, etc.
Importante: certifique-se que leu a seco relativa s funes SOD abaixo!
eID Middleware 1.0
21/35
May 2007
Funes:
-
PTEID_GetID()
PTEID_GetAddr()
PTEID_GetPic()
PTEID_GetCertificates()
PTEID_GetPINs()
PTEID_GetTokenInfo()
4.7. Funes General purpose de alto nvel

Estas funes do acesso integradas com o toolkit a funes gerais para
aplicaes que necessitem de efectuar outras aces para alm do acesso aos
dados identificativos (nome, morada, etc.)
Funes
-
PTEID_SelectADF()
PTEID_ReadFile()
PTEID_WriteFile()
PTEID_VerifyPIN()
PTEID_ChangePIN()
PTEID_UnblockPIN()
PTEID_UnblockPIN_Ext()
PTEID_IsActivated()
PTEID_Activate()
4.8. Funes relacionadas com CVC

Para assegurar que os dados no carto so genunos, um ficheiro SOD
colocado no carto contendo as hashes criptogrficas assinadas sobre os
dados identificativos, a morada, a fotografia e a chave de autenticao pblica
do carto (pelo menos um usado para autenticao CVC).
As seguintes funes usaro este SOD para verificao:
-
os dados de identificao: PTEID_GetID()
a morada: PTEID_GetAddr() and PTEID_CVC_GetAddr()
a fotografia: PTEID_GetPic()

eID Middleware 1.0
22/35
May 2007
a chave de autenticao pblica do carto: PTEID_CVC_Init()
As seguintes funes so fornecidas para controlar a verificao SOD:

- PTEID_SetSODChecking ()
- PTEID_SetSODCAs()
4.9. Detalhes da API C/C++

A API C/C++ descrita em detalhe abaixo:
Para a API C# sobre esta API C/C++, por favor consulte as header files no
directrio dotnet da SDK.
Para a API Java sobre esta API C/C++, por favor consulte os Javadocs no
directrio java da SDK.
PTEIDLIB_API long
PTEID_Activate
( char *
pszPin,
unsigned char * pucDate,

unsigned long ulMode
)
Activar o carto (= actualizar um ficheiro especfico do carto).
Caso o carto j tenha sido activado, devolvido o erro
SC_ERROR_NOT_ALLOWED.
Parmetros:
pszPin in: valor do PIN de Activao
pucDate in: a data corrente no formato DD MM YY YY em formato BCD (4
bytes), ex: {0x17 0x11 0x20 0x06} para 17 de Novembro de 2006)
ulMode in: modo: MODE_ACTIVATE_BLOCK_PIN para bloquear o PIN
de Activao, ou 0 para o inverso (deve apenas ser usado para
testes).

eID Middleware 1.0
23/35
May 2007
PTEIDLIB_API long
PTEID_ChangePIN
( unsigned char
char *
char *
long *
PinId,
pszOldPin,
pszNewPin,
triesLeft
)
Mudar um PIN.
Parmetros:
PinId
in: o PIN ID, ver o registo PTEID_Pins
pszOldPin in: o valor actual do PIN, caso seja NULL o PIN ser solicitado
ao utilizador
pszNewPin in: o novo valor do PIN, caso seja NULL o PIN ser solicitado ao
utilizador
triesLeft
out: as restantes tentativas de PIN
PTEIDLIB_API long
PTEID_CVC_Authenticate
( unsigned char *
pucSignedChallenge,
iSignedChallengeLen
int
)
Concluir a autenticao CVC com o carto, para ser chamado aps

PTEID_CVC_Init()
Parmetros:
pucSignedChallenge in: no challenge que foi assinado pela chave privada
correspondente ao CVC
iSignedChallengeLen in: o comprimento de ucSignedChallenge tem de ser
128
PTEIDLIB_API long PTEID_CVC_GetAddr( PTEID_ADDR * AddrData )

Ler o ficheiro de morada sobre um canal CVC e colocar os contedos num registo
PTEID_ADDR.
PTEID_CVC_Init() e PTEID_CVC_Authenticate() bem sucedidos tero de ser
efectuados anteriormente.
Parmetros:
AddrData out: o endereo de um registo PTEID_ADDR

eID Middleware 1.0
24/35
May 2007
PTEIDLIB_API long
PTEID_CVC_Init
( const unsigned char *

int
unsigned char *
int
pucCert,
iCertLen,
pucChallenge,
iChallengeLen
)
Iniciar uma autenticao CVC com o carto.
O challenge resultante dever ser assinado com a chave privada correspondente ao
certificado CVC (raw RSA signature) e fornecido na funo
PTEID_CVC_Authenticate().
Parmetros:
pucCert
iCertLen
pucChallenge
iChallengeLen
in: o CVC como um byte array

in: o comprimento de ucCert
out: o challenge que ser assinado pela chave CVC privada
in: o comprimento reservado para ucChallenge, deve ser 128
PTEIDLIB_API long
PTEID_CVC_ReadFile
( unsigned char *
int
unsigned char *
unsigned long *
file,
filelen,
out,
outlen
)
Ler os contedos de um ficheiro sobre um canal CVC.
efectuados anteriormente. Se *outlen for menor que os contedos do ficheiro,
apenas os bytes *outlen sero lidos. Se *outlen for maior os contedos do ficheiro
so devolvidos sem erro.
Parmetros:
file
in: o caminho do ficheiro a ler (e.g. {0x3F, 0x00, 0x5F, 0x00, 0xEF,
0x05}
filelen in: o coprimento do caminho do ficheiro (ex: 6)
out
out: o buffer para armazenar os contedos do ficheiro
outlen out: o nmero de bytes a ler / nmero de bytes lidos.

eID Middleware 1.0
25/35
May 2007
PTEIDLIB_API long PTEID_CVC_WriteAddr( const PTEID_ADDR * AddrData )

Escrever o ficheiro de endereo sobre um canal CVC. PTEID_CVC_Init() e
PTEID_CVC_Authenticate() bem sucedidos tero de ser efectuados anteriormente.
Parmetros:
AddrData in: o endereo de um registo PTEID_ADDR
PTEIDLIB_API long
PTEID_CVC_WriteFile
( unsigned char *
int
unsigned long
const unsigned char *
unsigned long
unsigned long
file,
filelen,
ulFileOffset,
in,
inlen,
ulMode
)
Escrever para um ficheiro no carto sobre um canal CVC
efectuados anteriormente
Parmetros:
file
in: o caminho do ficheiro a ler (ex: {0x3F, 0x00, 0x5F, 0x00, 0xEF,
0x05} )
filelen
in: o comprimento do caminho do ficheiro (ex: 6)
ulFileOffset in: escolher qual o offset no ficheiro por onde iniciar a escrita
in
in: os contedos do ficheiro
inlen
in: o nmero de bytes a escrever
ulMode
in: definir como CVC_WRITE_MODE_PAD para preencher o
ficheiro com zeros se (ulFileOffset + inlen) for menor que o
comprimento do ficheiro
PTEIDLIB_API long
PTEID_CVC_WriteSOD
( unsigned long
const unsigned char *
unsigned long
unsigned long
ulFileOffset,
in,
inlen,
ulMode
)
Esta funo chama PTEID_CVC_WriteFile() com o ficheiro SOD file como caminho.
Parmetros:
ulFileOffset in: escolher qual o offset no ficheiro por onde iniciar a escrita
in
in: os contedos do ficheiro
eID Middleware 1.0
26/35
May 2007
inlen
ulMode
in: o nmero de bytes a escrever

in: definir como CVC_WRITE_MODE_PAD para preencher o
ficheiro com zeros se (ulFileOffset + inlen) for menor que o
comprimento do ficheiro
PTEIDLIB_API long PTEID_Exit( unsigned long ulMode )

Limpa todos os dados usados pelo toolkit. Esta funo tem que ser chamada no
final do programa.
Parmetros:
ulMode in: modo de sada, PTEID_EXIT_LEAVE_CARD ou
PTEID_EXIT_UNPOWER
PTEIDLIB_API long PTEID_GetAddr( PTEID_ADDR * AddrData )

Ler os dados de Morada:
Parmetros:
AddrData out: o endereo do registo PTEID_ADDR
PTEIDLIB_API long PTEID_GetCertificates ( PTEID_Certifs *
Certifs )
Ler todos os certificados pessoais e de CA

Parmetros:
Certifs out: o endereo do registo PTEID_Certifs
PTEIDLIB_API long
PTEID_GetCVCRoot
( PTEID_RSAPublicKey * pCVCRootKey
Obter a chave pblica CVC CA que este carto utilize para verificar a chave CVC;
permitir que a aplicao seleccione o certificado CVC correcto para este carto.
No ser alocada nenhuma memria para o registo PTEID_RSAPublicKey struct
por isso os campos modulus e exponent devero ter memria suficiente
alocada para guardar os respectivos valores; e a quantidade de memria deve ser
dada nos campos Lenght.
Por exemplo:
unsigned char modulus[128];
unsigned char exponent[3];
PTEID_RSAPublicKey CVCRootKey = {modulus, sizeof(modulus), exponent,
eID Middleware 1.0
27/35
May 2007
sizeof(exponent)};
Aps retorno bem sucedido, os campos modulusLength e exponentLenght iro
conter os correctos modulus length resp. exponent length.
Parmetros:
pCVCRootKey in: o endereo do registo PTEID_RSAPublicKey
PTEIDLIB_API long PTEID_GetID( PTEID_ID * IDData )

Ler os dados de Identificao
Parmetros
IDData out: o endereo do registo PTEID_ID
PTEIDLIB_API long PTEID_GetPic( PTEID_PIC * PicData )

Ler a fotografia.
Parmetros:
PicData out: o endereo do registo PTEID_PIC
PTEIDLIB_API long PTEID_GetPINs( PTEID_Pins * Pins )

Devolver os PINs (listados nos ficheiros PKCS15).
Parmetros:
Pins out: o endereo do registo PTEID_Pins
PTEIDLIB_API long PTEID_GetTokenInfo( PTEID_TokenInfo * tokenData )

Devolver os contedos de PKCS15 TokenInfo.
Parmetros:
tokenData out: o endereo do registo PTEID_TokenInfo
PTEIDLIB_API long PTEID_Init( char * ReaderName )

Inicializa o toolkit.
Esta funo deve ser chamada antes de qualquer outra; tenta efectuar uma ligao
ao carto e caso no esteja inserido nenhum carto devolvido um erro. Quando o
eID Middleware 1.0
28/35
May 2007
carto removido do leitor, esta funo tem que ser chamada novamente.
Parmetros:
ReaderName in: o nome do leitor PCSC (tal como devolvido por
SCardListReaders()), especifique NULL se quiser seleccionar o
primeiro leitor
PTEIDLIB_API long PTEID_IsActivated( unsigned long * pulStatus )

Obter o estado de activao do carto.
Parmetros:
pulStatus out: o estado de activao: 0 se no estiver activo, 1 se activado
PTEIDLIB_API long
PTEID_ReadFile
( unsigned char *
int
unsigned char *
unsigned long *
unsigned char
file,
filelen,
out,
outlen,
PinId
)
Ler um ficheiro no carto.
Se uma referncia PIN fornecida e necessria para ler o ficheiro, o PIN ser
solicitado e verificado se necessrio. Se *outlen for menor que os contedos do
ficheiro, apenas os bytes *outlen sero lidos. Se *outlen for maior os contedos do
ficheiro so devolvidos sem erro.
Parmetros:
file
in: um byte array contendo o caminho do ficheiro, como por exemplo
{0x3F, 0x00, 0x5F, 0x00, 0xEF, 0x02}, para o ficheiro ID
filelen in: comprimento do ficheiro
out
out: o buffer que guarda os contedos do ficheiro
outlen in/out: nmero de bytes alocados / nmero de bytes lidos
PinId in: o ID do PIN de Morada (apenas necessrio aquando da leitura do
ficheiro de Morada)
PTEIDLIB_API long
PTEID_ReadSOD
( unsigned char *
out,
unsigned long * outlen

)

eID Middleware 1.0
29/35
May 2007
Ler os contedos do ficheiro SOD a partir do carto.

Esta funo chama PTEID_ReadFile() com o ficheiro SOD como caminho. Se *outlen
for menor que os contedos do ficheiro, apenas os bytes *outlen sero lidos. Se
*outlen for maior os contedos do ficheiro so devolvidos sem erro.
Parmetros:
out
out: o buffer para guardar os contedos do ficheiro
outlen in/out: nmero de bytes alocados / nmero de bytes lidos
PTEIDLIB_API long
PTEID_SelectADF
( unsigned char *
adf,
adflen
long
)
Seleccionar um Application Directory File (ADF) atravs da AID (Application ID).

Parmetros
adf
in: a AID da ADF
adflen in: o comprimento
PTEIDLIB_API long
PTEID_SetSODCAs
( PTEID_Certifs * Certifs )
Especificar os certificados (raiz) que so usados para assinar os certificados

DocumentSigner no ficheiro SOD.
(O ficheiro SOD no carto est assinado por um certificado Document Signer, e este
certificado est tambm no SOD)
Por omisso, esta biblioteca l os certificados que esto presentes no directrio
%appdir%/eidstore/certs (%appdir% corresponde ao directrio onde a aplicao
reside). Se este directrio no existir (ou no contiver os certificados correctos para
o carto), dever chamar esta funo para o especificar; ou desactivar a verificao
SOD com a funo PTEID_SetSODChecking(). Se chamar esta funo novamente
com o parmetro NULL, os certificados default sero novamente usados.
Parmetros:
Certifs in: o endereo de PTEID_Certifs, ou NULL
PTEIDLIB_API long PTEID_SetSODChecking( int bDoCheck )

Activar / Desactivar a verificao SOD.
eID Middleware 1.0
30/35
May 2007
Verificao SOD significa que a validade dos dados de identificao, morada,

fotografia e chave pblica de autenticao do carto, verificada de modo a
assegurar que no falsificada. Este processo efectuado atravs da leitura do
ficheiro SOD que contm hashes sobre os dados mencionados acima e est assinada
por um certificado DocumentSigner.
Parmetros:
bDoCheck in: true para activar verificao SOD checking, false para
desactivar
PTEIDLIB_API long
PTEID_UnblockPIN
( unsigned char
char *
char *
long *
PinId,
pszPuk,
pszNewPin,
triesLeft
)
Desbloquear PIN com alterao de PIN.
Se pszPuk == NULL ou pszNewPin == NULL, uma caixa de dilogo mostrada
solicitando o PUK e o novo PIN
Parmetros:
PinId
pszPuk
pszNewPin
triesLeft

in: o valor PUK, se NULL ser solicitado o PUK ao utilizador.
in: o novo PIN, se NULL ser solicitado o PIN ao utilizador.
out: o nmero restante de tentativas PUK
PTEIDLIB_API long
PTEID_UnblockPIN_Ext
( unsigned char
char *
char *
long *
unsigned long
PinId,
pszPuk,
pszNewPin,
triesLeft,
ulFlags
)
Funcionalidade estendida de desbloqueio de PIN
Ex: chamar PTEID_UnblockPIN_Ext() com ulFlags = UNBLOCK_FLAG_NEW_PIN
o mesmo que chamar PTEID_UnblockPIN(...)
Parmetros:
PinId
pszPuk

in: o valor PUK, se NULL ser solicitado o PUK ao utilizador.

eID Middleware 1.0
31/35
May 2007
pszNewPin in: o novo PIN, se NULL ser solicitado o PIN ao utilizador.

triesLeft
out: o nmero restante de tentativas PUK
ulFlags
in: flags: 0, UNBLOCK_FLAG_NEW_PIN,
UNBLOCK_FLAG_PUK_MERGE ou
UNBLOCK_FLAG_NEW_PIN |
UNBLOCK_FLAG_PUK_MERGE
PTEIDLIB_API long
PTEID_VerifyPIN
( unsigned char
char *
long *
PinId,
Pin,
triesLeft
)
Verificar um PIN.
Parmetros:
PinId in: o PIN ID, ver o registo PTEID_Pins
Pin
in: o valor PIN, se NULL ser solicitado o PIN ao utilizador.
triesLeft out: o nmero restante de tentativas PIN
PTEIDLIB_API long
PTEID_WriteFile
( unsigned char *
int
unsigned char *
unsigned long
unsigned char
file,
filelen,
in,
inlen,
PinId
)
Escrever dados para um ficheiro no carto.
Se for fornecida uma referncia PIN, este ser solicitado e verificado se necessrio
(verificao just-in-time). Esta funo aplica-se apenas a escrita no ficheiro
Personal Data.
Parmetros:
file
in: um array de bytes, contendo o caminho para o ficheiro. Ex: {0x3F,
0x00, 0x5F, 0x00, 0xEF, 0x02} para o ficheiro ID
filelen in: comprimento do ficheiro
in
in: os dados a ser escritos no ficheiro
inlen in: o comprimento dos dados a escrever
PinId in: o ID do PIN de Autenticao, ver o registo PTEID_Pins

eID Middleware 1.0
32/35
May 2007
4.10. Caching de ficheiros

Devido ao facto da leitura de ficheiros do carto ser um processo demorado,
especialmente em leitores mais lentos, certos ficheiros so guardados no disco
rgido quando so lidos pela primeira vez:
-
certos ficheiros pkcs15
o ficheiro ID
o ficheiro SOD
O ficheiro de morada no cached pois pode vir a mudar e porque contm

dados protegidos por PIN.
O ficheiro SOD pode tambm vir a mudar por isso uma pequena parte do
SOD lido do carto para verificar se a SOD que foi cached ainda est
actualizada. Caso no esteja, o ficheiro completo lido do carto e copiado
novamente para o disco rgido.
Nota para CVC: existe uma flag no middleware que regista quando o SOD foi
lido e, por exemplo, quando efectua um GetID() e depois GetAddress(), o
SOD no lido novamente para verificar a validade dos dados de Morada.
Como excepo, quando CVC_Write_XXX() chamado, feito um reset
flag.
4.11. Cdigos de Erro

Existem 2 tipos de return codes: os do prprio pteidlib, e os da biblioteca
open-source subjacente pteidlibopensc.
Return codes da biblioteca pteidlib:
#define PTEID_OK
0 /* Function succeeded */
#define PTEID_E_BAD_PARAM
pointer, out of bound, etc.) */
1 /* Invalid parameter (NULL
#define PTEID_E_INTERNAL
failed */
2 /* An internal consistency check
#define PTEID_E_INSUFFICIENT_BUFFER
returned data is too small */
3 /* The data buffer to receive
#define PTEID_E_KEYPAD_CANCELLED
4 /* Input on pinpad cancelled */
#define PTEID_E_KEYPAD_TIMEOUT
5 /* Timout returned from pinpad */
#define PTEID_E_KEYPAD_PIN_MISMATCH
6 /* The two PINs did not match */
#define PTEID_E_KEYPAD_MSG_TOO_LONG
7 /* Message too long on pinpad */

eID Middleware 1.0
33/35
May 2007
#define PTEID_E_INVALID_PIN_LENGTH
8 /* Invalid PIN length */
#define PTEID_E_NOT_INITIALIZED
9 /* Library not initialized */
#define PTEID_E_UNKNOWN
detected, but the source is unknown */
10 /* An internal error has been
Return codes da biblioteca open-source subjacente pteidlibopensc - Licena LGPL:

/* Erros relativos a operaes do leitor */
#define SC_ERROR_READER
-1100
#define SC_ERROR_NO_READERS_FOUND
-1101
#define SC_ERROR_SLOT_NOT_FOUND
-1102
#define SC_ERROR_SLOT_ALREADY_CONNECTED
-1103
#define SC_ERROR_CARD_NOT_PRESENT
-1104
#define SC_ERROR_CARD_REMOVED
-1105
#define SC_ERROR_CARD_RESET
-1106
#define SC_ERROR_TRANSMIT_FAILED
-1107
#define SC_ERROR_KEYPAD_TIMEOUT
-1108
#define SC_ERROR_KEYPAD_CANCELLED
-1109
#define SC_ERROR_KEYPAD_PIN_MISMATCH
-1110
#define SC_ERROR_KEYPAD_MSG_TOO_LONG
-1111
#define SC_ERROR_EVENT_TIMEOUT
-1112
#define SC_ERROR_CARD_UNRESPONSIVE
-1113
#define SC_ERROR_READER_DETACHED
-1114
#define SC_ERROR_READER_REATTACHED
-1115
/* Resultantes de um comando de carto ou relacionado com o carto */

#define SC_ERROR_CARD_CMD_FAILED
-1200
#define SC_ERROR_FILE_NOT_FOUND
-1201
#define SC_ERROR_RECORD_NOT_FOUND
-1202
#define SC_ERROR_CLASS_NOT_SUPPORTED
-1203
#define SC_ERROR_INS_NOT_SUPPORTED
-1204
#define SC_ERROR_INCORRECT_PARAMETERS
-1205
#define SC_ERROR_WRONG_LENGTH
-1206
#define SC_ERROR_MEMORY_FAILURE
-1207
#define SC_ERROR_NO_CARD_SUPPORT
-1208
#define SC_ERROR_NOT_ALLOWED
-1209
#define SC_ERROR_INVALID_CARD
-1210
#define SC_ERROR_SECURITY_STATUS_NOT_SATISFIED
-1211
#define SC_ERROR_AUTH_METHOD_BLOCKED
-1212

eID Middleware 1.0
34/35
May 2007
#define SC_ERROR_UNKNOWN_DATA_RECEIVED
-1213
#define SC_ERROR_PIN_CODE_INCORRECT
-1214
#define SC_ERROR_FILE_ALREADY_EXISTS
-1215
/* Devolvidos pela biblioteca OpenSC quando invocada com argumentos invlidos */

#define SC_ERROR_INVALID_ARGUMENTS
-1300
#define SC_ERROR_CMD_TOO_SHORT
-1301
#define SC_ERROR_CMD_TOO_LONG
-1302
#define SC_ERROR_BUFFER_TOO_SMALL
-1303
#define SC_ERROR_INVALID_PIN_LENGTH
-1304
/* Resultantes de operaes internas da biblioteca OpenSC */

#define SC_ERROR_INTERNAL
-1400
#define SC_ERROR_INVALID_ASN1_OBJECT
-1401
#define SC_ERROR_ASN1_OBJECT_NOT_FOUND
-1402
#define SC_ERROR_ASN1_END_OF_CONTENTS
-1403
#define SC_ERROR_OUT_OF_MEMORY
-1404
#define SC_ERROR_TOO_MANY_OBJECTS
-1405
#define SC_ERROR_OBJECT_NOT_VALID
-1406
#define SC_ERROR_OBJECT_NOT_FOUND
-1407
#define SC_ERROR_NOT_SUPPORTED
-1408
#define SC_ERROR_PASSPHRASE_REQUIRED
-1409
#define SC_ERROR_EXTRACTABLE_KEY
-1410
#define SC_ERROR_DECRYPT_FAILED
-1411
#define SC_ERROR_WRONG_PADDING
-1412
#define SC_ERROR_WRONG_CARD
-1413
/* Relacionados com o PKCS #15 init */

#define SC_ERROR_PKCS15INIT
-1500
#define SC_ERROR_SYNTAX_ERROR
-1501
#define SC_ERROR_INCONSISTENT_PROFILE
-1502
#define SC_ERROR_INCOMPATIBLE_KEY
-1503
#define SC_ERROR_NO_DEFAULT_KEY
-1504
#define SC_ERROR_ID_NOT_UNIQUE
-1505
#define SC_ERROR_CANNOT_LOAD_KEY
-1006
/* Erros que no se enquadram nas categorias acima */

#define SC_ERROR_UNKNOWN
-1900
#define SC_ERROR_PKCS15_APP_NOT_FOUND
-1901

eID Middleware 1.0
35/35
May 2007

AAC01 SAMA 4 Middleware CartaoCidadao ManualTecnico v1

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

AAC01 SAMA 4 Middleware CartaoCidadao ManualTecnico v1

Enviado por

Direitos autorais:

Formatos disponíveis

Projecto Carto de Cidado

Manual tcnico do Middleware Carto

Este documento apresenta a descrio das interfaces

A interface Crypto API ..............................................................................6

Documentao PKCS#11 .................................................................................17

Technical manual for the Portuguese

Chamadas API implementadas ....................................................17

Funes de gesto de Slot e token ..............................................17

Funes de gesto de sesso........................................................17

Funes de gesto de objectos.....................................................18

Funes de assinatura ..................................................................18

Funes de gerao aleatria (a aguardar confirmao).........18

Mecanismos de assinatura suportados...........................................18

Informaes de Slot e token .............................................................19

Comportamento da chave de no-repdio....................................19

Documentao eID Lib API .............................................................................20

Gesto de verses e compatibilidade ....................................................20

Aplicao Multi-threaded .......................................................................21

Funes de Initialisation e termination.................................................21

Funes General purpose de alto nvel.................................................22

Funes relacionadas com CVC .............................................................22

Detalhes da API C/C++ ..........................................................................23

Cdigos de Erro ........................................................................................33

Technical manual for the Portuguese

As seguintes interfaces podem ser encontradas no middleware do Carto de

eID lib ( = a SDK ou Software Development Kit)

A CSP est apenas disponvel em ambiente Windows; as outras 2 bibliotecas

Ler e mostrar informao sobre o cidado e fotografia

Ler e mostrar a morada do cidado

Ler os certificados do governo e do cidado

Registar os certificados do governo e do cidado (apenas Windows)

Gesto de cdigos PIN (Testar o PIN, Alterar o PIN)

Gerir a Pasta pessoal

Ver informao especfica de ministrios

desactiv-la), verifica se um carto eID est inserido. Aps inserir o carto

Technical manual for the Portuguese

Para as aplicaes standard Microsoft (Office, Outlook...) criado um

duas interfaces utilizar para oferecer funcionalidade criptogrfica ao

2.2. A interface Crypto API

conhecerem a implementao subjacente, da mesma forma que podem usar

Technical manual for the Portuguese

O parmetro pszContainer contm o nome do key container que tem uma

Visto que as chaves e certificados do Carto de Cidado so pr-instalados

Technical manual for the Portuguese

Para o parmetro PP_IMPTYPE devolvido o valor CRYPT_IMPL_MIXED

Technical manual for the Portuguese

Tal como estipulado pelo Governo Portugus, no suportada a utilizao

Technical manual for the Portuguese

De modo a assinar os dados hash, necessrio ler alguma informao (por

Technical manual for the Portuguese

Esta chamada API implementada com base na documentao MSDN. Os

Technical manual for the Portuguese

A interface PKCS#11 (v2.20) utilizada por aplicaes no Microsoft como

3.1.1. Chamadas API implementadas

Funes de gesto de Slot e token

Funes de gesto de sesso

Funes de gesto de objectos

Funes de gerao aleatria (a aguardar confirmao)

3.1.2. Mecanismos de assinatura suportados

CKM_RSA_PKCS: both ASN.1-wrapped e hashes puros (MD5, SHA1,

CKM_SHA_1, CKM_RIPEMD160, CKM_MD5

3.1.3. Informaes de Slot e token

3.1.4. Comportamento da chave de no-repdio

Technical manual for the Portuguese