PyBankID Documentation

Transcription

1 PyBankID Documentation Release Henrik Blidh

2

3 Contents 1 Getting Started Installation Dependencies Usage BankID JSON Client BankID SOAP Client PyBankID Exceptions API Certificates Production certificates Converting/splitting certificates Test server certificate API Indices and tables 19 Python Module Index 21 i

4 ii

5 PyBankID is a client for providing BankID services as a Relying Party, i.e. providing authentication and signing functionality to end users. This package provides a simplifying interface for initiating authentication and signing orders and then collecting the results from the BankID servers. If you intend to use PyBankID in your project, you are advised to read the BankID Relying Party Guidelines before doing anything else. There, one can find information about how the BankID methods are defined and how to use them. If you use PyBankID in production and want updates on new releases and notifications about important changes to the BankID service, send a mail to the developer of this package to be added to the PyBankID mailing list. Contents 1

6 2 Contents

7 CHAPTER 1 Getting Started 1.1 Installation PyBankID can be installed though pip: pip install pybankid To remedy the InsecurePlatformWarning problem detailed below (Python 2, urllib3 and certificate verification), you can install pybankid with the security extras: pip install pybankid[security] This installs the pyopenssl, ndg-httpsclient and pyasn1 packages as well. In Linux, this does however require the installation of some additional system packages: sudo apt-get install build-essential libssl-dev libffi-dev python-dev See the cryptography package s documentation for details. 1.2 Dependencies PyBankID makes use of the following external packages: requests>=2.7.0 zeep>=1.3.0 six>=

8 1.2.1 Python 2, urllib3 and certificate verification An InsecurePlatformWarning is issued when using the client in Python 2 (See urllib3 documentation). This can be remedied by installing pyopenssl according to this issue and docstrings in requests. Optionally, the environment variable PYBANKID_DISABLE_WARNINGS can be set to disable these warnings. 4 Chapter 1. Getting Started

9 CHAPTER 2 Usage There are two different clients available in the bankid package: the bankid.client.bankidclient, which uses the SOAP-based API that is being deprecated in February 2020, and the bankid.jsonclient. BankIDJSONClient, which uses the new JSON API released in February Any new deployment using PyBankID should use the JSON Client! 2.1 BankID JSON Client The Relying Party client using the v5 JSON API Usage Create a client: >>> from bankid import BankIDJSONClient >>> client = BankIDJSONClient(certificates=('path/to/certificate.pem',... 'path/to/key.pem')) Connection to production server is the default in the client. If test server is desired, send in the test_server=true keyword in the init of the client. When using the JSON client, all authentication and signing calls requires the end user s ip address to be included the requests. An authentication order is initiated as such: >>> client.authenticate(end_user_ip=' ',... personal_number="yyyymmddxxxx") { 'autostarttoken': '798c1ea1-e67a-4df6-a2f6-164ac223fd52', 'orderref': 'a9b791c3-459f-492b-bf b' } and a sign order is initiated in a similar fashion: 5

10 >>> client.sign(end_user_ip=' ',... user_visible_data="the information to sign.",... personal_number="yyyymmddxxxx") { 'autostarttoken': '798c1ea1-e67a-4df6-a2f6-164ac223fd52', 'orderref': 'a9b791c3-459f-492b-bf b' } Since the BankIDJSONClient is using the BankID v5 JSON API, the personal_number can now be omitted when calling authenticate and sign. See BankID Relying Party Guidelines for more information about this. The status of an order can then be studied by polling with the collect method using the received orderref: >>> client.collect(order_ref="a9b791c3-459f-492b-bf b") { 'hintcode': 'outstandingtransaction', 'orderref': 'a9b791c3-459f-492b-bf b', 'status': 'pending' } >>> client.collect(order_ref="a9b791c3-459f-492b-bf b") { 'hintcode': 'usersign', 'orderref': 'a9b791c3-459f-492b-bf b', 'status': 'pending' } >>> c.collect(order_ref="a9b791c3-459f-492b-bf b") { 'completiondata': { 'cert': { 'notafter': ' ', 'notbefore': ' ' }, 'device': { 'ipaddress': ' ' }, 'ocspresponse': 'MIIHegoBAKCCB[...]', 'signature': 'PD94bWwgdmVyc2lv[...]', 'user': { 'givenname': 'Namn', 'name': 'Namn Namnsson', 'personalnumber': 'YYYYMMDDXXXX', 'surname': 'Namnsson' } }, 'orderref': 'a9b791c3-459f-492b-bf b', 'status': 'complete' } Please note that the collect method should be used sparingly: in the BankID Relying Party Guidelines it is specified that collect should be called every two seconds and must not be called more frequent than once per second API bankid.jsonclient BankID JSON Client Created on by hbldh 6 Chapter 2. Usage

