NAME

a2id_coreform, a2id_fromstr, a2id_generalize, a2id_hassignature, a2id_dprint, a2id_tostr — library to work with A2IDs and A2ID Selectors

SYNOPSIS

#include <arpa2/a2id.h>

size_t
a2id_coreform(char *dst, size_t dstsz, const a2id *id);

int
a2id_fromstr(a2id *id, const char *in, size_t inlen, int isselector);

int
a2id_generalize(a2id *id);

int
a2id_hassignature(const a2id *id);

void
a2id_dprint(int d, const a2id *id);

size_t
a2id_tostr(char *dst, size_t dstsz, const a2id *id);

DESCRIPTION

The a2id_coreform() function writes the core form of a2id into dst. Up to dstsz - 1 characters of the id are copied. It is guaranteed that dst is terminated with a nul byte, unless dstsz is 0. Furthermore, if dstsz >= A2ID_MAXSZ, then every valid A2ID will always fit.

The a2id_fromstr() function parses the string in of length inlen and writes the result in the opaque object id. isselector is a boolean that indicates whether or not the input should be treated as a selector.

The a2id_generalize() function generalizes an A2ID structure by one step. Generalization is the process of removing segments and labels from the localpart and domain, in that order. Each function call represents one generalization. As long as there are segments in the localpart, one segment is removed from the localpart from right to left. As soon as the localpart can't be generalized any further, domain labels are removed from left to right, until no labels are left. id will be directly modified.

The a2id_hassignature() function determines whether or not id has a signature. Note that signatures must be validated by the caller.

The a2id_dprint() function prints the different parts of id to descriptor d.

The a2id_tostr() function writes the string representation of id into dst. Up to dstsz - 1 characters of the id are copied. It is guaranteed that dst is terminated with a nul byte, unless dstsz is 0. Furthermore, if dstsz >= A2ID_MAXSZ, then every valid A2ID will always fit.

RETURN VALUES

a2id_coreform() returns the length of the string that would have been output, as if the size were unlimited (not including the terminating nul byte). Thus, if the return value is >= dstsz, then dst was truncated.

a2id_fromstr() returns 0 if in could be parsed and is a valid A2ID. On error -1 is returned.

a2id_generalize() returns 1 if a component is removed from the localpart or the domain. Returns 0 if nothing was removed because id can not be further generalized.

a2id_hassignature() returns 1 if id has a signature or 0 if not.

a2id_tostr() returns the length of the string that would have been output, as if the size were unlimited (not including the terminating nul byte). Thus, if the return value is >= dstsz, then dst was truncated.

EXAMPLES

Load an A2ID into id and write out it's core form.

a2id id;
char buf[A2ID_MAXSZ];
const char id[] = "foo+opt1+opt2@example.com";

if (a2id_fromstr(&id, id, strlen(id), 0) == -1)
	err(1, "invalid A2ID");

coreform(buf, sizeof buf, &id);
printf("core form: %s\n", buf);

Write a nul terminated copy of the core form of id into a buffer buf that might not be large enough to hold the result.

a2id id;
char buf[100];

/* ensure id is set with a2id_fromstr */

if (coreform(buf, sizeof buf, &id) >= sizeof buf)
	err(1, "buf too small");

Dynamically allocate room for a nul terminated copy of the core form of id.

a2id id;
size_t len;
char *cp;

/* ensure id is set with a2id_fromstr */

len = coreform(NULL, 0, &id);
if ((cp = malloc(len + 1)) == NULL)
	err(1, "malloc");

coreform(cp, len + 1, &id);

Print information about an A2ID to stderr.

a2id id;

/* ensure id is set with a2id_fromstr */

a2id_dprint(STDERR_FILENO, &id);

STANDARDS

The ARPA2 ID is based on the Network Access Identifier as specified in RFC 4282.

AUTHORS

Tim Kuijsten

CAVEATS

The current grammar of an A2ID only supports a subset of US-ASCII, notably the set supported by isgraph(3). In the future UTF-8 should probably be supported, but special care needs to be taken for any Unicode characters that have the same visual representation. A good pointer to start with would be RFC 8265 and 7542 and the notes about normalization in these documents.