Lehekülje EID application guide lähteteksti vaatamine

<table border=0 width=100% cellpadding=0 cellspacing=0 style="font-size:26px; margin-top:30px; margin-bottom:30px; padding-left:10px; padding-right: 2px; color:#1C4B8C; border-bottom: 3px solid #1B4175; background-color:#E5E5E5;">
<tr>
<td>
Electronic Identity (eID) Application Guide: <br>
where, why, how.
<div style="font-size:12px;">
[[EID_rakendusjuhend|Elektrooniline identiteet infosüsteemides]]
</div>
</td>
<td align=right style="padding-top:2px; padding-bottom:2px;">[[Pilt:Eu_regional_small.jpg]]</td>
</tr>
</table>
[[Pilt:id_kaart_u1.png|left|ID-kaart]]
== Introduction ==
<!-- [[Pilt:idcard_u1.jpg|right|ID-kaart]] -->
The Application Guide provides the basic knowledge required for planning and creating applications using [[A_Short_Introduction_to_eID#ID_card|ID-card]], 
[[A_Short_Introduction_to_eID#Mobile_ID|mobile ID]] and [[A_Short_Introduction_to_eID#Digital_certificate_of_identity|digital ID]] 
(summarized as [[A_Short_Introduction_to_eID|eID]]) in the following.

The guide is divided into three main parts: 

* Overview of applications and scenarios where ID card is an option worth considering. We will bring examples and present analyzes of likely gain and amount of work.
* Technical guides and software examples for employing eID in applications, starting from fairly simple and reaching rather complex applications.
* Technological details and useful background information about eID.

The target audience for this work is everybody related to planning, procuring and developing information systems. The end users are not a target audience of this guide: 
for example, we do not explain how to give a digital signature to a document using eID.

The guide has been developed in several stages  by the Estonian Information System's Authority and several companies within the framework of the EU structural funds programme "Raising Public Awareness about the Information Society".

With questions regarding the contents of the guide, contact [mailto:help@ria.ee help@ria.ee], regarding eID development contact [mailto:abi@id.ee abi@id.ee], regarding the programme visit [https://www.ria.ee/programme/ www.ria.ee/programme].

== Application scenarios: where and why eID ==
<!-- [[Pilt:it_u1.jpg|right|IT]] -->
We divide the [[A_Short_Introduction_to_eID|eID]] application scenarios into five broad scenarios:

* <b>Entrance card</b>. ID card is a sensible alternative to the conventional RFID card in situations where (a) the number of users is big and the set of users changes fairly often (b) security aspects are relatively important (c) a card is typically not used for entrance tens of times per day. ID card is used as an entrance card mostly in schools and libraries.
** Application example and guide: [[ID card as an entrance card]]
* <b>Loyalty card</b>. Id card can be successfully used in client loyalty programmes (shops, transport, libraries etc) as a loyalty card for quick identification of the client. Ease of use for ID card is better than for widely used magnet strip client cards and the clients prefer to carry a single card for all the shops.
** Application example: [[Using_ID-card_as_a_loyalty_card_-_Prisma_Peremarket| Prisma Peremarket chain]]
** Application guide: [[Using_ID-card_as_a_loyalty_card|Using eID as a loyalty card]] <!-- [[eID kasutamine kliendikaardina]] -->
* <b>Logging in</b>. The main use of eID is logging into a web application. Using eID is more secure and easier to administer than logging in with Google or Facebook. eID can be also used as an additional option for loggin into a conventional desktop.
** Application example: [[Case study of logging into the study portal and computers of the Tallinn Uni of Tech]] <!-- [[Rakendamise näide Tallinna Tehnikaülikooli õppeinfosüsteemi ja arvutitesse sisselogimisel| Tallinna Tehnikaülikooli õppeinfosüsteemi ja arvutitesse sisselogimine]] -->
** Application guide: [[eID for authentication in applications/desktop]] <!-- [[eID kasutaja tuvastamiseks veebis/sisselogimiseks]]. -->
* <b>Payments</b>. Due to the security of ID-card it can be employed for implementing several alternative payment methods in places where decreasing the duration of the payment process or decreasing the use of cash is important, or other payment methods can not be applied. The typical schema is to authenticate the user securely at the time of offering the services or selling the goods while conducting the actual payment later or in an alternative channel.
** Application example: [[Using ID-card for payments - Edelaraudtee|Edelaraudtee railways]]  <!-- [[Case_study_Edelaraudtee|Edelaraudtee]] -->
** Application guide: [[Using ID-card for payments|eID for payments]] <!-- [[eID kasutamine makseteks]]. -->
* <b>Digital signatures and paperless office</b>. Using digital signatures instead of signed agreements and confirmations on paper has the greatest potential for savings.
** Application example: [[Application example: SEB|SEB paperless office]]<!-- [[Rakendamise näide: SEB|SEB paberivaba kontor]] -->
** Application guide: [[Using eID for digital signatures and a paperless office]]. <!-- [[eID kasutamine digiallkirjade ja paberivaba kontori korraldamiseks]] -->

<!--
NB! Järgnev on eelmise versiooni tekst, mida sellisena alles ei jäta, kuid kasutame tema osi:
* [[Kasutuselevõtu_analüüs_toorik|Kasutuselevõtu analüüs]]
-->

== Technical guides and examples ==

In short, [[A_Short_Introduction_to_eID#Digital_certificate_of_identity|eID]]  can be used for authentication or digital signatures. Considering details, [[A_Short_Introduction_to_eID#Digital_certificate_of_identity|eID]] can be used in the following ways:

* Using standard software for digital signatures, as explained in the [[Using eID for digital signatures and a paperless office]]. In most cases there is no need to create a new specialized application for digital signatures. 

*In case there is a a real need for a specialized application, look into both [[Command line applications|command line applications]] and [[Complex PHP example|a complex PHP example]]. Browser JavaScript interface [https://github.com/open-eid/hwcrypto.js hwcrypto.js ] should be used for signing with hardware tokens. The component's API documentation along with usage sample can be found https://github.com/open-eid/hwcrypto.js/wiki/ModernAPI.
<!-- * Dokumentide digiallkirjastamine eID standardtarkvara abil, nagu kirjeldatud eelnevas juhendis: [[eID kasutamine digiallkirjade ja paberivaba kontori korraldamiseks]]. Allkirjastamiseks ei olegi enamikul juhtudel vaja erirakendust ehitada. Kui erirakendus siiski vajalik on, tutvu nii järgnevas toodud väikeste [[Käsurea näiterakendused|käsurea-näiterakenduste]] kui [[Näiterakendused_keerukam|keerukama PHP näiterakendusega]]. --> 
* [[Authenticating in web applications]]: the simplest and the most widely used application. Requires both configuration and some development work. The web application reads the user data from the card in cooperation with the web server, guaranteeing at the same time, that the user has entered the correct PIN code. Relatively easy to implement: the first rough attempt takes ca one hour from the developer. Developing and actually usable system takes more time, roughly one day.
<!-- * [[Kasutaja tuvastamine veebis]]: praktikas kõige olulisem ja samas pea kõige lihtsam rakendus, mis nõuab lisaks konfigureerimisele ka veidi arendustööd. Koostöös veebiserveriga loeb veebirakendus kaardilt kasutaja info, tagades samas, et kasutaja on sisestanud õige PIN-koodi. Peale digiallkirjastamise on see eID põhirakendus. Tehniliselt on kasutaja tuvastamist lihtne ja kiire realiseerida: esimese töötava katseni kulub arendajal ca üks tund. Reaalselt kasutusvalmis süsteem võtab loomulikult rohkem aega, kui üldjuhul mitte üle tööpäeva. -->
* [[EID_email_etc|Securing e-mail, VPN-s and logging into the desktop]]: not very widely used, does not require developing a new application. In most cases it should be sufficient to configure existing systems. However, understanding the needs, requirements and configuration options is nontrivial. Expect ca week of work for these applications.
<!-- * [[EID_email_jms|E-maili turvamine, privaatvõrgud ja arvutisse sisselogimine]]: tegu on harvem kasutatavate rakendustega, mille jaoks ei ole jällegi vaja enda rakendust ehitada, olemasolevate süsteemide seadistamisest piisab. Samas on reaalsetest vajadustest arusaamine ja seadistused ise mittetriviaalsed: nende kasutuselevõtuks tasub hinnata ca üks nädal tööd. -->
* [[Command line applications|Command line applications]] for giving digital signatures, checking signatures, encryption. Use these as components for creating larger specialised applications for digital signatures. Examples are in C++ and Java.
<!-- * [[Käsurea näiterakendused|Allkirjastamise, kontrollimise, krüpteerimise]] väikesed käsurea-näiterakendused oma eriarenduste loomiseks: neid saad kasutada eeskätt keerukamate, digiallkirjastamist kasutavate rakenduste ehitamisel konkreetsete komponentidena. Näiterakendused on keeltes C++ ja Java.-->
* [https://github.com/kgilden/php-digidoc a simple PHP library] for digitally signing and verifying digital signatures using estonian id cards.

* [[Complex PHP example|A complex PHP application]]: a full set of eID functions, including signatures, encryption, creating and managing forms. The example application used PHP, .NET, Javascript.
<!-- * [[Näiterakendused_keerukam|Keerukam näiterakendus]]: täiskomplekt eID funktsioone, sh digiallkirjastamine ja krüpteerimine, avalduste loomise ja töötlemise rakenduses. Keeled: PHP, .NET, Javascript. -->

Get the source of the example applications from the Github address [https://github.com/tammet/eid tammet/eid]  
<!--
Näiterakenduste lähtekoodi saad oma arvutisse kõige lihtsamalt Githubist  [https://github.com/tammet/eid tammet/eid koodihoidlast]. -->

== Technological details and background ==

The following materials will be useful for both planning and conducting actual development work:

* [http://id.ee/?lang=en a set of guides for eID] from AS Sertifitseerimiskeskus (the Estonian certification authority), for end users and for developers
* [https://github.com/open-eid GitHub environment] for everyone who wants to contribute to the development of eID software, for example upload their proposals for code improvements
* [http://open-eid.github.io/ eID software architecture document] overview of the components that comprise eID software, their internal and external interfaces
* [[A_Short_Introduction_to_eID|A short introduction to eID]]: ID card, digital ID, etc: what is what.
* [[EID_functionality_short|Overview of the technical functionality of eID]]: how does authentication, signing etc work.
* [[Creating_new_eID_applications_old|Details of eID technology for creating new applications ]]: inner workings of the functionality, plus an overview of useful tools.
* [[Cross-border_eID_old|Cross-border eID, STORK and the European Citizen Card ]]: eID and other countries.

<!--
* [http://id.ee/?lang=en a set of guides for eID] from AS Sertifitseerimiskeskus (the Estonian certification authority), for end users and for developers
* [[A_Short_Introduction_to_eID|A short introduction to eID]]: ID card, digital ID, etc: what is what.
* [[EID_funktsioonide_lühitutvustus_toorik|eID tehniliste funktsioonide lühitutvustus]]: kuidas käib autentimine, digiallkirjastamine, krüpteerimine, kontroll.
* [[Uute_eID_rakenduste_loomine_toorik|eID funktsioonide tehnoloogia nüansid]]: samad funktsioonid detailselt lahti seletatuna, koos ülevaatega praktilistest abivahenditest.
* [[Piiri%C3%BClene_eID,_STORK_ja_Euroopa_kodanikukaart_toorik|Piiriülene eID, STORK ja Euroopa kodanikukaart]]: eID ja teised riigid
-->

[[EID_application_guide_old|old version of the guide]]

<!--


<table border=0 width=100% cellpadding=0 cellspacing=0 style="font-size:26px; margin-top:30px; margin-bottom:30px; padding-left:10px; padding-right: 2px; color:#1C4B8C; border-bottom: 3px solid #1B4175; background-color:#E5E5E5;">
<tr>
<td>
Electronic Identity (eID) Application Guide<br/>
for Software Developers<br/>
<div style="font-size:12px;">
Loe eesti keeles: [[EID_rakendusjuhend|Elektroonilise identiteedi rakendusjuhend tarkvaraarendajatele]]
</div>
</td>
<td align=right style="padding-top:2px; padding-bottom:2px;">[[Pilt:Eu_regional_small.jpg]]</td>
</tr>
</table>

= Introduction =
== The aim of this guide ==
In accordance with the contract between the Estonian Information System's Authority and Cybernetica AS, and within the framework of the EU structural funds programme "Raising Public Awareness about the Information Society", Cybernetica AS has produced an Electronic Identity (eID) Application Guide for Software Developers and conducted necessary analyses and research in the period from 30 March 2012 to 31 October 2012. 

The Application Guide provides the basic knowledge required for the creation of eID usage environments. eID refers to the Estonian ID card, digital ID, the electronic residence card, digital stamp and mobile ID as well as, in specifically mentioned cases, the electronic identities of other countries. 
The guide is divided into two main parts: 
# Introduction of eID and its present possibilities for application; 
# Source code examples in C++, PHP, Java, Javascript and .NET, for MS Windows and Linux platforms. As requested by the customer and due to scope limitations, this version of the guide does not cover the MacOS X platform.

With questions regarding the contents of the guide, contact [mailto:help@ria.ee help@ria.ee], regarding eID development contact [mailto:abi@id.ee abi@id.ee], regarding the programme visit [https://www.ria.ee/programme/ www.ria.ee/programme].

== Target audience. Presuppositions ==
The target audience for this work is IT architects and software developers, as well as persons responsible for IT development contracting. The text part of the guide presupposes familiarity with the basic terms and concepts of the Public Key Infrastructure (PKI), like "digital signature", "certificate", etc. The source code part of the guide presupposes familiarity with the respective programming language or framework. End users are not a target group of this work. 

== Abbreviations ==

{|class="wikitable"
!Abbreviation
!Meaning or explanation
|-
|CA
|Certification Authority
|-
|DSA
|Digital Signatures Act 
|-
|IDA
|Identity Documents Act 
|-
|OCSP
|''Online Certificate Status Protocol'' (protokoll sertifikaadi kehtivuse kontrolliks)
|-
|EISA
|Estonian Information System's Authority 
|-
|DSIS
|The Department of State Information Systems of the Ministry of Economic Affairs and Communications 
|-
|SK
|AS Sertifitseerimiskeskus (Certification Centre)
|-
|SMIT
|IT and Development Centre, Ministry of the Interior 
|-
|STORK
|Secure Identity Across Borders Linked
|}

= [[A_Short_Introduction_to_eID|A short introduction to eID]] =
Facilities for identification, authentication, and digital signing
* [[A_Short_Introduction_to_eID#ID_card|ID Card]]
* [[A_Short_Introduction_to_eID#Digital_certificate_of_identity|Digital Certificate of Identity]]
* [[A_Short_Introduction_to_eID#Digital_stamp|Digital Stamp]]
* [[A_Short_Introduction_to_eID#Electronic_residence_card|Electronic Residence Card]]
* [[A_Short_Introduction_to_eID#Mobile_ID|Mobile ID]]
An overview of the application areas of eID
* [[A_Short_Introduction_to_eID#Personal_authentication|Personal Authentication]]
* [[A_Short_Introduction_to_eID#Digital_signing|Digital Signing]]
* [[A_Short_Introduction_to_eID#Timestamping|Timestamping]]
* [[A_Short_Introduction_to_eID#Encryption_.2F_decryption|Encryption/Decryption]]
* [[A_Short_Introduction_to_eID#Alternative_applications|Alternative Applications]]

= [[General_information_for_developers|General information for developers]] =
* [[General_information_for_developers#Certificates|Certificates]]
* [[General_information_for_developers#File_formats|File formats]]
** [[General_information_for_developers#DDOC|DDOC]]
** [[General_information_for_developers#BDOC|BDOC]]
** [[General_information_for_developers#CDOC|CDOC]]
* [[General_information_for_developers#Development_tools|Development tools]]
** [[General_information_for_developers#DigiDoc_software|DigiDoc software]]
* [[General_information_for_developers#Test_tools|Test tools]]
* [[General_information_for_developers#Using_the_personal_data_file|Using the personal data file]]
** [[General_information_for_developers#Data_contained_on_an_ID_card|Data contained on an ID card]]
** [[General_information_for_developers#Using_the_personal_data_file_on_the_Web|Using the personal data file on the Web]]
* [[General_information_for_developers#eID_supporting_applications:_eidenv.2C_cdigidoc.2C_digidoc-tool.2C_jdigidoc|eID supporting applications: eidenv, cdigidoc, digidoc-tool, jdigidoc]]
* [[General_information_for_developers#Using_the_eToken_crypto-stick|Using the eToken crypto-stick]]
* [[General_information_for_developers#Using_the_ID_card.27s_.40eesti.ee_mail_address|Using the ID card's @eesti.ee mail address]]
* [[General_information_for_developers#Technical_notes_and_observations|Technical notes and observations]]
** [[General_information_for_developers#The_fault_in_pre-2011_ID_cards|The fault in pre-2011 ID cards]]
** [[General_information_for_developers#Padding_oracle_attack|Padding oracle attack]]
** [[General_information_for_developers#USB_rights|USB rights]]
** [[General_information_for_developers#Java_and_libpcsclite|Java and libpcsclite]]
* [[General_information_for_developers#External_links|External links]]

= [[Using_eID_with_existing_applications|Using eID with existing applications]] =
* [[Using_eID_with_existing_applications#Desktop_applications|Desktop applications]]
** [[Using_eID_with_existing_applications#Mail_programs|Mail programs]]
** [[Using_eID_with_existing_applications#Virtual_private_networks|Virtual private networks]]
** [[Using_eID_with_existing_applications#Validity_confirmation_query|Validity confirmation query]]
* [[Using_eID_with_existing_applications#Logging_into_Windows_with_ID_card|Logging into Windows with ID card]]
** [[Using_eID_with_existing_applications#Logging_into_a_domain|Logging into a domain]]
** [[Using_eID_with_existing_applications#Logging_into_a_standalone_computer|Logging into a standalone computer]]
* [[Using_eID_with_existing_applications#Logging_into_Linux_with_an_ID_card|Logging into Linux with an ID card]]
** [[Using_eID_with_existing_applications#Installing|Installing]]
** [[Using_eID_with_existing_applications#Configuration|Configuration]]
** [[Using_eID_with_existing_applications#Linking_an_ID_card_with_a_user_account|Linking an ID card with a user account]]
** [[Using_eID_with_existing_applications#PAM_configuration|PAM configuration]]

= [[Creating_new_eID_applications|Creating new eID applications]] =
* [[Creating_new_eID_applications#Personal_identification|Personal identification]]
** [[Creating_new_eID_applications#Identification_on_the_web|Identification on the web]]
** [[Creating_new_eID_applications#Identification_with_mobile_ID|Identification with mobile ID]]
* [[Creating_new_eID_applications#Digital_signing|Digital signing]]
** [[Creating_new_eID_applications#Digital_signing_with_mobile_ID|Digital signing with mobile ID]]
* [[Creating_new_eID_applications#Encryption|Encryption]]
** [[Creating_new_eID_applications#Loading_certificates_from_LDAP|Loading certificates from LDAP]]
* [[Creating_new_eID_applications#Certificate_validity_check|Certificate validity check]]
** [[Creating_new_eID_applications#In_a_SSL.2FTLS_session|In a SSL/TLS session]]
* [[Creating_new_eID_applications#Using_the_personal_data_file|Using the personal data file]]
** [[Creating_new_eID_applications#Direct_communication_with_the_card|Direct communication with the card]]

= [[ID_card_loyalty_access_analysis|Using the ID card as a loyalty card and in access control systems. Implementation analysis]] =
Using the ID card as a loyalty card and in access control systems 
* [[ID_card_loyalty_access_analysis#Using_the_ID_card_as_a_loyalty_card|Using the ID card as a loyalty card]]
* [[ID_card_loyalty_access_analysis#Using_the_ID_card_in_access_control_systems|Using the ID card in access control systems]]
Implementation analysis
* [[ID_card_loyalty_access_analysis#Benefits|Benefits]]
* [[ID_card_loyalty_access_analysis#Expenses|Expenses]]
* [[ID_card_loyalty_access_analysis#Risks|Risks]]
* [[ID_card_loyalty_access_analysis#Aid_to_contractor_of_IT_developments|Aid to contractor of IT developments]]

= [[Cross-border_eID|Cross-border eID, STORK and the European Citizen Card]] =
* [[Cross-border_eID#General|General]]
* [[Cross-border_eID#STORK|STORK]]
** [[Cross-border_eID#Validity_confirmation_proxying|Validity confirmation proxying]]
* [[Cross-border_eID#European_Citizen_Card|European Citizen Card]]

= [[Sample_applications|Sample applications]] =
* [[Sample_applications#Requirements|Requirements]]
* Languages/frameworks:
** [[Sample_applications#Sample_application_in_C.2B.2B|Sample application in C++]]
** [[Sample_applications#Sample_application_in_Java|Sample application in Java]]
** [[Sample_applications#Sample_application_in_PHP|Sample application in PHP]]
** [[Sample_applications#Sample_application_in_JavaScript|Sample application in JavaScript]]
** [[Sample_applications#Sample_application_in_the_.NET_framework|Sample application in the .NET framework]]
* [[Sample_applications#Claims_presentation_use_case|Claims presentation use case]]
** [[Sample_applications#Web_server|Web server]]
** [[Sample_applications#Web_form|Web form]]
** [[Sample_applications#Claims_handling_service|Claims handling service]]
** [[Sample_applications#Claims_application|Claims application]]
* [[Sample_applications#Signing_application|Signing application]]
* [[Sample_applications#Personal_identification_application|Personal identification application]]
* [[Sample_applications#Signature_verification_application|Signature verification application]]
* [[Sample_applications#Data_decryption_application|Data decryption application]]
* [[Sample_applications#Simple_access_control_in_Apache_httpd|Simple access control in Apache httpd]]
-->