11 class bankid.jsonclient.bankidjsonclient(certificates, test_server=false) The client to use for communicating with BankID servers via the v.5 API. Parameters certificates (tuple) Tuple of string paths to the certificate to use and the key to sign with. test_server (bool) Use the test server for authenticating and signing. authenticate(end_user_ip, personal_number=none, requirement=none, **kwargs) Request an authentication order. The collect() method is used to query the status of the order. Note that personal number is not needed when authentication is to be done on the same device, provided that the returned autostarttoken is used to open the BankID Client. Example data returned: { } "orderref":"131daac9-16c beb f37288", "autostarttoken":"7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6" Parameters end_user_ip (str) IP address of the user requesting the authentication. personal_number (str) The Swedish personal number in format YYYYMMD- DXXXX. requirement (dict) An optional dictionary stating how the signature must be created and verified. See BankID Relying Party Guidelines, section 13.5 for more details. Returns The order response. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server. cancel(order_ref ) Cancels an ongoing sign or auth order. This is typically used if the user cancels the order in your service or app. Parameters order_ref (str) The UUID string specifying which order to cancel. Returns Boolean regarding success of cancellation. Return type bool Raises BankIDError raises a subclass of this error when error has been returned from server. collect(order_ref ) Collects the result of a sign or auth order using the orderref as reference. RP should keep on calling collect every two seconds as long as status indicates pending. RP must abort if status indicates failed. The user identity is returned when complete. Example collect results returned while authentication or signing is still pending: 2.1. BankID JSON Client 7

12 { } "orderref":"131daac9-16c beb f37288", "status":"pending", "hintcode":"usersign" Example collect result when authentication or signing has failed: { } "orderref":"131daac9-16c beb f37288", "status":"failed", "hintcode":"usercancel" Example collect result when authentication or signing is successful and completed: { } "orderref":"131daac9-16c beb f37288", "status":"complete", "completiondata": { "user": { "personalnumber":" ", "name":"karl Karlsson", "givenname":"karl", "surname":"karlsson" }, "device": { "ipaddress":" " }, "cert": { "notbefore":" ", "notafter":" " }, "signature":"<base64-encoded data>", "ocspresponse":"<base64-encoded data>" } See BankID Relying Party Guidelines Version: 3.0 for more details about how to inform end user of the current status, whether it is pending, failed or completed. Parameters order_ref (str) The orderref UUID returned from auth or sign. Returns The CollectResponse parsed to a dictionary. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server. sign(end_user_ip, user_visible_data, personal_number=none, requirement=none, user_non_visible_data=none, **kwargs) Request an signing order. The collect() method is used to query the status of the order. Note that personal number is not needed when signing is to be done on the same device, provided that the returned autostarttoken is used to open the BankID Client. Example data returned: 8 Chapter 2. Usage

13 { } "orderref":"131daac9-16c beb f37288", "autostarttoken":"7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6" Parameters end_user_ip (str) IP address of the user requesting the authentication. user_visible_data (str) The information that the end user is requested to sign. personal_number (str) The Swedish personal number in format YYYYMMD- DXXXX. requirement (dict) An optional dictionary stating how the signature must be created and verified. See BankID Relying Party Guidelines, section 13.5 for more details. user_non_visible_data (str) Optional information sent with request that the user never sees. Returns The order response. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server. 2.2 BankID SOAP Client The Relying Party client using the v4 SOAP API. This client will be deprecated in February Prior to this a PendingDeprecationWarning will be issued on using Usage First, create a BankIDClient: >>> from bankid import BankIDClient >>> client = BankIDClient(certificates=('path/to/certificate.pem',... 'path/to/key.pem')) Connection to production server is the default in the client. If test server is desired, send in the test_server=true keyword in the init of the client. The production server for the BankID server is undergoing an update. Until June 2019 there are two endpoints that can be used, and PyBankID will use the newer one unless legacy_mode=true is entered at BankIDClient creation. A sign order is then placed by >>> client.sign(user_visible_data="the information to sign.",... personal_number="yyyymmddxxxx") {'autostarttoken': '798c1ea1-e67a-4df6-a2f6-164ac223fd52', 'orderref': 'a9b791c3-459f-492b-bf b'} and an authentication order is initiated by 2.2. BankID SOAP Client 9

