nqcard, nqcardvrfy
— make and check an identity card for a signing
key
libnoqtis, -lnoqtis
#include
<noqtis.h>
int
nqcard(nqsalg alg,
const uint8_t *sk, size_t sklen,
const uint8_t *pk, size_t pklen,
const char *name, const char
*orcid, const char *email, const
char *url, const char *affil,
int64_t created, char *out,
size_t cap, size_t *outlen);
int
nqcardvrfy(const char *card,
size_t n, const uint8_t *pk,
size_t pklen, nqcardf *f);
nqcard()
writes to out, of cap bytes, an
identity card (‘noqtis-idcard-1,
noqtis-capsule(5)’)
in canonical JSON: the public key pk of
alg with name and, when not
NULL, orcid,
email, url and
affil, made at created (seconds
since 1970-01-01T00:00:00Z) and signed by sk under the
context ‘noqtis-idcard-1’.
*outlen gets the card's size, also when
cap is too small. The signature is verified before the
card is written.
The fields, in bytes: name and
affil are 1 to 255 bytes of UTF-8 with no control
character (C0, DEL or C1) and no space at either end;
orcid is an ORCID iD,
‘0000-0002-1825-0097’, or its
‘https://orcid.org/’ address, whose
last character is its ISO 7064 MOD 11-2 check digit
(‘X for 10’),
a lower-case ‘x’ taken as
‘X’; the card holds the bare iD.
email is
‘local@domain.tld’, at most
NQCARDEMAIL (254) bytes; url
an ‘https://’ address with a host, at
most NQCARDURL (1024) bytes; neither has a space or
a control character. The arguments and fields are checked before the
algorithm, so a call refused for a field returns
NQEARG whatever alg is.
nqcardvrfy()
checks the n bytes at card (at
most NQCARDMAX, 256 KiB): it must be a
‘noqtis-idcard-1’ card in canonical
form, with exactly its members, fields within the limits above (the ORCID iD
bare, its check digit right), a post-quantum algorithm, a key and a
signature of that algorithm's sizes, and a signature that verifies under the
key it carries with the context
‘noqtis-idcard-1’. With
pk not NULL, the card's key
must also be pk, of pklen bytes.
On success *f gets the card:
typedef struct {
nqsalg alg;
uint8_t pk[NQCARDPK]; /* the card's public key, pklen bytes */
size_t pklen;
uint8_t fp[32]; /* its SHA-256 (nqinsp's info.key) */
int64_t created; /* seconds since 1970, UTC */
char utc[21]; /* the same, YYYY-MM-DDTHH:MM:SSZ */
char name[256];
char orcid[20]; /* "" for a field the card has not */
char email[NQCARDEMAIL + 1];
char url[NQCARDURL + 1];
char affil[256];
} nqcardf;
On any other result *f is zeroed. A card is self-signed: a card that verifies was written by whoever holds its key and is unchanged, which does not make the name true; compare fp with the one its holder published, or pin pk.
NQOKNQEBUF]NQENOSUP]nqcard(): the algorithm is not a post-quantum
signature (Ed25519 alone).NQEARG]NULL argument, a field out of its limits, keys
of the wrong sizes or not a pair, or created before
1970 or after 9999.NQEVRFY]nqcardvrfy(): the signature does not verify, or
the card is not for pk.NQEDEC]nqcardvrfy(): not a card as above.NQELIM]nqcardvrfy(): more than
NQCARDMAX bytes.NQEMEM]NULL.noqtis-check(1), noqtis-idcard(1), nqinsp(3), nqkstmt(3), noqtis-capsule(5)