aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_identity_service.h
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-11-12 17:49:34 +0100
committerChristian Grothoff <christian@grothoff.org>2020-11-12 17:49:34 +0100
commit3522008dfd14f049a821dfba7ba89a27aa27d4aa (patch)
tree09cc48925133f736e48bb2be4f239fb7d6d01950 /src/include/gnunet_identity_service.h
parent23f8671e09a80bf722c3268e8d477b5ce5e3d76a (diff)
parente11d1e59e4ae5f7d89c33df3ae9ca8f1ece990cf (diff)
downloadgnunet-3522008dfd14f049a821dfba7ba89a27aa27d4aa.tar.gz
gnunet-3522008dfd14f049a821dfba7ba89a27aa27d4aa.zip
Merge branch 'master' of git+ssh://gnunet.org/gnunet
Diffstat (limited to 'src/include/gnunet_identity_service.h')
-rw-r--r--src/include/gnunet_identity_service.h264
1 files changed, 263 insertions, 1 deletions
diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h
index 17714fec4..2974568db 100644
--- a/src/include/gnunet_identity_service.h
+++ b/src/include/gnunet_identity_service.h
@@ -138,6 +138,33 @@ struct GNUNET_IDENTITY_PublicKey
138 138
139 139
140/** 140/**
141 * An identity signature as per LSD0001.
142 */
143struct 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
167/**
141 * Handle for an operation with the identity service. 168 * Handle for an operation with the identity service.
142 */ 169 */
143struct GNUNET_IDENTITY_Operation; 170struct GNUNET_IDENTITY_Operation;
@@ -379,6 +406,240 @@ GNUNET_IDENTITY_key_get_length (const struct GNUNET_IDENTITY_PublicKey *key);
379 406
380 407
381/** 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 */
420ssize_t
421GNUNET_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 */
438ssize_t
439GNUNET_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 */
455ssize_t
456GNUNET_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 */
472ssize_t
473GNUNET_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 */
491ssize_t
492GNUNET_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 */
511int
512GNUNET_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 */
560int
561GNUNET_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 */
610ssize_t
611GNUNET_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 */
632ssize_t
633GNUNET_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/**
382 * Creates a (Base32) string representation of the public key. 643 * Creates a (Base32) string representation of the public key.
383 * The resulting string encodes a compacted representation of the key. 644 * The resulting string encodes a compacted representation of the key.
384 * See also #GNUNET_IDENTITY_key_get_length. 645 * See also #GNUNET_IDENTITY_key_get_length.
@@ -438,7 +699,8 @@ GNUNET_IDENTITY_private_key_from_string (const char*str,
438 * @return GNUNET_SYSERR on error. 699 * @return GNUNET_SYSERR on error.
439 */ 700 */
440enum GNUNET_GenericReturnValue 701enum GNUNET_GenericReturnValue
441GNUNET_IDENTITY_key_get_public (const struct GNUNET_IDENTITY_PrivateKey *privkey, 702GNUNET_IDENTITY_key_get_public (const struct
703 GNUNET_IDENTITY_PrivateKey *privkey,
442 struct GNUNET_IDENTITY_PublicKey *key); 704 struct GNUNET_IDENTITY_PublicKey *key);
443 705
444 706