Skip to content

Commit e640562

Browse files
ZhuoZhuoCrayonZhuoZhuoCrayon
committed
docs: The basic usage description is inaccurate (closed #23)
1 parent 0bea639 commit e640562

2 files changed

Lines changed: 119 additions & 121 deletions

File tree

‎readme.md‎

Lines changed: 16 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -42,22 +42,6 @@ $ pip install bk-crypto-python-sdk
4242

4343
**非对称加密**
4444

45-
```python
46-
import os
47-
48-
from bkcrypto import constants
49-
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
50-
from bkcrypto.contrib.basic.ciphers import get_symmetric_cipher
51-
52-
symmetric_cipher: BaseSymmetricCipher = get_symmetric_cipher(
53-
cipher_type=constants.SymmetricCipherType.SM4.value,
54-
common={"key": os.urandom(16)},
55-
)
56-
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
57-
```
58-
59-
**对称加密**
60-
6145
````python
6246
from bkcrypto import constants
6347
from bkcrypto.asymmetric import options
@@ -83,6 +67,22 @@ assert "123" == asymmetric_cipher.decrypt(asymmetric_cipher.encrypt("123"))
8367
assert asymmetric_cipher.verify(plaintext="123", signature=asymmetric_cipher.sign("123"))
8468
````
8569

70+
**对称加密**
71+
72+
```python
73+
import os
74+
75+
from bkcrypto import constants
76+
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
77+
from bkcrypto.contrib.basic.ciphers import get_symmetric_cipher
78+
79+
symmetric_cipher: BaseSymmetricCipher = get_symmetric_cipher(
80+
cipher_type=constants.SymmetricCipherType.SM4.value,
81+
common={"key": os.urandom(16)},
82+
)
83+
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
84+
```
85+
8686
#### 2. 结合 Django 使用
8787

8888
在 Django Settings 中配置加密算法类型
@@ -211,94 +211,6 @@ class IdentityData(models.Model):
211211
password = SymmetricTextField("密码", blank=True, null=True)
212212
```
213213

214-
#### 3. Using Django CipherManager
215-
216-
Configure the encryption algorithm type in Django Settings
217-
218-
```python
219-
from bkcrypto import constants
220-
from bkcrypto.symmetric.options import AESSymmetricOptions, SM4SymmetricOptions
221-
from bkcrypto.asymmetric.options import RSAAsymmetricOptions
222-
223-
BKCRYPTO = {
224-
# Declare the asymmetric encryption algorithm used by the project
225-
"ASYMMETRIC_CIPHER_TYPE": constants.AsymmetricCipherType.SM2.value,
226-
# Declare the symmetric encryption algorithm used by the project
227-
"SYMMETRIC_CIPHER_TYPE": constants.SymmetricCipherType.SM4.value,
228-
"SYMMETRIC_CIPHERS": {
229-
# default - The configured symmetric encryption instance can be configured with multiple instances depending on the project requirements
230-
"default": {
231-
# Optional, used in cases where settings cannot directly obtain the key
232-
# "get_key_config": "apps.utils.encrypt.key.get_key_config",
233-
# Optional, used for ModelField, encrypted with this prefix to store the database, decrypting and analyzing the prefix and selecting the appropriate decryption algorithm
234-
# ⚠️ The prefix and cipher type must be in one-to-one correspondence, and there can be no prefix matching relationship
235-
# "db_prefix_map": {
236-
# SymmetricCipherType.AES.value: "aes_str:::",
237-
# SymmetricCipherType.SM4.value: "sm4_str:::"
238-
# },
239-
# Common parameter configuration, sharing these parameters when initializing different ciphers
240-
"common": {"key": "your key"},
241-
"cipher_options": {
242-
constants.SymmetricCipherType.AES.value: AESSymmetricOptions(key_size=16),
243-
# Blue Whale recommended configuration
244-
constants.SymmetricCipherType.SM4.value: SM4SymmetricOptions(mode=constants.SymmetricMode.CTR)
245-
}
246-
},
247-
},
248-
"ASYMMETRIC_CIPHERS": {
249-
# Configuration same as SYMMETRIC_CIPHERS
250-
"default": {
251-
"common": {"public_key_string": "your key"},
252-
"cipher_options": {
253-
constants.AsymmetricCipherType.RSA.value: RSAAsymmetricOptions(
254-
padding=constants.RSACipherPadding.PKCS1_OAEP
255-
),
256-
constants.AsymmetricCipherType.SM2.value: SM4SymmetricOptions()
257-
},
258-
},
259-
}
260-
}
261-
```
262-
263-
**Asymmetric Encryption**
264-
265-
Use `asymmetric_cipher_manager` to get the `cipher` configured for `BKCRYPTO.ASYMMETRIC_CIPHERS`
266-
267-
```python
268-
from bkcrypto.asymmetric.ciphers import BaseAsymmetricCipher
269-
from bkcrypto.contrib.django.ciphers import asymmetric_cipher_manager
270-
271-
asymmetric_cipher: BaseAsymmetricCipher = asymmetric_cipher_manager.cipher(using="default")
272-
273-
# Encrypt and Decrypt
274-
assert "123" == asymmetric_cipher.decrypt(asymmetric_cipher.encrypt("123"))
275-
# Signature verification
276-
assert asymmetric_cipher.verify(plaintext="123", signature=asymmetric_cipher.sign("123"))
277-
```
278-
279-
**Symmetric Encryption**
280-
281-
Use `symmetric_cipher_manager` to get the `cipher` configured for `BKCRYPTO.SYMMETRIC_CIPHERS`
282-
283-
```python
284-
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
285-
from bkcrypto.contrib.django.ciphers import symmetric_cipher_manager
286-
287-
# using - Specifies a symmetric encryption instance, defaults to 'default'
288-
symmetric_cipher: BaseSymmetricCipher = symmetric_cipher_manager.cipher(using="default")
289-
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
290-
```
291-
292-
**Django ModelField**
293-
294-
```python
295-
from django.db import models
296-
from bkcrypto.contrib.django.fields import SymmetricTextField
297-
298-
299-
class IdentityData(models.Model):
300-
password = SymmetricTextField("Password", blank=True, null=True)
301-
```
302214

303215
## Roadmap
304216

‎readme_en.md‎

Lines changed: 103 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -41,27 +41,10 @@ $ pip install bk-crypto-python-sdk
4141
> For more usage guidelines, please refer
4242
> to: [Usage Documentation](https://github.com/TencentBlueKing/crypto-python-sdk/blob/main/docs/usage.md)
4343
44-
4544
#### 1. Basic Usage
4645

4746
**Asymmetric Encryption**
4847

49-
```python
50-
import os
51-
52-
from bkcrypto import constants
53-
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
54-
from bkcrypto.contrib.basic.ciphers import get_symmetric_cipher
55-
56-
symmetric_cipher: BaseSymmetricCipher = get_symmetric_cipher(
57-
cipher_type=constants.SymmetricCipherType.SM4.value,
58-
common={"key": os.urandom(16)},
59-
)
60-
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
61-
```
62-
63-
**Symmetric Encryption**
64-
6548
````python
6649
from bkcrypto import constants
6750
from bkcrypto.asymmetric import options
@@ -87,6 +70,22 @@ assert "123" == asymmetric_cipher.decrypt(asymmetric_cipher.encrypt("123"))
8770
assert asymmetric_cipher.verify(plaintext="123", signature=asymmetric_cipher.sign("123"))
8871
````
8972

73+
**Symmetric Encryption**
74+
75+
```python
76+
import os
77+
78+
from bkcrypto import constants
79+
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
80+
from bkcrypto.contrib.basic.ciphers import get_symmetric_cipher
81+
82+
symmetric_cipher: BaseSymmetricCipher = get_symmetric_cipher(
83+
cipher_type=constants.SymmetricCipherType.SM4.value,
84+
common={"key": os.urandom(16)},
85+
)
86+
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
87+
```
88+
9089
#### 2. Using with Django
9190

9291
Configure the encryption algorithm type in Django Settings
@@ -126,7 +125,94 @@ symmetric_cipher: BaseSymmetricCipher = get_symmetric_cipher()
126125
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
127126
```
128127

128+
#### 3. Using Django CipherManager
129+
130+
Configure the encryption algorithm type in Django Settings
131+
132+
```python
133+
from bkcrypto import constants
134+
from bkcrypto.symmetric.options import AESSymmetricOptions, SM4SymmetricOptions
135+
from bkcrypto.asymmetric.options import RSAAsymmetricOptions
136+
137+
BKCRYPTO = {
138+
# Declare the asymmetric encryption algorithm used by the project
139+
"ASYMMETRIC_CIPHER_TYPE": constants.AsymmetricCipherType.SM2.value,
140+
# Declare the symmetric encryption algorithm used by the project
141+
"SYMMETRIC_CIPHER_TYPE": constants.SymmetricCipherType.SM4.value,
142+
"SYMMETRIC_CIPHERS": {
143+
# default - The configured symmetric encryption instance can be configured with multiple instances depending on the project requirements
144+
"default": {
145+
# Optional, used in cases where settings cannot directly obtain the key
146+
# "get_key_config": "apps.utils.encrypt.key.get_key_config",
147+
# Optional, used for ModelField, encrypted with this prefix to store the database, decrypting and analyzing the prefix and selecting the appropriate decryption algorithm
148+
# ⚠️ The prefix and cipher type must be in one-to-one correspondence, and there can be no prefix matching relationship
149+
# "db_prefix_map": {
150+
# SymmetricCipherType.AES.value: "aes_str:::",
151+
# SymmetricCipherType.SM4.value: "sm4_str:::"
152+
# },
153+
# Common parameter configuration, sharing these parameters when initializing different ciphers
154+
"common": {"key": "your key"},
155+
"cipher_options": {
156+
constants.SymmetricCipherType.AES.value: AESSymmetricOptions(key_size=16),
157+
# Blue Whale recommended configuration
158+
constants.SymmetricCipherType.SM4.value: SM4SymmetricOptions(mode=constants.SymmetricMode.CTR)
159+
}
160+
},
161+
},
162+
"ASYMMETRIC_CIPHERS": {
163+
# Configuration same as SYMMETRIC_CIPHERS
164+
"default": {
165+
"common": {"public_key_string": "your key"},
166+
"cipher_options": {
167+
constants.AsymmetricCipherType.RSA.value: RSAAsymmetricOptions(
168+
padding=constants.RSACipherPadding.PKCS1_OAEP
169+
),
170+
constants.AsymmetricCipherType.SM2.value: SM4SymmetricOptions()
171+
},
172+
},
173+
}
174+
}
175+
```
176+
177+
**Asymmetric Encryption**
178+
179+
Use `asymmetric_cipher_manager` to get the `cipher` configured for `BKCRYPTO.ASYMMETRIC_CIPHERS`
180+
181+
```python
182+
from bkcrypto.asymmetric.ciphers import BaseAsymmetricCipher
183+
from bkcrypto.contrib.django.ciphers import asymmetric_cipher_manager
184+
185+
asymmetric_cipher: BaseAsymmetricCipher = asymmetric_cipher_manager.cipher(using="default")
186+
187+
# Encrypt and Decrypt
188+
assert "123" == asymmetric_cipher.decrypt(asymmetric_cipher.encrypt("123"))
189+
# Signature verification
190+
assert asymmetric_cipher.verify(plaintext="123", signature=asymmetric_cipher.sign("123"))
191+
```
192+
193+
**Symmetric Encryption**
194+
195+
Use `symmetric_cipher_manager` to get the `cipher` configured for `BKCRYPTO.SYMMETRIC_CIPHERS`
196+
197+
```python
198+
from bkcrypto.symmetric.ciphers import BaseSymmetricCipher
199+
from bkcrypto.contrib.django.ciphers import symmetric_cipher_manager
200+
201+
# using - Specifies a symmetric encryption instance, defaults to 'default'
202+
symmetric_cipher: BaseSymmetricCipher = symmetric_cipher_manager.cipher(using="default")
203+
assert "123" == symmetric_cipher.decrypt(symmetric_cipher.encrypt("123"))
204+
```
205+
206+
**Django ModelField**
129207

208+
```python
209+
from django.db import models
210+
from bkcrypto.contrib.django.fields import SymmetricTextField
211+
212+
213+
class IdentityData(models.Model):
214+
password = SymmetricTextField("Password", blank=True, null=True)
215+
```
130216

131217
## Roadmap
132218

0 commit comments

Comments
 (0)