Skip to content

Commit 89effc6

Browse files
author
Ben Taylor
committed
Add improvements and corrections to the migration guide
Signed-off-by: Ben Taylor <[email protected]>
1 parent 9e98b72 commit 89effc6

File tree

1 file changed

+124
-105
lines changed

1 file changed

+124
-105
lines changed

‎docs/4.0-migration-guide/rng-removal.md

+124-105
Original file line numberDiff line numberDiff line change
@@ -8,186 +8,204 @@ The `f_rng` and `p_rng` arguments have been removed from the LMS, LMOTS, PK, X50
88

99
The following function calls have been changed in LMS:
1010

11-
`int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
12-
mbedtls_lms_algorithm_type_t type,
13-
mbedtls_lmots_algorithm_type_t otstype,
14-
int (*f_rng)(void *, unsigned char *, size_t),
15-
void *p_rng, const unsigned char *seed,
16-
size_t seed_size);`
17-
18-
`int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
11+
```c
12+
int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx, mbedtls_lms_algorithm_type_t type, mbedtls_lmots_algorithm_type_t otstype,
13+
int (*f_rng)(void *, unsigned char *, size_t),
14+
void *p_rng,
15+
const unsigned char *seed, size_t seed_size);`
16+
```
17+
18+
```c
19+
int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
1920
int (*f_rng)(void *, unsigned char *, size_t),
20-
void *p_rng, const unsigned char *msg,
21-
unsigned int msg_size, unsigned char *sig, size_t sig_size,
22-
size_t *sig_len);`
21+
void *p_rng,
22+
const unsigned char *msg, unsigned int msg_size, unsigned char *sig, size_t sig_size, size_t *sig_len);`
2323
2424
to
2525
26-
`int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
27-
mbedtls_lms_algorithm_type_t type,
28-
mbedtls_lmots_algorithm_type_t otstype,
29-
const unsigned char *seed,
30-
size_t seed_size);`
26+
```c
27+
int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx, mbedtls_lms_algorithm_type_t type, mbedtls_lmots_algorithm_type_t otstype,
28+
const unsigned char *seed, size_t seed_size);`
29+
```
3130

32-
`int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
33-
int (*f_rng)(void *, unsigned char *, size_t),
34-
const unsigned char *msg,
35-
unsigned int msg_size, unsigned char *sig, size_t sig_size,
36-
size_t *sig_len);`
31+
```c
32+
int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
33+
const unsigned char *msg, unsigned int msg_size, unsigned char *sig, size_t sig_size, size_t *sig_len);`
34+
```
3735
3836
3937
### Changes in x509
4038
4139
The following function calls have been changed in x509:
4240
43-
`int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
41+
```c
42+
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
4443
int (*f_rng)(void *, unsigned char *, size_t),
4544
void *p_rng);`
45+
```
4646

47-
`int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
47+
```c
48+
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
4849
int (*f_rng)(void *, unsigned char *, size_t),
4950
void *p_rng);`
51+
```
5052
51-
`int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
53+
```c
54+
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
5255
int (*f_rng)(void *, unsigned char *, size_t),
5356
void *p_rng);`
57+
```
5458

55-
`int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
59+
```c
60+
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
5661
int (*f_rng)(void *, unsigned char *, size_t),
5762
void *p_rng);`
63+
```
5864
5965
to
6066
61-
`int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);`
67+
```c
68+
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);`
69+
```
6270

63-
`int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);`
71+
```c
72+
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);`
73+
```
6474
65-
`int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);`
75+
```c
76+
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);`
77+
```
6678

