2 This file is part of GNUnet
3 Copyright (C) 2010-2015 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @file reclaim/oidc_helper.c
23 * @brief helper library for OIDC related functions
24 * @author Martin Schanzenbach
29 #include "gnunet_util_lib.h"
30 #include "gnunet_reclaim_attribute_lib.h"
31 #include "gnunet_reclaim_service.h"
32 #include "gnunet_signatures.h"
33 #include "oidc_helper.h"
34 // #include "benchmark.h"
37 GNUNET_NETWORK_STRUCT_BEGIN
40 * The signature used to generate the authorization code
42 struct OIDC_Parameters
47 struct GNUNET_RECLAIM_Ticket ticket;
52 uint32_t nonce GNUNET_PACKED;
55 * The length of the PKCE code_challenge
57 uint32_t code_challenge_len GNUNET_PACKED;
60 * The length of the attributes list
62 uint32_t attr_list_len GNUNET_PACKED;
65 * The length of the attestation list
67 uint32_t attest_list_len GNUNET_PACKED;
70 GNUNET_NETWORK_STRUCT_END
73 create_jwt_header (void)
78 root = json_object ();
79 json_object_set_new (root, JWT_ALG, json_string (JWT_ALG_VALUE));
80 json_object_set_new (root, JWT_TYP, json_string (JWT_TYP_VALUE));
82 json_str = json_dumps (root, JSON_INDENT (0) | JSON_COMPACT);
89 replace_char (char *str, char find, char replace)
91 char *current_pos = strchr (str, find);
95 *current_pos = replace;
96 current_pos = strchr (current_pos, find);
103 fix_base64 (char *str)
106 replace_char (str, '+', '-');
109 replace_char (str, '/', '_');
114 * Create a JWT from attributes
116 * @param aud_key the public of the audience
117 * @param sub_key the public key of the subject
118 * @param attrs the attribute list
119 * @param expiration_time the validity of the token
120 * @param secret_key the key used to sign the JWT
121 * @return a new base64-encoded JWT string.
124 OIDC_id_token_new (const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
125 const struct GNUNET_CRYPTO_EcdsaPublicKey *sub_key,
126 struct GNUNET_RECLAIM_AttributeList *attrs,
127 struct GNUNET_RECLAIM_AttestationList *attests,
128 const struct GNUNET_TIME_Relative *expiration_time,
130 const char *secret_key)
132 struct GNUNET_RECLAIM_AttributeListEntry *le;
133 struct GNUNET_RECLAIM_AttestationListEntry *ale;
134 struct GNUNET_HashCode signature;
135 struct GNUNET_TIME_Absolute exp_time;
136 struct GNUNET_TIME_Absolute time_now;
141 char *aggr_names_str;
142 char *aggr_sources_str;
143 char *aggr_sources_jwt_str;
148 char *signature_target;
149 char *signature_base64;
151 char *attest_val_str;
154 json_t *aggr_sources;
155 json_t *aggr_sources_jwt;
156 int num_attestations = 0;
157 for (le = attrs->list_head; NULL != le; le = le->next)
159 if (GNUNET_NO == GNUNET_RECLAIM_id_is_zero (&le->attribute->attestation))
163 // iat REQUIRED time now
164 time_now = GNUNET_TIME_absolute_get ();
165 // exp REQUIRED time expired from config
166 exp_time = GNUNET_TIME_absolute_add (time_now, *expiration_time);
167 // auth_time only if max_age
168 // nonce only if nonce
169 // OPTIONAL acr,amr,azp
171 GNUNET_STRINGS_data_to_string_alloc (sub_key,
173 GNUNET_CRYPTO_EcdsaPublicKey));
175 GNUNET_STRINGS_data_to_string_alloc (aud_key,
177 GNUNET_CRYPTO_EcdsaPublicKey));
178 header = create_jwt_header ();
179 body = json_object ();
180 aggr_names = json_object ();
181 aggr_sources = json_object ();
183 // iss REQUIRED case sensitive server uri with https
184 // The issuer is the local reclaim instance (e.g.
185 // https://reclaim.id/api/openid)
186 json_object_set_new (body, "iss", json_string (SERVER_ADDRESS));
187 // sub REQUIRED public key identity, not exceed 255 ASCII length
188 json_object_set_new (body, "sub", json_string (subject));
189 // aud REQUIRED public key client_id must be there
190 json_object_set_new (body, "aud", json_string (audience));
192 json_object_set_new (body,
194 json_integer (time_now.abs_value_us / (1000 * 1000)));
196 json_object_set_new (body,
198 json_integer (exp_time.abs_value_us / (1000 * 1000)));
200 json_object_set_new (body,
202 json_integer (time_now.abs_value_us / (1000 * 1000)));
205 json_object_set_new (body, "nonce", json_string (nonce));
206 attest_val_str = NULL;
207 aggr_names_str = NULL;
208 aggr_sources_str = NULL;
209 aggr_sources_jwt_str = NULL;
212 for (ale = attests->list_head; NULL != ale; ale = ale->next)
215 GNUNET_asprintf (&source_name,
218 aggr_sources_jwt = json_object ();
220 GNUNET_RECLAIM_attestation_value_to_string (ale->attestation->type,
221 ale->attestation->data,
222 ale->attestation->data_size);
223 json_object_set_new (aggr_sources_jwt, "JWT",
224 json_string (attest_val_str) );
225 aggr_sources_jwt_str = json_dumps (aggr_sources_jwt, JSON_INDENT (0)
227 json_object_set_new (aggr_sources, source_name,json_string (
228 aggr_sources_jwt_str));
232 for (le = attrs->list_head; NULL != le; le = le->next)
235 if (GNUNET_YES == GNUNET_RECLAIM_id_is_zero (&le->attribute->attestation))
239 GNUNET_RECLAIM_attribute_value_to_string (le->attribute->type,
241 le->attribute->data_size);
242 json_object_set_new (body, le->attribute->name,
243 json_string (attr_val_str));
244 GNUNET_free (attr_val_str);
248 // Check if attest is there
250 for (ale = attests->list_head; NULL != ale; ale = ale->next)
253 GNUNET_RECLAIM_id_is_equal (&ale->attestation->id,
254 &le->attribute->attestation))
258 GNUNET_assert (NULL != ale);
259 // Attestation is existing, hence take the respective source str
260 GNUNET_asprintf (&source_name,
263 json_object_set_new (aggr_names, le->attribute->data,
264 json_string (source_name));
268 if (NULL != attest_val_str)
269 GNUNET_free (attest_val_str);
270 if (NULL != source_name)
271 GNUNET_free (source_name);
274 aggr_names_str = json_dumps (aggr_names, JSON_INDENT (0) | JSON_COMPACT);
275 aggr_sources_str = json_dumps (aggr_sources, JSON_INDENT (0)
277 json_object_set_new (body, "_claim_names", json_string (aggr_names_str));
278 json_object_set_new (body, "_claim_sources", json_string (
282 json_decref (aggr_names);
283 json_decref (aggr_sources);
284 json_decref (aggr_sources_jwt);
286 body_str = json_dumps (body, JSON_INDENT (0) | JSON_COMPACT);
288 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,"ID-Token: %s\n", body_str);
290 GNUNET_STRINGS_base64url_encode (header, strlen (header), &header_base64);
291 fix_base64 (header_base64);
293 GNUNET_STRINGS_base64url_encode (body_str, strlen (body_str), &body_base64);
294 fix_base64 (body_base64);
296 GNUNET_free (subject);
297 GNUNET_free (audience);
300 * Creating the JWT signature. This might not be
301 * standards compliant, check.
303 GNUNET_asprintf (&signature_target, "%s.%s", header_base64, body_base64);
304 GNUNET_CRYPTO_hmac_raw (secret_key,
307 strlen (signature_target),
309 GNUNET_STRINGS_base64url_encode ((const char *) &signature,
310 sizeof(struct GNUNET_HashCode),
312 fix_base64 (signature_base64);
314 GNUNET_asprintf (&result,
320 GNUNET_free (signature_target);
321 GNUNET_free (header);
322 GNUNET_free (body_str);
323 if (NULL != aggr_sources_str)
324 GNUNET_free (aggr_sources_str);
325 if (NULL != aggr_names_str)
326 GNUNET_free (aggr_names_str);
327 if (NULL != aggr_sources_jwt_str)
328 GNUNET_free (aggr_sources_jwt_str);
329 GNUNET_free (signature_base64);
330 GNUNET_free (body_base64);
331 GNUNET_free (header_base64);
337 derive_aes_key (struct GNUNET_CRYPTO_SymmetricSessionKey *key,
338 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
339 struct GNUNET_HashCode *key_material)
341 static const char ctx_key[] = "reclaim-aes-ctx-key";
342 static const char ctx_iv[] = "reclaim-aes-ctx-iv";
344 GNUNET_CRYPTO_kdf (key,
345 sizeof(struct GNUNET_CRYPTO_SymmetricSessionKey),
349 sizeof(struct GNUNET_HashCode),
351 GNUNET_CRYPTO_kdf (iv,
353 struct GNUNET_CRYPTO_SymmetricInitializationVector),
357 sizeof(struct GNUNET_HashCode),
363 calculate_key_priv (struct GNUNET_CRYPTO_SymmetricSessionKey *key,
364 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
365 const struct GNUNET_CRYPTO_EcdsaPrivateKey *ecdsa_priv,
366 const struct GNUNET_CRYPTO_EcdhePublicKey *ecdh_pub)
368 struct GNUNET_HashCode key_material;
370 GNUNET_CRYPTO_ecdsa_ecdh (ecdsa_priv, ecdh_pub, &key_material);
371 derive_aes_key (key, iv, &key_material);
376 calculate_key_pub (struct GNUNET_CRYPTO_SymmetricSessionKey *key,
377 struct GNUNET_CRYPTO_SymmetricInitializationVector *iv,
378 const struct GNUNET_CRYPTO_EcdsaPublicKey *ecdsa_pub,
379 const struct GNUNET_CRYPTO_EcdhePrivateKey *ecdh_priv)
381 struct GNUNET_HashCode key_material;
383 GNUNET_CRYPTO_ecdh_ecdsa (ecdh_priv, ecdsa_pub, &key_material);
384 derive_aes_key (key, iv, &key_material);
389 decrypt_payload (const struct GNUNET_CRYPTO_EcdsaPrivateKey *ecdsa_priv,
390 const struct GNUNET_CRYPTO_EcdhePublicKey *ecdh_pub,
395 struct GNUNET_CRYPTO_SymmetricSessionKey key;
396 struct GNUNET_CRYPTO_SymmetricInitializationVector iv;
398 calculate_key_priv (&key, &iv, ecdsa_priv, ecdh_pub);
399 GNUNET_break (GNUNET_CRYPTO_symmetric_decrypt (ct, ct_len, &key, &iv, buf));
404 encrypt_payload (const struct GNUNET_CRYPTO_EcdsaPublicKey *ecdsa_pub,
405 const struct GNUNET_CRYPTO_EcdhePrivateKey *ecdh_priv,
410 struct GNUNET_CRYPTO_SymmetricSessionKey key;
411 struct GNUNET_CRYPTO_SymmetricInitializationVector iv;
413 calculate_key_pub (&key, &iv, ecdsa_pub, ecdh_priv);
415 GNUNET_CRYPTO_symmetric_encrypt (payload, payload_len, &key, &iv, buf));
420 * Builds an OIDC authorization code including
421 * a reclaim ticket and nonce
423 * @param issuer the issuer of the ticket, used to sign the ticket and nonce
424 * @param ticket the ticket to include in the code
425 * @param attrs list of attributes which are shared
426 * @param nonce the nonce to include in the code
427 * @param code_challenge PKCE code challenge
428 * @return a new authorization code (caller must free)
431 OIDC_build_authz_code (const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
432 const struct GNUNET_RECLAIM_Ticket *ticket,
433 struct GNUNET_RECLAIM_AttributeList *attrs,
434 struct GNUNET_RECLAIM_AttestationList *attests,
435 const char *nonce_str,
436 const char *code_challenge)
438 struct OIDC_Parameters params;
443 char *buf_ptr = NULL;
445 size_t code_payload_len;
446 size_t attr_list_len = 0;
447 size_t attests_list_len = 0;
448 size_t code_challenge_len = 0;
451 struct GNUNET_CRYPTO_EccSignaturePurpose *purpose;
452 struct GNUNET_CRYPTO_EcdhePrivateKey *ecdh_priv;
453 struct GNUNET_CRYPTO_EcdhePublicKey ecdh_pub;
457 memset (¶ms, 0, sizeof(params));
458 params.ticket = *ticket;
461 payload_len = sizeof(struct OIDC_Parameters);
462 if ((NULL != nonce_str) && (strcmp ("", nonce_str) != 0))
464 if ((1 != sscanf (nonce_str, "%u", &nonce)) || (nonce > UINT32_MAX))
467 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Invalid nonce %s\n", nonce_str);
470 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
471 "Got nonce: %u from %s\n",
475 nonce_tmp = htonl (nonce);
476 params.nonce = nonce_tmp;
477 // Assign code challenge
478 if (NULL != code_challenge)
479 code_challenge_len = strlen (code_challenge);
480 payload_len += code_challenge_len;
481 params.code_challenge_len = htonl (code_challenge_len);
486 attr_list_len = GNUNET_RECLAIM_attribute_list_serialize_get_size (attrs);
487 params.attr_list_len = htonl (attr_list_len);
488 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
489 "Length of serialized attributes: %lu\n",
491 // Get serialized attributes
492 payload_len += attr_list_len;
498 GNUNET_RECLAIM_attestation_list_serialize_get_size (attests);
499 params.attest_list_len = htonl (attests_list_len);
500 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
501 "Length of serialized attestations: %lu\n",
503 // Get serialized attributes
504 payload_len += attests_list_len;
507 // Get plaintext length
508 payload = GNUNET_malloc (payload_len);
509 memcpy (payload, ¶ms, sizeof(params));
510 tmp = payload + sizeof(params);
511 if (0 < code_challenge_len)
513 memcpy (tmp, code_challenge, code_challenge_len);
514 tmp += code_challenge_len;
516 if (0 < attr_list_len)
517 GNUNET_RECLAIM_attribute_list_serialize (attrs, tmp);
518 if (0 < attests_list_len)
519 GNUNET_RECLAIM_attestation_list_serialize (attests, tmp);
525 code_payload_len = sizeof(struct GNUNET_CRYPTO_EccSignaturePurpose)
526 + sizeof(struct GNUNET_CRYPTO_EcdhePublicKey)
527 + payload_len + sizeof(struct
528 GNUNET_CRYPTO_EcdsaSignature);
529 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
530 "Length of data to encode: %lu\n",
534 ecdh_priv = GNUNET_CRYPTO_ecdhe_key_create ();
535 GNUNET_CRYPTO_ecdhe_key_get_public (ecdh_priv, &ecdh_pub);
536 // Initialize code payload
537 code_payload = GNUNET_malloc (code_payload_len);
538 GNUNET_assert (NULL != code_payload);
539 purpose = (struct GNUNET_CRYPTO_EccSignaturePurpose *) code_payload;
540 purpose->size = htonl (sizeof(struct GNUNET_CRYPTO_EccSignaturePurpose)
541 + sizeof(ecdh_pub) + payload_len);
542 purpose->purpose = htonl (GNUNET_SIGNATURE_PURPOSE_RECLAIM_CODE_SIGN);
544 buf_ptr = (char *) &purpose[1];
545 memcpy (buf_ptr, &ecdh_pub, sizeof(ecdh_pub));
546 buf_ptr += sizeof(ecdh_pub);
547 // Encrypt plaintext and store
548 encrypt_payload (&ticket->audience, ecdh_priv, payload, payload_len, buf_ptr);
549 GNUNET_free (ecdh_priv);
550 GNUNET_free (payload);
551 buf_ptr += payload_len;
552 // Sign and store signature
554 GNUNET_CRYPTO_ecdsa_sign (issuer,
556 (struct GNUNET_CRYPTO_EcdsaSignature *)
560 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Unable to sign code\n");
561 GNUNET_free (code_payload);
564 GNUNET_STRINGS_base64url_encode (code_payload, code_payload_len, &code_str);
565 GNUNET_free (code_payload);
571 * Parse reclaim ticket and nonce from
572 * authorization code.
573 * This also verifies the signature in the code.
575 * @param audience the expected audience of the code
576 * @param code the string representation of the code
577 * @param code_verfier PKCE code verifier
578 * @param ticket where to store the ticket
579 * @param attrs the attributes in the code
580 * @param nonce where to store the nonce
581 * @return GNUNET_OK if successful, else GNUNET_SYSERR
584 OIDC_parse_authz_code (const struct GNUNET_CRYPTO_EcdsaPrivateKey *ecdsa_priv,
586 const char *code_verifier,
587 struct GNUNET_RECLAIM_Ticket *ticket,
588 struct GNUNET_RECLAIM_AttributeList **attrs,
589 struct GNUNET_RECLAIM_AttestationList **attests,
596 char *expected_code_challenge;
597 char *code_challenge;
598 char *code_verifier_hash;
599 struct GNUNET_CRYPTO_EccSignaturePurpose *purpose;
600 struct GNUNET_CRYPTO_EcdsaSignature *signature;
601 struct GNUNET_CRYPTO_EcdsaPublicKey ecdsa_pub;
602 struct GNUNET_CRYPTO_EcdhePublicKey *ecdh_pub;
603 uint32_t code_challenge_len;
604 uint32_t attrs_ser_len;
605 size_t plaintext_len;
606 size_t code_payload_len;
608 struct OIDC_Parameters *params;
610 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Trying to decode `%s'\n", code);
613 GNUNET_STRINGS_base64url_decode (code, strlen (code),
614 (void **) &code_payload);
615 if (code_payload_len < sizeof(struct GNUNET_CRYPTO_EccSignaturePurpose)
616 + sizeof(struct GNUNET_CRYPTO_EcdhePublicKey)
617 + sizeof(struct OIDC_Parameters)
618 + sizeof(struct GNUNET_CRYPTO_EcdsaSignature))
620 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Authorization code malformed\n");
621 GNUNET_free_non_null (code_payload);
622 return GNUNET_SYSERR;
625 purpose = (struct GNUNET_CRYPTO_EccSignaturePurpose *) code_payload;
626 plaintext_len = code_payload_len;
627 plaintext_len -= sizeof(struct GNUNET_CRYPTO_EccSignaturePurpose);
628 ptr = (char *) &purpose[1];
630 ecdh_pub = (struct GNUNET_CRYPTO_EcdhePublicKey *) ptr;
631 ptr += sizeof(struct GNUNET_CRYPTO_EcdhePublicKey);
632 plaintext_len -= sizeof(struct GNUNET_CRYPTO_EcdhePublicKey);
634 // Decrypt ciphertext
635 plaintext_len -= sizeof(struct GNUNET_CRYPTO_EcdsaSignature);
636 plaintext = GNUNET_malloc (plaintext_len);
637 decrypt_payload (ecdsa_priv, ecdh_pub, ptr, plaintext_len, plaintext);
639 ptr += plaintext_len;
640 signature = (struct GNUNET_CRYPTO_EcdsaSignature *) ptr;
641 params = (struct OIDC_Parameters *) plaintext;
643 // cmp code_challenge code_verifier
644 code_challenge_len = ntohl (params->code_challenge_len);
645 if (0 != code_challenge_len) /* Only check if this code requires a CV */
647 if (NULL == code_verifier)
649 GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
650 "Expected code verifier!\n");
651 GNUNET_free_non_null (code_payload);
652 return GNUNET_SYSERR;
654 code_verifier_hash = GNUNET_malloc (256 / 8);
655 // hash code verifier
656 gcry_md_hash_buffer (GCRY_MD_SHA256,
659 strlen (code_verifier));
660 // encode code verifier
661 GNUNET_STRINGS_base64url_encode (code_verifier_hash, 256 / 8, &expected_code_challenge);
662 code_challenge = (char *) ¶ms[1];
663 GNUNET_free (code_verifier_hash);
664 if ((strlen (expected_code_challenge) != code_challenge_len) ||
666 strncmp (expected_code_challenge, code_challenge, code_challenge_len)))
668 GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
669 "Invalid code verifier! Expected: %s, Got: %.*s\n",
670 expected_code_challenge,
673 GNUNET_free_non_null (code_payload);
674 GNUNET_free (expected_code_challenge);
675 return GNUNET_SYSERR;
677 GNUNET_free (expected_code_challenge);
680 memcpy (ticket, ¶ms->ticket, sizeof(params->ticket));
682 nonce = ntohl (params->nonce); // ntohl (*((uint32_t *) ptr));
683 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Got nonce: %u\n", nonce);
685 GNUNET_CRYPTO_ecdsa_key_get_public (ecdsa_priv, &ecdsa_pub);
686 if (0 != GNUNET_memcmp (&ecdsa_pub, &ticket->audience))
688 GNUNET_free (code_payload);
689 GNUNET_free (plaintext);
690 GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
691 "Audience in ticket does not match client!\n");
692 return GNUNET_SYSERR;
695 GNUNET_CRYPTO_ecdsa_verify (GNUNET_SIGNATURE_PURPOSE_RECLAIM_CODE_SIGN,
700 GNUNET_free (code_payload);
701 GNUNET_free (plaintext);
702 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Signature of AuthZ code invalid!\n");
703 return GNUNET_SYSERR;
706 attrs_ser = ((char *) ¶ms[1]) + code_challenge_len;
707 attrs_ser_len = ntohl (params->attr_list_len);
708 *attrs = GNUNET_RECLAIM_attribute_list_deserialize (attrs_ser, attrs_ser_len);
712 GNUNET_asprintf (nonce_str, "%u", nonce);
713 GNUNET_free (code_payload);
714 GNUNET_free (plaintext);
720 * Build a token response for a token request
721 * TODO: Maybe we should add the scope here?
723 * @param access_token the access token to include
724 * @param id_token the id_token to include
725 * @param expiration_time the expiration time of the token(s)
726 * @param token_response where to store the response
729 OIDC_build_token_response (const char *access_token,
730 const char *id_token,
731 const struct GNUNET_TIME_Relative *expiration_time,
732 char **token_response)
736 root_json = json_object ();
738 GNUNET_assert (NULL != access_token);
739 GNUNET_assert (NULL != id_token);
740 GNUNET_assert (NULL != expiration_time);
741 json_object_set_new (root_json, "access_token", json_string (access_token));
742 json_object_set_new (root_json, "token_type", json_string ("Bearer"));
743 json_object_set_new (root_json,
745 json_integer (expiration_time->rel_value_us
747 json_object_set_new (root_json, "id_token", json_string (id_token));
748 *token_response = json_dumps (root_json, JSON_INDENT (0) | JSON_COMPACT);
749 json_decref (root_json);
754 * Generate a new access token
757 OIDC_access_token_new ()
760 uint64_t random_number;
763 GNUNET_CRYPTO_random_u64 (GNUNET_CRYPTO_QUALITY_NONCE, UINT64_MAX);
764 GNUNET_STRINGS_base64_encode (&random_number,