14 >>> client.authenticate(personal_number="yyyymmddxxxx") {'autostarttoken': '798c1ea1-e67a-4df6-a2f6-164ac223fd52', 'orderref': 'a9b791c3-459f-492b-bf b'} The status of an order can then be studied by polling with the collect method using the received orderref: >>> client.collect(order_ref="a9b791c3-459f-492b-bf b") {'progressstatus': 'OUTSTANDING_TRANSACTION'} >>> client.collect(order_ref="a9b791c3-459f-492b-bf b") {'progressstatus': 'USER_SIGN'} >>> client.collect(order_ref="a9b791c3-459f-492b-bf b") {'ocspresponse': 'MIIHfgoBAKCCB3cw[...]', 'progressstatus': 'COMPLETE', 'signature': 'PD94bWwgdmVyc2lvbj0[...]', 'userinfo': {'givenname': 'Namn', 'ipaddress': ' ', 'name': 'Namn Namnsson', 'notafter': datetime.datetime(2016, 9, 9, 22, 59, 59), 'notbefore': datetime.datetime(2014, 9, 9, 23, 0), 'personalnumber': 'YYYYMMDDXXXX', 'surname': 'Namnsson'}} Please note that the collect method should be used sparingly: in the BankID Relying Party Guidelines. it states that collect should be called every two seconds and must not be called more frequent than once per second API bankid.client BankID Client Created on by hbldh class bankid.client.bankidclient(certificates, test_server=false, legacy_mode=false) The client to use for communicating with BankID servers. Parameters certificates (tuple) Tuple of string paths to the certificate to use and the key to sign with. test_server (bool) Use the test server for authenticating and signing. legacy_mode (bool) Use the old production server endpoint (will be removed in June 2019) authenticate(personal_number, **kwargs) Request an authentication order. The collect() method is used to query the status of the order. Parameters personal_number (str) The Swedish personal number in format YYYYM- MDDXXXX. Returns The OrderResponse parsed to a dictionary. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server. collect(order_ref ) Collect the progress status of the order with the specified order reference. 10 Chapter 2. Usage

15 Parameters order_ref (str) The UUID string specifying which order to collect status from. Returns The CollectResponse parsed to a dictionary. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server. file_sign(**kwargs) Request a file signing order. The collect() method is used to query the status of the order. Note: Not implemented due to that the method is deprecated. Raises NotImplementedError This method is not implemented. sign(user_visible_data, personal_number=none, **kwargs) Request an signing order. The collect() method is used to query the status of the order. Parameters user_visible_data (str) The information that the end user is requested to sign. personal_number (str) The Swedish personal number in format YYYYMMD- DXXXX. Returns The OrderResponse parsed to a dictionary. Return type dict Raises BankIDError raises a subclass of this error when error has been returned from server BankID SOAP Client 11

16 12 Chapter 2. Usage

17 CHAPTER 3 PyBankID Exceptions These are all the exceptions and warnings that PyBankID can raise. 3.1 API bankid.exceptions PyBankID Exceptions Created on , 08:29 exception bankid.exceptions.accessdeniedrperror(*args, **kwargs) Access permission denied error. Code: ACCESS_DENIED_RP Reason: RP does not have access to the service or requested operation. Action by RP: RP must not try the same request again. This is an internal error within RP s system and must not be communicated to the user as a BankID-error. exception bankid.exceptions.alreadyinprogresserror(*args, **kwargs) Failure to create new order due to one already in progress. Code: ALREADY_IN_PROGRESS Reason: An order for this user is already in progress. The order is aborted. No order is created. Action by RP: RP must inform the user that a login or signing operation is already initiated for this user. Message RFA3 should be used. exception bankid.exceptions.bankiderror(*args, **kwargs) Parent exception class for all PyBankID errors. exception bankid.exceptions.bankidwarning Warning class for PyBankID. 13

