A high level Sequoia PGP based API for nim

Find a file

user 6ca99690e3 added cbindgen to the deps		2024-09-05 17:10:46 -04:00
docs	version bump	2024-06-29 19:26:27 +09:00
src	added cbindgen to the deps	2024-09-05 17:10:46 -04:00
.gitignore	updated gitignore	2024-06-27 03:49:04 +09:00
generate-docs.sh	added versioning control. Attemtping to solve distribution issues	2024-06-26 20:46:13 +09:00
LICENSE	added License (MIT)	2024-06-27 03:46:27 +09:00
nimPGP.nimble	version bump	2024-06-29 19:26:27 +09:00
README.md	fixed formatting issues	2024-06-29 07:24:13 +09:00
ReleaseNotes.md	version bump	2024-06-29 19:26:27 +09:00

README.md

NIMPGP

Read the docs here: https://publiccdn.albassort.com/nimPGP/releases/latest/docs/nimPGP.html

Self-Hosted git: https://gogs.albassort.com/albassort/nimPGP

Gitlab Git: https://gitlab.com/IAlbassort/nimPGP

What is nimPGP

nimPGP is a pgp utility which uses Sequoia PGP on the backend. It allows for simple and idiomatic ways to utilize pgp in your code. It supports both parsing and generation of the following asymmetric algorithms on the primary keys and the subkeys in infinite configurations

Cv25519
RSA2k, RSA3k, RSA4k
P256, P384, P521

It is notable that it does NOT support any other algorithm. The following are somewhat common but not parsable:

RSA1K, RSA8K, ECC (and more)

What nimPGP is not

nimPGP is NOT a Sequoia wrapper. It is not intended to replace the already existing Sequoia wrapper for Nim.

All of the code is implemented in Rust and has bindings for Nim. You will not be able to interact with the entire breadth and scope of Sequoia. This is okay for everyday use but is not fit for, say, security analysis. Things are abstracted.

Features

(main feature black dot, white dot is options / parameters)

Certificate creation
- User ids
- Expiration length
- Primary Key Encryption algorithms
Subkeys
- Individual Expiration times independent from the Primary Key
- Customizable keyflags for each key
- Individual Encryption algorithms independent from the Primary Key
Cert Encryption
- Supports atomic passwords for each key as well as one single password for the entire Certificate
Message Signing
Signature Verification
Encrypting a message for a given Public Key
Decrypting a message with a Private Key
- Supports multiple private keys (keyrings) and password keyrings
Revoking a subkey
Revoking a Primary Key
Getting the intended recipients (by keyid) of an encrypted message
Scaffolding a key to a Cert object which contains all of its information

This covers most usecases, but there is more that can be covered in the future.

Exception Hanndling

　The base exception is SequoiaException, you can use this to catch all errors from nimPGG.

The exceptions follow this inheritance pattern.

CertParsingException
- FailedToParseKeyPublicException
- FailedToParseKeyPrivateException
- FailedToParseKeyException
- CertIsInvalidException
MissMatchingKey
- ExpectedPrivateKeyGotPublicException
- IncorrectKeyFlagsException
PasswordException
- PasswordSetToAtomicButMissingEncryptedKeyidException
- IncorrectPasswordForSecretKeyException
- FoundEncryptedSecretButNoPasswordHandlerException
CertGenerationFailedException
- KeyCannotBeUsedForTransportAndSigningException
NimSideSequoiaException
- CertLacksPrivateKey
- MustBeLiveForMoreThan100SecondsException
CertMaybeRevokedException
CertRevokedException
FailedToWriteMessageException
NoKeyMeetsSelectionException
FailedToParseMessageException
PackedParserFailedToRecurseException
FailedToReadFromBufferException
FailedToRevokeSubkeyException
FailedToRevokePrimaryKeyException
FailedToEncryptKeyException
CertHasEncryptedKeyException

I've made all of the names very clear to what they are, even if they are long. This is to also help you understand which ones can come up in the functions you execute intuitively, in lieu of functioning helpers, as, on paper every function can raise any one of these.

For additional clarity, the docs specify what functions raise which exception.

Security Concerns

