As a simple example of use of the CapyRandom I'll show in this article how to write a command line app to generate passwords and random data files.

(The complete code is available at the end of the article)

First, lets define a structure to hold all the needed data.

struct App { // Return code at the end of execution int ret; // Parser to process the command line arguments CapyArgParser parser; // Random generator CapyRandom generator; };

We'll need also an array of valid characters for a password, which I divide in two arrays to manage passwords with/without special characters.

char* pwdChar = "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789"; char* pwdSpecialChar = "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789" "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~";

Generating random data is as simple as creating the CapyRandom instance:

app.generator = CapyRandomCreate(time(NULL));

and getting the data in the required format, here a single byte:

uint8_t byte = $(&(app.generator), getUInt8)();

here an integer in a range of the appropriate size for the passwords:

char* setChar = pwdChar; if ($(&(app.parser), isSet)("-s")) setChar = pwdSpecialChar; uint8_t sizeSetChar = strlen(setChar) - 1; CapyRangeUInt8 range = CapyRangeUInt8Create(0, sizeSetChar); ... uint8_t chr = $(&(app.generator), getUInt8Range)(&range);

To select between password and data file, we'll use the command line parser provided by LibCapy. The argument definition looks as follow:

CapyArg args[] = { {.lbl=argv[0], .nbVal=capyArg_noVal, .help="Generate random data and passwords."}, {.shortLbl="-p", .lbl="--password", .nbVal=1, .help="Print on stdout a password of the length in character " "given in argument"}, {.shortLbl="-s", .lbl="--special", .nbVal=0, .help="Enable special characters in the password"}, {.shortLbl="-d", .lbl="--data", .nbVal=1, .help="Print on stdout as many random bytes as the number given " "in argument"}, };

and the actual parsing is done with:

app.parser = CapyArgParserAlloc(argc, argv, args);

Of course we'll want to check the arguments passed by the user, and to process any problem cleanly, we'll use some purpose made exceptions:

enum AppExceptions { excInvalidMode = CapyExc_LastID, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "Invalid mode, you must choose --password or --data", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's explanation if (exc >= excInvalidMode && exc < lastAppException) return exceptionStr[exc - excInvalidMode]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; }

The ExcToStr conversion function is set with:

CapyAddExcToStrFun(ExcToStr);

and the arguments checking looks like this:

if ($(&(app.parser), isSet)("-d") == true && $(&(app.parser), isSet)("-p") == true) raiseExc(excInvalidMode); if ($(&(app.parser), isSet)("-d") == false && $(&(app.parser), isSet)("-p") == false) raiseExc(excInvalidMode);

After the arguments have been checked, we can use them as follow:

if ($(&(app.parser), isSet)("-d")) { // Get the number of bytes to generates int64_t nbByte = $(&(app.parser), getAsInt)("-d", 0); // Generate the bytes and print them on stdout loop (iByte, nbByte) { uint8_t byte = ... printf("%c", byte); } } else if ($(&(app.parser), isSet)("-p")) { // Get the number of character to generates int64_t nbChar = $(&(app.parser), getAsInt)("-p", 0); ... // Generate the characters and print them on stdout loop (iByte, nbChar) { uint8_t chr = ... printf("%c", setChar[chr]); } printf("\n"); }

I skip intentionally releasing memory. This is done automatically at the end of the program, which is so small and simple that there is nothing to fear here. Everything put together, it becomes:

/* Capybarand - A password and random data file generator Copyright (C) 2021 Pascal Baillehache baillehache.pascal@gmail.com https://baillehachepascal.dev This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. */ #include <LibCapy/capy.h> // Valid characters for the password generation char* pwdChar = "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789"; char* pwdSpecialChar = "abcdefghijklmnopqrstuvwxyz" "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "0123456789" "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"; // App exceptions enum AppExceptions { excInvalidMode = CapyExc_LastID, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "Invalid mode, you must choose --password or --data", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's explanation if (exc >= excInvalidMode && exc < lastAppException) return exceptionStr[exc - excInvalidMode]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; } // Structure to memorise the appli variables struct App { // Return code at the end of execution int ret; // Parser to process the command line arguments CapyArgParser parser; // Random generator CapyRandom generator; }; // Main function int main( int argc, char** argv) { // Set the conversion function for raised exceptions CapyAddExcToStrFun(ExcToStr); // Instance of the application struct App app; // Initialise the application app.ret = EXIT_SUCCESS; app.generator = CapyRandomCreate(time(NULL)); try { // Definition of the arguments from the command line CapyArg args[] = { {.lbl=argv[0], .nbVal=capyArg_noVal, .help="Generate random data and passwords."}, {.shortLbl="-p", .lbl="--password", .nbVal=1, .help="Print on stdout a password of the length in character " "given in argument"}, {.shortLbl="-s", .lbl="--special", .nbVal=0, .help="Enable special characters in the password"}, {.shortLbl="-d", .lbl="--data", .nbVal=1, .help="Print on stdout as many random bytes as the number given " "in argument"}, }; // Create the argument parser and parse the arguments app.parser = CapyArgParserCreate(argc, argv, args); // Check the arguments if ($(&(app.parser), isSet)("-d") == true && $(&(app.parser), isSet)("-p") == true) raiseExc(excInvalidMode); if ($(&(app.parser), isSet)("-d") == false && $(&(app.parser), isSet)("-p") == false) raiseExc(excInvalidMode); // Generate data or password according to the command line arguments if ($(&(app.parser), isSet)("-d")) { // Get the number of bytes to generates int64_t nbByte = $(&(app.parser), getAsInt)("-d", 0); // Generate the bytes and print them on stdout loop (iByte, nbByte) { uint8_t byte = $(&(app.generator), getUInt8)(); printf("%c", byte); } } else if ($(&(app.parser), isSet)("-p")) { // Get the number of character to generates int64_t nbChar = $(&(app.parser), getAsInt)("-p", 0); // Get the used set of character according to the command line // argument char* setChar = pwdChar; if ($(&(app.parser), isSet)("-s")) setChar = pwdSpecialChar; uint8_t sizeSetChar = strlen(setChar) - 1; CapyRangeUInt8 range = CapyRangeUInt8Create(0, sizeSetChar); // Generate the characters and print them on stdout loop (iByte, nbChar) { uint8_t chr = $(&(app.generator), getUInt8Range)(&range); printf("%c", setChar[chr]); } printf("\n"); } } catchDefault { // Inform the user about the raised exception $(&capyDecoratorRed, fprintf)( stdout, "Sorry, an exception occured. Exiting.\n"); $(&capyDecoratorRed, fprintf)( stdout, "%s\n", CapyExcToStr(CapyGetLastExcId())); app.ret = EXIT_FAILURE; } endCatch; return app.ret; }

Compile with the following Makefile:

CAPY_PARAM=-std=c18 -I./ -Wall -Wextra -Wshadow -Wno-format-truncation -Werror -Wfatal-errors -O3 -ggdb -fopenmp -DPNG_SKIP_SETJMP_CHECK `pkg-config --cflags gtk+-3.0` -D_XOPEN_SOURCE=700 -DCAPY_WITH_GUI=1 CAPY_LINK=-lcapy -lm -fopenmp -lpng `pkg-config --libs gtk+-3.0` capybarand: main.o Makefile gcc -o capybarand main.o $(CAPY_LINK) main.o: main.c Makefile gcc $(CAPY_PARAM) -c main.c

Example of use:

> capybarand --password 10 tQXsEozU2I > capybarand --password 10 --special MmEz8&>wTD > capybarand --data 100 > random.data