18 exception bankid.exceptions.cancellederror(*args, **kwargs) User had issue a cancel on the order. Code: CANCELLED Reason: The order was cancelled. The system received a new order for the user. Action by RP: RP must inform the user. Message RFA3. exception bankid.exceptions.certificateerror(*args, **kwargs) Error due to certificate issues. Code: CERTIFICATE_ERR Reason: This error is returned if: 1. The user has entered wrong security code too many times in her mobile device. The Mobile BankID cannot be used. 2. The users BankID is revoked. 3. The users BankID is invalid. Action by RP: RP must inform the user. Message RFA3. exception bankid.exceptions.clienterror(*args, **kwargs) Remote technical error. Code: CLIENT_ERR Reason: Internal technical error. It was not possible to create or verify the transaction. Action by RP: RP must not automatically try again. RP must inform the user. Message RFA12. exception bankid.exceptions.expiredtransactionerror(*args, **kwargs) Error due to collecting on an expired order. Code: EXPIRED_TRANSACTION Reason: The order has expired. The BankID security app/program did not start, the user did not finalize the signing or the RP called collect too late. Action by RP: RP must inform the user. Message RFA8. exception bankid.exceptions.internalerror(*args, **kwargs) Remote server error. Code: INTERNAL_ERROR Reason: Internal technical error in the BankID system. Action by RP: RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used. exception bankid.exceptions.invalidparameterserror(*args, **kwargs) User induced error. Code: INVALID_PARAMETERS Reason: Invalid parameter. Invalid use of method. Action by RP: RP must not try the same request again. This is an internal error within RP s system and must not be communicated to the user as a BankID error. exception bankid.exceptions.maintenanceerror(*args, **kwargs) The service is temporarily out of service. 14 Chapter 3. PyBankID Exceptions

19 Action by RP: RP may try again without informing the user. If this error is returned repeatedly, RP must inform the user. Message RFA5. exception bankid.exceptions.notfounderror(*args, **kwargs) An erroneously URL path was used. Action by RP: RP must not try the same request again. This is an internal error within RP s system and must not be communicated to the user as a BankID error. exception bankid.exceptions.requesttimeouterror(*args, **kwargs) It took too long time to transmit the request. Action by RP: RP must not automatically try again. This error may occur if the processing at RP or the communication is too slow. RP must inform the user. Message RFA5 exception bankid.exceptions.retryerror(*args, **kwargs) Remote server error, different from InternalError. Code: RETRY Reason: Internal technical error in the BankID system. Action by RP: RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used. exception bankid.exceptions.startfailederror(*args, **kwargs) Error handling the order s progression due to RP/user issues. Code: START_FAILED Reason: The user did not provide her ID, or the RP requires autostarttoken to be used, but the client did not start within a certain time limit. The reason may be: 1. RP did not use autostarttoken when starting BankID security program/app. 2. The client software was not installed or other problem with the user s computer. Action by RP: 1. The RP must use autostarttoken when starting the client. 2. The RP must inform the user. Message RFA17. exception bankid.exceptions.unauthorizederror(*args, **kwargs) RP does not have access to the service. Action by RP: RP must not try the same request again. This is an internal error within RP s system and must not be communicated to the user as a BankID error. exception bankid.exceptions.usercancelerror(*args, **kwargs) User had issue a cancel on the order. Code: USER_CANCEL Reason: The user decided to cancel the order. Action by RP: RP must inform the user. Message RFA API 15

20 16 Chapter 3. PyBankID Exceptions

