diff options
Diffstat (limited to 'src/include/gnunet_identity_service.h')
-rw-r--r-- | src/include/gnunet_identity_service.h | 422 |
1 files changed, 417 insertions, 5 deletions
diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h index 94127248e..2974568db 100644 --- a/src/include/gnunet_identity_service.h +++ b/src/include/gnunet_identity_service.h | |||
@@ -57,6 +57,21 @@ extern "C" { | |||
57 | */ | 57 | */ |
58 | #define GNUNET_IDENTITY_VERSION 0x00000100 | 58 | #define GNUNET_IDENTITY_VERSION 0x00000100 |
59 | 59 | ||
60 | enum GNUNET_IDENTITY_KeyType | ||
61 | { | ||
62 | /** | ||
63 | * The identity type. The value is the same as the | ||
64 | * PKEY record type. | ||
65 | */ | ||
66 | GNUNET_IDENTITY_TYPE_ECDSA = 65536, | ||
67 | |||
68 | /** | ||
69 | * EDDSA identity. The value is the same as the EDKEY | ||
70 | * record type. | ||
71 | */ | ||
72 | GNUNET_IDENTITY_TYPE_EDDSA = 65556 | ||
73 | }; | ||
74 | |||
60 | /** | 75 | /** |
61 | * Handle to access the identity service. | 76 | * Handle to access the identity service. |
62 | */ | 77 | */ |
@@ -67,6 +82,88 @@ struct GNUNET_IDENTITY_Handle; | |||
67 | */ | 82 | */ |
68 | struct GNUNET_IDENTITY_Ego; | 83 | struct GNUNET_IDENTITY_Ego; |
69 | 84 | ||
85 | |||
86 | /** | ||
87 | * A private key for an identity as per LSD0001. | ||
88 | */ | ||
89 | struct GNUNET_IDENTITY_PrivateKey | ||
90 | { | ||
91 | /** | ||
92 | * Type of public key. | ||
93 | * Defined by the GNS zone type value. | ||
94 | * In NBO. | ||
95 | */ | ||
96 | uint32_t type; | ||
97 | |||
98 | union | ||
99 | { | ||
100 | /** | ||
101 | * An ECDSA identity key. | ||
102 | */ | ||
103 | struct GNUNET_CRYPTO_EcdsaPrivateKey ecdsa_key; | ||
104 | |||
105 | /** | ||
106 | * AN EdDSA identtiy key | ||
107 | */ | ||
108 | struct GNUNET_CRYPTO_EddsaPrivateKey eddsa_key; | ||
109 | }; | ||
110 | }; | ||
111 | |||
112 | |||
113 | /** | ||
114 | * An identity key as per LSD0001. | ||
115 | */ | ||
116 | struct GNUNET_IDENTITY_PublicKey | ||
117 | { | ||
118 | /** | ||
119 | * Type of public key. | ||
120 | * Defined by the GNS zone type value. | ||
121 | * In NBO. | ||
122 | */ | ||
123 | uint32_t type; | ||
124 | |||
125 | union | ||
126 | { | ||
127 | /** | ||
128 | * An ECDSA identity key. | ||
129 | */ | ||
130 | struct GNUNET_CRYPTO_EcdsaPublicKey ecdsa_key; | ||
131 | |||
132 | /** | ||
133 | * AN EdDSA identtiy key | ||
134 | */ | ||
135 | struct GNUNET_CRYPTO_EddsaPublicKey eddsa_key; | ||
136 | }; | ||
137 | }; | ||
138 | |||
139 | |||
140 | /** | ||
141 | * An identity signature as per LSD0001. | ||
142 | */ | ||
143 | struct GNUNET_IDENTITY_Signature | ||
144 | { | ||
145 | /** | ||
146 | * Type of signature. | ||
147 | * Defined by the GNS zone type value. | ||
148 | * In NBO. | ||
149 | */ | ||
150 | uint32_t type; | ||
151 | |||
152 | union | ||
153 | { | ||
154 | /** | ||
155 | * An ECDSA signature | ||
156 | */ | ||
157 | struct GNUNET_CRYPTO_EcdsaSignature ecdsa_signature; | ||
158 | |||
159 | /** | ||
160 | * AN EdDSA signature | ||
161 | */ | ||
162 | struct GNUNET_CRYPTO_EddsaSignature eddsa_signature; | ||
163 | }; | ||
164 | }; | ||
165 | |||
166 | |||
70 | /** | 167 | /** |
71 | * Handle for an operation with the identity service. | 168 | * Handle for an operation with the identity service. |
72 | */ | 169 | */ |
@@ -79,7 +176,7 @@ struct GNUNET_IDENTITY_Operation; | |||
79 | * @param ego the ego | 176 | * @param ego the ego |
80 | * @return associated ECC key, valid as long as the ego is valid | 177 | * @return associated ECC key, valid as long as the ego is valid |
81 | */ | 178 | */ |
82 | const struct GNUNET_CRYPTO_EcdsaPrivateKey * | 179 | const struct GNUNET_IDENTITY_PrivateKey * |
83 | GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego); | 180 | GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego); |
84 | 181 | ||
85 | 182 | ||
@@ -100,7 +197,7 @@ GNUNET_IDENTITY_ego_get_anonymous (void); | |||
100 | */ | 197 | */ |
101 | void | 198 | void |
102 | GNUNET_IDENTITY_ego_get_public_key (struct GNUNET_IDENTITY_Ego *ego, | 199 | GNUNET_IDENTITY_ego_get_public_key (struct GNUNET_IDENTITY_Ego *ego, |
103 | struct GNUNET_CRYPTO_EcdsaPublicKey *pk); | 200 | struct GNUNET_IDENTITY_PublicKey *pk); |
104 | 201 | ||
105 | 202 | ||
106 | /** | 203 | /** |
@@ -224,7 +321,7 @@ GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h); | |||
224 | typedef void | 321 | typedef void |
225 | (*GNUNET_IDENTITY_CreateContinuation) ( | 322 | (*GNUNET_IDENTITY_CreateContinuation) ( |
226 | void *cls, | 323 | void *cls, |
227 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *pk, | 324 | const struct GNUNET_IDENTITY_PrivateKey *pk, |
228 | const char *emsg); | 325 | const char *emsg); |
229 | 326 | ||
230 | 327 | ||
@@ -234,6 +331,7 @@ typedef void | |||
234 | * @param id identity service to use | 331 | * @param id identity service to use |
235 | * @param name desired name | 332 | * @param name desired name |
236 | * @param privkey desired private key or NULL to create one | 333 | * @param privkey desired private key or NULL to create one |
334 | * @param ktype the type of key to create. Ignored if privkey != NULL. | ||
237 | * @param cont function to call with the result (will only be called once) | 335 | * @param cont function to call with the result (will only be called once) |
238 | * @param cont_cls closure for @a cont | 336 | * @param cont_cls closure for @a cont |
239 | * @return handle to abort the operation | 337 | * @return handle to abort the operation |
@@ -241,7 +339,8 @@ typedef void | |||
241 | struct GNUNET_IDENTITY_Operation * | 339 | struct GNUNET_IDENTITY_Operation * |
242 | GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id, | 340 | GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id, |
243 | const char *name, | 341 | const char *name, |
244 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *privkey, | 342 | const struct GNUNET_IDENTITY_PrivateKey *privkey, |
343 | enum GNUNET_IDENTITY_KeyType ktype, | ||
245 | GNUNET_IDENTITY_CreateContinuation cont, | 344 | GNUNET_IDENTITY_CreateContinuation cont, |
246 | void *cont_cls); | 345 | void *cont_cls); |
247 | 346 | ||
@@ -292,6 +391,319 @@ void | |||
292 | GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op); | 391 | GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op); |
293 | 392 | ||
294 | 393 | ||
394 | /** | ||
395 | * Get the compacted length of a #GNUNET_IDENTITY_PublicKey. | ||
396 | * Compacted means that it returns the minimum number of bytes this | ||
397 | * key is long, as opposed to the union structure inside | ||
398 | * #GNUNET_IDENTITY_PublicKey. | ||
399 | * Useful for compact serializations. | ||
400 | * | ||
401 | * @param key the key. | ||
402 | * @return -1 on error, else the compacted length of the key. | ||
403 | */ | ||
404 | ssize_t | ||
405 | GNUNET_IDENTITY_key_get_length (const struct GNUNET_IDENTITY_PublicKey *key); | ||
406 | |||
407 | |||
408 | /** | ||
409 | * Reads a #GNUNET_IDENTITY_PublicKey from a compact buffer. | ||
410 | * The buffer has to contain at least the compacted length of | ||
411 | * a #GNUNET_IDENTITY_PublicKey in bytes. | ||
412 | * If the buffer is too small, the function returns -1 as error. | ||
413 | * If the buffer does not contain a valid key, it returns -2 as error. | ||
414 | * | ||
415 | * @param key the key | ||
416 | * @param buffer the buffer | ||
417 | * @param len the length of buffer | ||
418 | * @return -1 or -2 on error, else the amount of bytes read from the buffer | ||
419 | */ | ||
420 | ssize_t | ||
421 | GNUNET_IDENTITY_read_key_from_buffer (struct GNUNET_IDENTITY_PublicKey *key, | ||
422 | const void*buffer, | ||
423 | size_t len); | ||
424 | |||
425 | |||
426 | /** | ||
427 | * Writes a #GNUNET_IDENTITY_PublicKey to a compact buffer. | ||
428 | * The buffer requires space for at least the compacted length of | ||
429 | * a #GNUNET_IDENTITY_PublicKey in bytes. | ||
430 | * If the buffer is too small, the function returns -1 as error. | ||
431 | * If the key is not valid, it returns -2 as error. | ||
432 | * | ||
433 | * @param key the key | ||
434 | * @param buffer the buffer | ||
435 | * @param len the length of buffer | ||
436 | * @return -1 or -2 on error, else the amount of bytes written to the buffer | ||
437 | */ | ||
438 | ssize_t | ||
439 | GNUNET_IDENTITY_write_key_to_buffer (const struct | ||
440 | GNUNET_IDENTITY_PublicKey *key, | ||
441 | void*buffer, | ||
442 | size_t len); | ||
443 | |||
444 | |||
445 | /** | ||
446 | * Get the compacted length of a #GNUNET_IDENTITY_Signature. | ||
447 | * Compacted means that it returns the minimum number of bytes this | ||
448 | * signature is long, as opposed to the union structure inside | ||
449 | * #GNUNET_IDENTITY_Signature. | ||
450 | * Useful for compact serializations. | ||
451 | * | ||
452 | * @param sig the signature. | ||
453 | * @return -1 on error, else the compacted length of the signature. | ||
454 | */ | ||
455 | ssize_t | ||
456 | GNUNET_IDENTITY_signature_get_length (const struct | ||
457 | GNUNET_IDENTITY_Signature *sig); | ||
458 | |||
459 | |||
460 | /** | ||
461 | * Reads a #GNUNET_IDENTITY_Signature from a compact buffer. | ||
462 | * The buffer has to contain at least the compacted length of | ||
463 | * a #GNUNET_IDENTITY_Signature in bytes. | ||
464 | * If the buffer is too small, the function returns -1 as error. | ||
465 | * If the buffer does not contain a valid key, it returns -2 as error. | ||
466 | * | ||
467 | * @param sig the signature | ||
468 | * @param buffer the buffer | ||
469 | * @param len the length of buffer | ||
470 | * @return -1 or -2 on error, else the amount of bytes read from the buffer | ||
471 | */ | ||
472 | ssize_t | ||
473 | GNUNET_IDENTITY_read_signature_from_buffer (struct | ||
474 | GNUNET_IDENTITY_Signature *sig, | ||
475 | const void*buffer, | ||
476 | size_t len); | ||
477 | |||
478 | |||
479 | /** | ||
480 | * Writes a #GNUNET_IDENTITY_Signature to a compact buffer. | ||
481 | * The buffer requires space for at least the compacted length of | ||
482 | * a #GNUNET_IDENTITY_Signature in bytes. | ||
483 | * If the buffer is too small, the function returns -1 as error. | ||
484 | * If the key is not valid, it returns -2 as error. | ||
485 | * | ||
486 | * @param sig the signature | ||
487 | * @param buffer the buffer | ||
488 | * @param len the length of buffer | ||
489 | * @return -1 or -2 on error, else the amount of bytes written to the buffer | ||
490 | */ | ||
491 | ssize_t | ||
492 | GNUNET_IDENTITY_write_signature_to_buffer (const struct | ||
493 | GNUNET_IDENTITY_Signature *sig, | ||
494 | void*buffer, | ||
495 | size_t len); | ||
496 | |||
497 | |||
498 | /** | ||
499 | * @brief Sign a given block. | ||
500 | * | ||
501 | * The @a purpose data is the beginning of the data of which the signature is | ||
502 | * to be created. The `size` field in @a purpose must correctly indicate the | ||
503 | * number of bytes of the data structure, including its header. If possible, | ||
504 | * use #GNUNET_IDENTITY_sign() instead of this function. | ||
505 | * | ||
506 | * @param priv private key to use for the signing | ||
507 | * @param purpose what to sign (size, purpose) | ||
508 | * @param[out] sig where to write the signature | ||
509 | * @return #GNUNET_SYSERR on error, #GNUNET_OK on success | ||
510 | */ | ||
511 | int | ||
512 | GNUNET_IDENTITY_sign_ (const struct | ||
513 | GNUNET_IDENTITY_PrivateKey *priv, | ||
514 | const struct | ||
515 | GNUNET_CRYPTO_EccSignaturePurpose *purpose, | ||
516 | struct GNUNET_IDENTITY_Signature *sig); | ||
517 | |||
518 | |||
519 | /** | ||
520 | * @brief Sign a given block with #GNUNET_IDENTITY_PrivateKey. | ||
521 | * | ||
522 | * The @a ps data must be a fixed-size struct for which the signature is to be | ||
523 | * created. The `size` field in @a ps->purpose must correctly indicate the | ||
524 | * number of bytes of the data structure, including its header. | ||
525 | * | ||
526 | * @param priv private key to use for the signing | ||
527 | * @param ps packed struct with what to sign, MUST begin with a purpose | ||
528 | * @param[out] sig where to write the signature | ||
529 | */ | ||
530 | #define GNUNET_IDENTITY_sign(priv,ps,sig) do { \ | ||
531 | /* check size is set correctly */ \ | ||
532 | GNUNET_assert (ntohl ((ps)->purpose.size) == sizeof (*(ps))); \ | ||
533 | /* check 'ps' begins with the purpose */ \ | ||
534 | GNUNET_static_assert (((void*) (ps)) == \ | ||
535 | ((void*) &(ps)->purpose)); \ | ||
536 | GNUNET_assert (GNUNET_OK == \ | ||
537 | GNUNET_IDENTITY_sign_ (priv, \ | ||
538 | &(ps)->purpose, \ | ||
539 | sig)); \ | ||
540 | } while (0) | ||
541 | |||
542 | |||
543 | /** | ||
544 | * @brief Verify a given signature. | ||
545 | * | ||
546 | * The @a validate data is the beginning of the data of which the signature | ||
547 | * is to be verified. The `size` field in @a validate must correctly indicate | ||
548 | * the number of bytes of the data structure, including its header. If @a | ||
549 | * purpose does not match the purpose given in @a validate (the latter must be | ||
550 | * in big endian), signature verification fails. If possible, | ||
551 | * use #GNUNET_IDENTITY_signature_verify() instead of this function (only if @a validate | ||
552 | * is not fixed-size, you must use this function directly). | ||
553 | * | ||
554 | * @param purpose what is the purpose that the signature should have? | ||
555 | * @param validate block to validate (size, purpose, data) | ||
556 | * @param sig signature that is being validated | ||
557 | * @param pub public key of the signer | ||
558 | * @returns #GNUNET_OK if ok, #GNUNET_SYSERR if invalid | ||
559 | */ | ||
560 | int | ||
561 | GNUNET_IDENTITY_signature_verify_ (uint32_t purpose, | ||
562 | const struct | ||
563 | GNUNET_CRYPTO_EccSignaturePurpose *validate, | ||
564 | const struct GNUNET_IDENTITY_Signature *sig, | ||
565 | const struct | ||
566 | GNUNET_IDENTITY_PublicKey *pub); | ||
567 | |||
568 | |||
569 | /** | ||
570 | * @brief Verify a given signature with #GNUNET_IDENTITY_PublicKey. | ||
571 | * | ||
572 | * The @a ps data must be a fixed-size struct for which the signature is to be | ||
573 | * created. The `size` field in @a ps->purpose must correctly indicate the | ||
574 | * number of bytes of the data structure, including its header. | ||
575 | * | ||
576 | * @param purp purpose of the signature, must match 'ps->purpose.purpose' | ||
577 | * (except in host byte order) | ||
578 | * @param ps packed struct with what to sign, MUST begin with a purpose | ||
579 | * @param sig where to read the signature from | ||
580 | * @param pub public key to use for the verifying | ||
581 | */ | ||
582 | #define GNUNET_IDENTITY_signature_verify(purp,ps,sig,pub) ({ \ | ||
583 | /* check size is set correctly */ \ | ||
584 | GNUNET_assert (ntohl ((ps)->purpose.size) == sizeof (*(ps))); \ | ||
585 | /* check 'ps' begins with the purpose */ \ | ||
586 | GNUNET_static_assert (((void*) (ps)) == \ | ||
587 | ((void*) &(ps)->purpose)); \ | ||
588 | GNUNET_IDENTITY_signature_verify_ (purp, \ | ||
589 | &(ps)->purpose, \ | ||
590 | sig, \ | ||
591 | pub); \ | ||
592 | }) | ||
593 | |||
594 | |||
595 | /** | ||
596 | * Encrypt a block with #GNUNET_IDENTITY_PublicKey and derives a | ||
597 | * #GNUNET_CRYPTO_EcdhePublicKey which is required for decryption | ||
598 | * using ecdh to derive a symmetric key. | ||
599 | * | ||
600 | * @param block the block to encrypt | ||
601 | * @param size the size of the @a block | ||
602 | * @param pub public key to use for ecdh | ||
603 | * @param ecc where to write the ecc public key | ||
604 | * @param result the output parameter in which to store the encrypted result | ||
605 | * can be the same or overlap with @c block | ||
606 | * @returns the size of the encrypted block, -1 for errors. | ||
607 | * Due to the use of CFB and therefore an effective stream cipher, | ||
608 | * this size should be the same as @c len. | ||
609 | */ | ||
610 | ssize_t | ||
611 | GNUNET_IDENTITY_encrypt (const void *block, | ||
612 | size_t size, | ||
613 | const struct GNUNET_IDENTITY_PublicKey *pub, | ||
614 | struct GNUNET_CRYPTO_EcdhePublicKey *ecc, | ||
615 | void *result); | ||
616 | |||
617 | |||
618 | /** | ||
619 | * Decrypt a given block with #GNUNET_IDENTITY_PrivateKey and a given | ||
620 | * #GNUNET_CRYPTO_EcdhePublicKey using ecdh to derive a symmetric key. | ||
621 | * | ||
622 | * @param block the data to decrypt, encoded as returned by encrypt | ||
623 | * @param size the size of the @a block to decrypt | ||
624 | * @param priv private key to use for ecdh | ||
625 | * @param ecc the ecc public key | ||
626 | * @param result address to store the result at | ||
627 | * can be the same or overlap with @c block | ||
628 | * @return -1 on failure, size of decrypted block on success. | ||
629 | * Due to the use of CFB and therefore an effective stream cipher, | ||
630 | * this size should be the same as @c size. | ||
631 | */ | ||
632 | ssize_t | ||
633 | GNUNET_IDENTITY_decrypt (const void *block, | ||
634 | size_t size, | ||
635 | const struct | ||
636 | GNUNET_IDENTITY_PrivateKey *priv, | ||
637 | const struct | ||
638 | GNUNET_CRYPTO_EcdhePublicKey *ecc, | ||
639 | void *result); | ||
640 | |||
641 | |||
642 | /** | ||
643 | * Creates a (Base32) string representation of the public key. | ||
644 | * The resulting string encodes a compacted representation of the key. | ||
645 | * See also #GNUNET_IDENTITY_key_get_length. | ||
646 | * | ||
647 | * @param key the key. | ||
648 | * @return the string representation of the key, or NULL on error. | ||
649 | */ | ||
650 | char * | ||
651 | GNUNET_IDENTITY_public_key_to_string (const struct | ||
652 | GNUNET_IDENTITY_PublicKey *key); | ||
653 | |||
654 | |||
655 | /** | ||
656 | * Creates a (Base32) string representation of the private key. | ||
657 | * The resulting string encodes a compacted representation of the key. | ||
658 | * See also #GNUNET_IDENTITY_key_get_length. | ||
659 | * | ||
660 | * @param key the key. | ||
661 | * @return the string representation of the key, or NULL on error. | ||
662 | */ | ||
663 | char * | ||
664 | GNUNET_IDENTITY_private_key_to_string (const struct | ||
665 | GNUNET_IDENTITY_PrivateKey *key); | ||
666 | |||
667 | |||
668 | /** | ||
669 | * Parses a (Base32) string representation of the public key. | ||
670 | * See also #GNUNET_IDENTITY_public_key_to_string. | ||
671 | * | ||
672 | * @param str the encoded key. | ||
673 | * @param key where to write the key. | ||
674 | * @return GNUNET_SYSERR on error. | ||
675 | */ | ||
676 | enum GNUNET_GenericReturnValue | ||
677 | GNUNET_IDENTITY_public_key_from_string (const char*str, | ||
678 | struct GNUNET_IDENTITY_PublicKey *key); | ||
679 | |||
680 | |||
681 | /** | ||
682 | * Parses a (Base32) string representation of the private key. | ||
683 | * See also #GNUNET_IDENTITY_private_key_to_string. | ||
684 | * | ||
685 | * @param str the encoded key. | ||
686 | * @param key where to write the key. | ||
687 | * @return GNUNET_SYSERR on error. | ||
688 | */ | ||
689 | enum GNUNET_GenericReturnValue | ||
690 | GNUNET_IDENTITY_private_key_from_string (const char*str, | ||
691 | struct GNUNET_IDENTITY_PrivateKey *key); | ||
692 | |||
693 | |||
694 | /** | ||
695 | * Retrieves the public key representation of a private key. | ||
696 | * | ||
697 | * @param privkey the private key. | ||
698 | * @param key the public key result. | ||
699 | * @return GNUNET_SYSERR on error. | ||
700 | */ | ||
701 | enum GNUNET_GenericReturnValue | ||
702 | GNUNET_IDENTITY_key_get_public (const struct | ||
703 | GNUNET_IDENTITY_PrivateKey *privkey, | ||
704 | struct GNUNET_IDENTITY_PublicKey *key); | ||
705 | |||
706 | |||
295 | /* ************* convenience API to lookup an ego ***************** */ | 707 | /* ************* convenience API to lookup an ego ***************** */ |
296 | 708 | ||
297 | /** | 709 | /** |
@@ -344,7 +756,7 @@ GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el); | |||
344 | typedef void | 756 | typedef void |
345 | (*GNUNET_IDENTITY_EgoSuffixCallback) ( | 757 | (*GNUNET_IDENTITY_EgoSuffixCallback) ( |
346 | void *cls, | 758 | void *cls, |
347 | const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv, | 759 | const struct GNUNET_IDENTITY_PrivateKey *priv, |
348 | const char *ego_name); | 760 | const char *ego_name); |
349 | 761 | ||
350 | 762 | ||