Any security issues affecting Sequoia affects you. These tools are not so different from the tools they provide that they are likely to pose a security risk.

Memory

(This diagram shows how memory is read and written.)

On the backend, memory ownership and management operates on the following core principles. These principles prevents memory leaks, and simplify operations:

Pointers provided in parameters are NOT mutable. All data returned to Nim must transfer directly in the return value.
Where possible, avoid manual allocation of arrays from Rust. For example, keyids are transferred in a ; separated string as they are hex values.
All non-gc managed pointers must be deallocated prior to return of the procedure, before the result is given to the user. Be it allocated by Rust, or allocated by Nim.
Manual allocation of data can only occur in Rust if the function does not return an error. All malloc calls must happen directly before return is called
After the Rust function returns, before an exception can be raised from its error_code, all manually managed Nim pointers must be deallocated. This means that because of rule 4, no data leak will occur.
Thus, no manually allocated pointers will be exposed to the end user (This diagram shows the order of operations to ensure memory safety.)

Usage

import nimPGP
import times
#   Sets the keyflags
#   Note that, Sequoia does not allow for the creation of keys which both do Transport Encryption and Signing
let signingKey = newSubkey({ForSigning})
let transportKey = newSubkey({ForTransport, ForStorageEncryption})
let certUnencrypted = newCert(@[signingKey, transportKey], validLength = initDuration(days=365))
#Creates a handler used to encrypt a Cert
let pwHandler = newPasswordHandler("password12345!")
let certEncrypted = encryptKeys(certUnencrypted, pwHandler)

Sounds useful! How do I install

Compile from source (recommended!):

#   This assumes this is an initial install
nimble install nimPGP 
#   Pay attention to the version installed, this assumes there is no prior versions
cd ~/.nimble/pkgs2/nimPGP*
#   Assuming you're on a debian derived-os
#   As of pre-release it runs: 
#   sudo apt install clang cargo llvm pkg-config nettle-dev -y
./scripts/install-deps-apt.sh
#   compiles and links the .so to /usr/lib and the headers to /usr/include
./scripts/link.sh

Download precompiled (linux-x86 only!)

sudo apt install clang cargo llvm pkg-config nettle-dev -y
#   Uses my private servers
sudo curl https://publiccdn.albassort.com/nimPGP/releases/latest/libnimPGP.so > /usr/lib/libnimPGP.so
sudo curl https://publiccdn.albassort.com/nimPGP/releases/latest/nimPGP.h > /usr/lib/nimPGP.h
nimble install nimPGP

Versioning

Versions are split into 3 numbers separated by ., for example, 1.0.0.

The leftmost number represents the current feature-set, and increments when new functionality is added.

The middle number represents bug-fixes and patches on the libnimPGP side, or major bugfixes/changes on the Nim side, usually resulting in incompatibility with the previous libnimPGP version.

The rightmost increments when minor changes/bugfixes, or updates to documentation are added in Nim, but not in libnimPGP. This is for compatibility, and to help prevent needless manual dependency updating.

1.0.1 is compatible with 1.0.0

1.0.29 is compatible with 1.0.0 through 1.0.28, etc

1.1.0 is not compatible with 1.0.1

2.0.0 is not compatible with 1.1.0

Future

Currently, nothing is explicitly planned, save for expanding the API to cover more of Sequoia.

Perhaps, if demand exists, I will make repositories to fix the manual dependency issue.

Credits

All code and documentation, and charts by Caroline Marceano as of initial release

Code Review, Consulting, and Inspiration: Leorize (Check out their stuff: https://github.com/nim-works/nimskull)

Code Review: Luyten Orion (Chronos) (Check out their stuff: https://github.com/Luyten-Orion)

The beautiful people in the Sequoia IRC, who helped me when I needed it most.

Code Review by my personal friends and family.

My PGP-KEy

Use this to verify the signatures of pre-build binaries you download. The distribution folders have a file in it named signed-sum.asc, which contains a sha-512 of the binary provided. Verify its signature, to prevent MTM attacks.

We stand on the shoulders of giants

巨人の肩の上に立つ

Nani gigantum humeris

Thank you for reading.

README.md Unescape Escape