67-
`int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);`
79+
```c
80+
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);`
81+
```
6882
6983
### Changes in PK
7084
7185
The following function calls have been changed in PK:
7286
73-
`int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
74-
mbedtls_md_type_t md_alg,
75-
const unsigned char *hash, size_t hash_len,
76-
unsigned char *sig, size_t sig_size, size_t *sig_len,
77-
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
87+
```c
88+
int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len,
89+
int (*f_rng)(void *, unsigned char *, size_t),
90+
void *p_rng,
7891
mbedtls_pk_restart_ctx *rs_ctx);`
92+
```
7993

80-
`int mbedtls_pk_check_pair(const mbedtls_pk_context *pub,
81-
const mbedtls_pk_context *prv,
94+
```c
95+
int mbedtls_pk_check_pair(const mbedtls_pk_context *pub, const mbedtls_pk_context *prv,
8296
int (*f_rng)(void *, unsigned char *, size_t),
8397
void *p_rng);`
98+
```
8499
85-
`int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,
86-
const unsigned char *input, size_t ilen,
87-
unsigned char *output, size_t *olen, size_t osize,
100+
```c
101+
int mbedtls_pk_decrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize,
88102
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);`
103+
```
89104

90-
`int mbedtls_pk_encrypt(mbedtls_pk_context *ctx,
91-
const unsigned char *input, size_t ilen,
92-
unsigned char *output, size_t *olen, size_t osize,
105+
```c
106+
int mbedtls_pk_encrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize,
93107
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);`
108+
```
94109
95-
`int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
96-
const unsigned char *hash, size_t hash_len,
97-
unsigned char *sig, size_t sig_size, size_t *sig_len,
110+
```c
111+
int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len,
98112
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);`
113+
```
99114

100-
`int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_type,
101-
mbedtls_pk_context *ctx,
102-
mbedtls_md_type_t md_alg,
103-
const unsigned char *hash, size_t hash_len,
104-
unsigned char *sig, size_t sig_size, size_t *sig_len,
115+
```c
116+
int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_type, mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len,
105117
int (*f_rng)(void *, unsigned char *, size_t),
106118
void *p_rng);`
119+
```
107120
108-
`int mbedtls_pk_parse_key(mbedtls_pk_context *ctx,
109-
const unsigned char *key, size_t keylen,
110-
const unsigned char *pwd, size_t pwdlen,
121+
```c
122+
int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen,
111123
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);`
124+
```
112125

113-
`int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx,
114-
const char *path, const char *password,
126+
```c
127+
int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password,
115128
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);`
129+
```
116130
117-
`typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx,
131+
```c
132+
typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx,
118133
int (*f_rng)(void *, unsigned char *, size_t),
119134
void *p_rng,
120-
mbedtls_md_type_t md_alg, unsigned int hashlen,
121-
const unsigned char *hash, unsigned char *sig);`
135+
mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig);`
136+
```
122137

123138
to
124139

125-
`int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
126-
mbedtls_md_type_t md_alg,
127-
const unsigned char *hash, size_t hash_len,
128-
unsigned char *sig, size_t sig_size, size_t *sig_len,
129-
mbedtls_pk_restart_ctx *rs_ctx);`
130-
131-
`int mbedtls_pk_check_pair(const mbedtls_pk_context *pub,
132-
const mbedtls_pk_context *prv);`
140+
```c
141+
int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len,
142+
mbedtls_pk_restart_ctx *rs_ctx);`
143+
```
133144
134-
`int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,
135-
const unsigned char *input, size_t ilen,
136-
unsigned char *output, size_t *olen, size_t osize);`
145+
```c
146+
int mbedtls_pk_check_pair(const mbedtls_pk_context *pub, const mbedtls_pk_context *prv);`
147+
```
137148

138-
`int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,
139-
const unsigned char *input, size_t ilen,
140-
unsigned char *output, size_t *olen, size_t osize);`
149+
```c
150+
int mbedtls_pk_decrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize);`
151+
```
141152
142-
`int mbedtls_pk_encrypt(mbedtls_pk_context *ctx,
143-
const unsigned char *input, size_t ilen,
144-
unsigned char *output, size_t *olen, size_t osize);'
153+
```c
154+
int mbedtls_pk_encrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize);'
155+
```
145156

146-
`int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
147-
const unsigned char *hash, size_t hash_len,
148-
unsigned char *sig, size_t sig_size, size_t *sig_len);`
157+
```c
158+
int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len);`
159+
```
149160
150-
`int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_type,
151-
mbedtls_pk_context *ctx,
152-
mbedtls_md_type_t md_alg,
153-
const unsigned char *hash, size_t hash_len,
154-
unsigned char *sig, size_t sig_size, size_t *sig_len);`
161+
```c
162+
int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_type, mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t sig_size, size_t *sig_len);`
163+
```
155164

156-
`int mbedtls_pk_parse_key(mbedtls_pk_context *ctx,
157-
const unsigned char *key, size_t keylen,
158-
const unsigned char *pwd, size_t pwdlen);`
165+
```c
166+
int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen);`
167+
```
159168
160-
`int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx,
161-
const char *path, const char *password);`
169+
```c
170+
int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password);`
171+
```
162172

163-
`typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx,
164-
mbedtls_md_type_t md_alg, unsigned int hashlen,
165-
const unsigned char *hash, unsigned char *sig);`
173+
```c
174+
typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx,
175+
mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig);`
176+
```
166177
167178
### Changes in SSL
168179
169180
The following function calls have been changed in SSL:
170181
171-
`int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
182+
```c
183+
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
172184
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
173-
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits,
174-
uint32_t lifetime);`
185+
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits, uint32_t lifetime);`
186+
```
175187

176-
`int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
188+
```c
189+
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
177190
int (*f_rng)(void *, unsigned char *, size_t),
178191
void *p_rng);`
192+
```
179193
180194
to
181195
182-
`int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
183-
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits,
184-
uint32_t lifetime);`
196+
```c
197+
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
198+
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits, uint32_t lifetime);`
199+
```
185200

186-
`int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx);`
201+
```c
202+
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx);`
203+
```
187204
188-
The follwing structs have also been changed in SSL
205+
The following structs have also been changed in SSL
189206
190-
`typedef struct mbedtls_ssl_ticket_context {
207+
```c
208+
typedef struct mbedtls_ssl_ticket_context {
191209
mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */
192210
unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */
193211
@@ -202,18 +220,18 @@ The follwing structs have also been changed in SSL
202220
#endif
203221
}
204222
mbedtls_ssl_ticket_context;`
223+
```
205224

206225

207226
to
208227

209-
`typedef struct mbedtls_ssl_ticket_context {
228+
```c
229+
typedef struct mbedtls_ssl_ticket_context {
210230
mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */
211231
unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */
212232

213233
uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< lifetime of tickets in seconds */
214234

215-
/** Callback for getting (pseudo-)random numbers */
216-
217235
#if defined(MBEDTLS_THREADING_C)
218236
mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex);
219237
#endif
@@ -222,4 +240,5 @@ mbedtls_ssl_ticket_context;`
222240

223241
### Removal of `mbedtls_ssl_conf_rng`
224242

225-
`mbedtls_ssl_conf_rng` has been removed from the library as it's sole purpose is to configure RNG for ssl and this is no longer required.
243+
`mbedtls_ssl_conf_rng` has been removed from the library as its sole purpose is to configure RNG for ssl and this is no longer required.
244+
```

0 commit comments

Comments
 (0)