21 CHAPTER 4 Certificates 4.1 Production certificates If you want to use BankID in a production environment, then you will have to purchase this service from one of the selling banks. They will then provide you with a certificate that can be used to authenticate your company/application with the BankID servers. This certificate has to be processed somewhat to be able to use with PyBankID, and how to do this depends on what the selling bank provides you with Test certificate The certificate to use when developing against the BankID test servers can be obtained through PyBankID: >>> import os >>> import bankid >>> dir_to_save_cert_and_key_in = os.path.expanduser('~') >>> cert_and_key = bankid.create_bankid_test_server_cert_and_key( dir_to_save_cert_and_key_in) >>> print(cert_and_key) ['/home/hbldh/certificate.pem', '/home/hbldh/key.pem'] >>> client = bankid.bankidjsonclient( certificates=cert_and_key, test_server=true) The test certificate is available on BankID Technical Information webpage. The bankid.certutils. create_bankid_test_server_cert_and_key() in the bankid.certutils module fetches that test certificate, splits it into one certificate and one key part and converts it from.p12 or.pfx format to pem. These can then be used for testing purposes, by sending in test_server=true keyword in the BankIDClient or BankIDJSONClient. 17

22 4.2 Converting/splitting certificates To convert your production certificate from PKCS_12 format to two pem, ready to be used by PyBankID, one can do the following: >>> from bankid.certutils import split_certificate >>> split_certificate('/path/to/certificate.p12', '/destination/folder/', 'password_for_certificate_p12') ('/destination/folder/certificate.pem', '/destination/folder/key.pem') It can also be done via regular OpenSSL terminal calls: openssl pkcs12 -in /path/to/certificate.p12 -passin pass:password_for_certificate_p12 -out /destination/folder/certificate.pem -clcerts -nokeys openssl pkcs12 -in /path/to/certificate.p12 -passin pass:password_for_certificate_p12 -out /destination/folder/key.pem -nocerts -nodes Note: This also removes the password from the private key in the certificate, which is a requirement for using the PyBankID package in an automated way. 4.3 Test server certificate 4.4 API bankid.certutils Certificate Utilities Created by hbldh bankid.certutils.create_bankid_test_server_cert_and_key(destination_path) Fetch the P12 certificate from BankID servers, split it into a certificate part and a key part and save them as separate files, stored in PEM format. Parameters destination_path (str) The directory to save certificate and key files to. Returns The path tuple (cert_path, key_path). Return type tuple bankid.certutils.split_certificate(certificate_path, destination_folder, password=none) Splits a PKCS12 certificate into Base64-encoded DER certificate and key. This method splits a potentially password-protected PKCS12 certificate (format.p12 or.pfx) into one certificate and one key part, both in pem format. Returns Tuple of certificate and key string data. Return type tuple 18 Chapter 4. Certificates

23 CHAPTER 5 Indices and tables genindex modindex search 19

24 20 Chapter 5. Indices and tables

25 Python Module Index b bankid.certutils, 18 bankid.client, 10 bankid.exceptions, 13 bankid.jsonclient, 6 21

26 22 Python Module Index

27 Index A AccessDeniedRPError, 13 AlreadyInProgressError, 13 authenticate() (bankid.client.bankidclient method), 10 authenticate() (bankid.jsonclient.bankidjsonclient method), 7 B bankid.certutils (module), 18 bankid.client (module), 10 bankid.exceptions (module), 13 bankid.jsonclient (module), 6 BankIDClient (class in bankid.client), 10 BankIDError, 13 BankIDJSONClient (class in bankid.jsonclient), 6 BankIDWarning, 13 C cancel() (bankid.jsonclient.bankidjsonclient method), 7 CancelledError, 13 CertificateError, 14 ClientError, 14 collect() (bankid.client.bankidclient method), 10 collect() (bankid.jsonclient.bankidjsonclient method), 7 create_bankid_test_server_cert_and_key() (in module bankid.certutils), 18 E ExpiredTransactionError, 14 F file_sign() (bankid.client.bankidclient method), 11 I InternalError, 14 InvalidParametersError, 14 M MaintenanceError, 14 N NotFoundError, 15 R RequestTimeoutError, 15 RetryError, 15 S sign() (bankid.client.bankidclient method), 11 sign() (bankid.jsonclient.bankidjsonclient method), 8 split_certificate() (in module bankid.certutils), 18 StartFailedError, 15 U UnauthorizedError, 15 UserCancelError, 15 23