Skip to content

Commit d5096d7

Browse files
icedevmlicedevml
committed
update README.md, unify examples, bump to 0.3.1
1 parent c00bf80 commit d5096d7

File tree

5 files changed

+82
-120
lines changed

5 files changed

+82
-120
lines changed

‎README.md‎

Lines changed: 78 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -18,82 +18,9 @@ Library available on PyPi: [pyksef](https://pypi.org/project/pyksef/)
1818
pip3 install pyksef
1919
```
2020

21-
## CLI Usage
22-
23-
### List available PKCS#11 tokens
24-
Command:
25-
```bash
26-
p11_list_tokens \
27-
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll"
28-
```
29-
Example output:
30-
```
31-
TokenRecord(slot=<Slot (slotID=2 flags=7)>, label='PKI Token 1 (Primary)', serial='31333132303030313233343536373839', manufacturer_id='CryptoTech P.S.A.', model='CCGraphitePro', hardware_version=(0, 0), firmware_version=(0, 0), flags=<TokenFlag.LOGIN_REQUIRED|USER_PIN_INITIALIZED|TOKEN_INITIALIZED: 1036>)
32-
TokenRecord(slot=<Slot (slotID=3 flags=7)>, label='PKI Token 2 (QSCD)', serial='31333132303030313233343536373839', manufacturer_id='CryptoTech P.S.A.', model='CCGraphitePro', hardware_version=(0, 0), firmware_version=(0, 0), flags=<TokenFlag.WRITE_PROTECTED|LOGIN_REQUIRED|USER_PIN_INITIALIZED|TOKEN_INITIALIZED: 1038>)
33-
```
34-
35-
### List available private keys/certificates for PKCS#11 token
36-
Command:
37-
```bash
38-
p11_list_objects \
39-
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
40-
--token-label "PKI Token 2 (QSCD)" \
41-
--token-serial "31333132303030313233343536373839"
42-
```
43-
Example output:
44-
```
45-
CertificateRecord(x509_cert=<Certificate(subject=<Name(C=PL,2.5.4.5=PNOPL-12345678900,CN=Jan Kowalski,2.5.4.42=Jan,2.5.4.4=Kowalski)>, ...)>)
46-
PrivateKeyRecord(label='No Friendly Name Available', id='6572df736d642974a2bab6ddba753aefb89afcce', key_type=<KeyType.RSA>)
47-
```
48-
49-
### Fetch certificates stored on a PKCS#11 token
50-
Command:
51-
```bash
52-
p11_list_objects \
53-
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
54-
--token-label "PKI Token 2 (QSCD)" \
55-
--token-serial "31333132303030313233343536373839" \
56-
--output certificates
57-
```
58-
Example output:
59-
```
60-
-----BEGIN CERTIFICATE-----
61-
MIIHe...
62-
-----END CERTIFICATE-----
63-
```
64-
65-
### Perform KSeF authentication using private key available through PKCS#11
66-
Command:
67-
```bash
68-
ksef_auth_pkcs11 \
69-
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
70-
--token-label "PKI Token 2 (QSCD)" \
71-
--key-id 6572df736d642974a2bab6ddba753aefb89afcce \
72-
--context-id-type nip \
73-
--context-id 5421234567
74-
```
75-
Example output:
76-
```json
77-
{"referenceNumber": "XXXXXXXX-XX-XXXXXXXXXX-XXXXXXXXXX-XX", "authenticationToken": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "validUntil": "2026-02-04T15:20:15.6254824+00:00"}}
78-
```
79-
80-
### Perform KSeF authentication using certificate/private key file pair stored on disk
81-
Command:
82-
```bash
83-
ksef_auth_file \
84-
--cert-file ksef.crt \
85-
--key-file ksf.key \
86-
--context-id-type nip \
87-
--context-id 5421234567
88-
```
89-
Example output:
90-
```json
91-
{"referenceNumber": "XXXXXXXX-XX-XXXXXXXXXX-XXXXXXXXXX-XX", "authenticationToken": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "validUntil": "2026-02-04T15:20:15.6254824+00:00"}}
92-
```
93-
9421
## Usage via Python
9522

96-
### PKCS#11 List tokens available with certain provider
23+
### List tokens available with certain PKCS#11 provider
9724

9825
```python
9926
from pyksef.p11 import PKCS11Lib
@@ -112,7 +39,7 @@ TokenRecord(slot=<Slot (slotID=2 flags=7)>, label='PKI Token 1 (Primary)', seria
11239
TokenRecord(slot=<Slot (slotID=3 flags=7)>, label='PKI Token 2 (QSCD)', serial='31333132303030313233343536373839', manufacturer_id='CryptoTech P.S.A.', model='CCGraphitePro', hardware_version=(0, 0), firmware_version=(0, 0), flags=<TokenFlag.WRITE_PROTECTED|LOGIN_REQUIRED|USER_PIN_INITIALIZED|TOKEN_INITIALIZED: 1038>)
11340
```
11441

115-
### PKCS#11 List private keys/certificates available with certain token
42+
### List private keys/certificates available with certain PKCS#11 token
11643

11744
```python
11845
import getpass
@@ -139,8 +66,8 @@ CertificateRecord(x509_cert=<Certificate(subject=<Name(C=PL,2.5.4.5=PNOPL-123456
13966
PrivateKeyRecord(label='No Friendly Name Available', id='6572df736d642974a2bab6ddba753aefb89afcce', key_type=<KeyType.RSA>)
14067
```
14168

142-
### PKCS#11 Authentication
143-
69+
### KSeF XAdES Authentication
70+
#### Using a private key available over PKCS#11
14471
```python
14572
import binascii
14673
import getpass
@@ -191,53 +118,20 @@ auth_res = ksef_auth_xades(
191118
)
192119

193120
# poll authentication state and redeem the actual token
121+
# we may need to wait a little bit before the authentication is approved
194122
auth_state = ksef_poll_auth_finalized(
195123
api_base_url=PROD_API_BASE_URL,
196124
reference_number=auth_res["referenceNumber"],
197125
authentication_token=auth_res["authenticationToken"]["token"]
198126
)
199127

200128
print(json.dumps({
201-
"ksefAuthPKCS11Result": auth_res,
129+
"ksefAuthInitResult": auth_res,
202130
"ksefPollAuthFinalizedResult": auth_state,
203131
}, indent=4))
204132
```
205-
Example output:
206-
```json
207-
{
208-
"ksefAuthPKCS11Result": {
209-
"referenceNumber": "XXXXXXXX-XX-XXXXXXXXXX-XXXXXXXXXX-XX",
210-
"authenticationToken": {
211-
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
212-
"validUntil": "2026-02-09T16:08:59.2602376+00:00"
213-
}
214-
},
215-
"ksefPollAuthFinalizedResult": {
216-
"redeemResult": {
217-
"accessToken": {
218-
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
219-
"validUntil": "2026-02-09T15:38:58.1201962+00:00"
220-
},
221-
"refreshToken": {
222-
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
223-
"validUntil": "2026-02-16T15:23:58.1201962+00:00"
224-
}
225-
},
226-
"authState": {
227-
"startDate": "2026-02-09T15:23:58.1401992+00:00",
228-
"authenticationMethod": "QualifiedSignature",
229-
"status": {
230-
"code": 200,
231-
"description": "Uwierzytelnianie zako\u0144czone sukcesem"
232-
},
233-
"isTokenRedeemed": false
234-
}
235-
}
236-
}
237-
```
238-
239-
### Authentication with private key on local disk
240133

134+
#### Using private key available as PEM file locally on the hard disk
241135
```python
242136
import getpass
243137
import json
@@ -284,21 +178,24 @@ auth_res = ksef_auth_xades(
284178
)
285179

286180
# poll authentication state and redeem the actual token
181+
# we may need to wait a little bit before the authentication is approved
287182
auth_state = ksef_poll_auth_finalized(
288183
api_base_url=PROD_API_BASE_URL,
289184
reference_number=auth_res["referenceNumber"],
290185
authentication_token=auth_res["authenticationToken"]["token"]
291186
)
292187

293188
print(json.dumps({
294-
"ksefAuthFileResult": auth_res,
189+
"ksefAuthInitResult": auth_res,
295190
"ksefPollAuthFinalizedResult": auth_state,
296191
}, indent=4))
297192
```
298-
Example output:
193+
194+
#### Example output
195+
All snippets in this section output their results in the same format.
299196
```json
300197
{
301-
"ksefAuthPKCS11Result": {
198+
"ksefAuthInitResult": {
302199
"referenceNumber": "XXXXXXXX-XX-XXXXXXXXXX-XXXXXXXXXX-XX",
303200
"authenticationToken": {
304201
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
@@ -329,6 +226,71 @@ Example output:
329226
}
330227
```
331228

229+
## CLI Usage
230+
231+
### List available PKCS#11 tokens
232+
Command:
233+
```bash
234+
p11_list_tokens \
235+
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll"
236+
```
237+
Example output:
238+
```
239+
TokenRecord(slot=<Slot (slotID=2 flags=7)>, label='PKI Token 1 (Primary)', serial='31333132303030313233343536373839', manufacturer_id='CryptoTech P.S.A.', model='CCGraphitePro', hardware_version=(0, 0), firmware_version=(0, 0), flags=<TokenFlag.LOGIN_REQUIRED|USER_PIN_INITIALIZED|TOKEN_INITIALIZED: 1036>)
240+
TokenRecord(slot=<Slot (slotID=3 flags=7)>, label='PKI Token 2 (QSCD)', serial='31333132303030313233343536373839', manufacturer_id='CryptoTech P.S.A.', model='CCGraphitePro', hardware_version=(0, 0), firmware_version=(0, 0), flags=<TokenFlag.WRITE_PROTECTED|LOGIN_REQUIRED|USER_PIN_INITIALIZED|TOKEN_INITIALIZED: 1038>)
241+
```
242+
243+
### List available private keys/certificates for PKCS#11 token
244+
Command:
245+
```bash
246+
p11_list_objects \
247+
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
248+
--token-label "PKI Token 2 (QSCD)" \
249+
--token-serial "31333132303030313233343536373839"
250+
```
251+
Example output:
252+
```
253+
CertificateRecord(x509_cert=<Certificate(subject=<Name(C=PL,2.5.4.5=PNOPL-12345678900,CN=Jan Kowalski,2.5.4.42=Jan,2.5.4.4=Kowalski)>, ...)>)
254+
PrivateKeyRecord(label='No Friendly Name Available', id='6572df736d642974a2bab6ddba753aefb89afcce', key_type=<KeyType.RSA>)
255+
```
256+
257+
### Fetch certificates stored on a PKCS#11 token
258+
Command:
259+
```bash
260+
p11_list_objects \
261+
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
262+
--token-label "PKI Token 2 (QSCD)" \
263+
--token-serial "31333132303030313233343536373839" \
264+
--output certificates
265+
```
266+
Example output:
267+
```
268+
-----BEGIN CERTIFICATE-----
269+
MIIHe...
270+
-----END CERTIFICATE-----
271+
```
272+
273+
### Perform KSeF authentication using private key available through PKCS#11
274+
Command:
275+
```bash
276+
ksef_auth_pkcs11 \
277+
--pkcs11-dll "C:\Program Files\Krajowa Izba Rozliczeniowa S.A\Szafir 2.0\bin\CCGraphiteP11p.x64.dll" \
278+
--token-label "PKI Token 2 (QSCD)" \
279+
--key-id 6572df736d642974a2bab6ddba753aefb89afcce \
280+
--context-id-type nip \
281+
--context-id 5421234567
282+
```
283+
284+
### Perform KSeF authentication using certificate/private key file pair stored on disk
285+
Command:
286+
```bash
287+
ksef_auth_file \
288+
--cert-file ksef.crt \
289+
--key-file ksf.key \
290+
--context-id-type nip \
291+
--context-id 5421234567
292+
```
293+
332294
## Troubleshooting
333295

334296
If you see the following exception even though the DLL physically exists at the path indicated:

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pyksef"
7-
version = "0.3.0"
7+
version = "0.3.1"
88
description = "KSeF Authentication library"
99
readme = "README.md"
1010
authors = [

‎src/pyksef/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""KSeF XAdES Authentication Library"""
22

3-
__version__ = "0.3.0"
3+
__version__ = "0.3.1"
44

55
from pyksef.auth import ksef_auth_xades
66

‎src/pyksef/cli/ksef_auth_file.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ def cli():
8282
)
8383

8484
print(json.dumps({
85-
"ksefAuthFileResult": auth_res,
85+
"ksefAuthInitResult": auth_res,
8686
"ksefPollAuthFinalizedResult": auth_state,
8787
}, indent=4))
8888

‎src/pyksef/cli/ksef_auth_pkcs11.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ def cli():
104104
)
105105

106106
print(json.dumps({
107-
"ksefAuthPKCS11Result": auth_res,
107+
"ksefAuthInitResult": auth_res,
108108
"ksefPollAuthFinalizedResult": auth_state,
109109
}, indent=4))
110110

0 commit comments

Comments
 (0)