.Dd March 6, 2024

.Nd signing key operations

.Op Fl -create | Fl -public | Fl -sign

.Op Fl t Ar type

.Ar keyfile

is used to create or extract signing keys for use with

One of the

.Fl -create ,

.Fl -public ,

or

.Fl -sign

operations must be specified.

Future work may write information about the

.Ar keyfile

out to

.Em stdout

when no key operation has been specified.

.Pp

See

.Xr pkg-repo

for some practical examples of using

.Nm .

.Ar keyfile

.Nm

will

.Xr chmod 2

the

.Ar keyfile

to

.Li 0400

upon successful completion.

The corresponding public key will be written to

.Em stdout ,

note the caveats of this described with the

.Fl -public

option.

The

.Fl t

option should be used when generating keys to be explicit about the type of

key requested.

.Pp

Note that the

.Sy ecdsa

and

.Sy eddsa

keys generated by

.Nm

are not compatible with those generated by OpenSSL, but

.Xr pkg 8

can read

.Sy ecdsa

keys generated by OpenSSL.

Write the public key corresponding to

.Ar keyfile

out to

.Em stdout .

Note that some signers may output keys in a binary format, so it is recommended

to redirect

.Em stdout

to a file.

.It Fl -sign

Signs the data ingested via

.Em stdin

with the named

.Ar keyfile ,

and writes the signature data to

.Em stdout .

As with

.Fl -public ,

note that the signature may be a binary format and it is recommended to redirect

.Em stdout

to a file.

.It Fl t Ar type

Specifies the

.Ar type

of signer to use for the given key.

.Nm

will not try to guess the correct signer that goes with a key in any case, so

it must be specified for every operation.

The

.Sy rsa

signer is assumed if

.Fl t

is not specified.

The following signers are currently supported:

.Bl -tag -width all

.It Sy rsa

Backend using RSA with keys created either by OpenSSL or by

.Nm

.Fl -create .

.It Sy ecc

An alias for the

.Sy eddsa

signer.

.It Sy ecdsa

Backend using ECDSA with keys created either by OpenSSL or by

.Nm

.Fl -create .

See

.Sx Elliptic Curve Cryptography

for more discussion.

.It Sy eddsa

Backend using EdDSA with keys created by

.Nm

.Fl -create .

See

.Sx Elliptic Curve Cryptography

for more discussion.

.El

.Ss Elliptic Curve Cryptography

Elliptic Curve Cryptography, ECC, is supported by

.Xr pkg 8 ,

with limited compatibility with OpenSSL.

Signatures are output in a format that OpenSSL can handle, subject to the

constraints about curve choice outlined in the rest of this section.

.Pp

The

.Sy ecdsa

signer is expected to be interoperable with OpenSSL, but curve choice is more

limited than what OpenSSL provides.

In general, the curves provided must be supported both by OpenSSL and by the

.Lb libecc

used by

.Xr pkg 8 .

The criteria for curve selection is that they must be 256-bit or higher and

accepted by both implementations.

The following common curves are currently supported:

.Bl -bullet

.It

.Sy secp256k1

.It

.Sy secp384r1

.It

.Sy secp521r1

.It

.Sy brainpoolP256r1

.It

.Sy brainpoolP256t1

.It

.Sy brainpoolP320r1

.It

.Sy brainpoolP320t1

.It

.Sy brainpoolP384r1

.It

.Sy brainpoolP384t1

.It

.Sy brainpoolP512r1

.It

.Sy brainpoolP512t1

.El

.Pp

The

.Sy eddsa

signer is not compatible with OpenSSL due to limited curve selection provided

by

.Lb libecc

by default.

The only curve supported by

.Xr pkg 8

for EdDSA is

.Sy WEI25519 .

.Ao Ar repo-path Ac Op Ar signer-type: Ns Ao Ar keyfile Ac | signing_command: Ao Ar the command Ac

.Ao Ar repo-path Ac Op Ar signer-type: Ns Ao Ar keyfile Ac | signing_command: Ao Ar the command Ac

This is enabled either by specifying the path to a private key as the

.Ar keyfile

When a

.Ar keyfile

is being used, it may be prefixed by the signer type.

Currently, this may be one of

.Sy rsa ,

.Sy ecdsa ,

or

.Sy eddsa .

.Sy ecc

is also accepted as an alias of

.Sy eddsa .

Keys for the

.Sy rsa

and

.Sy ecdsa

signers may be generated by OpenSSL or by

.Xr pkg-key 8 .

Keys for the

.Dq eddsa

signer may only be generated by

.Xr pkg-key 8 .

If the

.Ar key

is used, a hash of the repository is signed using the provided key.

The

.Sy rsa

signer will sign the SHA256 hash of the repository, while the

.Sy ecdsa

and

.Sy eddsa

signers will sign the BLAKE2 hash of the repository.

TYPE

signer type here (rsa, ecdsa, eddsa)

The

.Sy TYPE

field is optional if using

.Sy rsa ,

to remain compatible with external signing commands historically in use.

Note that the

.Sy SIGNATURE

field's data will may require an extra newline after it if the signature is

output in a binary format.

The

.Sy CERT

field may contain binary data, but

.Xr pkg 8

will search the tail of it for the missing

.Sy END

if it runs together.

.Pp

.Pp

The above examples can be repeated with OpenSSL creating a key pair for ECDSA:

.Bd -literal -offset indent

% openssl ecparam -genkey -name secp256k1 -out repo.key -outform DER

% chmod 0400 repo.key

% openssl ec -in repo.key -out repo.pub -pubout -outform DER

.Ed

.Pp

Prefixing the later

.Pa repo.key

reference with

.Dq ecdsa :

.Pp

.Dl pkg repo /usr/ports/packages ecdsa:repo.key

.Pp

The signing server example can be used mostly as-is, but with the following text

placed before the

.Sy SIGNATURE

section in the signing server output:

.Bd -literal -offset indent

TYPE

ecdsa

.Ed

.Pp

For EdDSA instead, create an EdDSA key pair:

.Bd -literal -offset indent

% pkg key --create -t eddsa repo.key > repo.pub

.Ed

.Pp

Create a repository and sign it with a local key.

As with the RSA example above, the public key would be shared on all client

servers with

.Sy SIGNATURE_TYPE

set to

.Dv PUBKEY

and its path set via the

.Sy PUBKEY

option in the repository configuration file:

.Pp

.Dl pkg repo /usr/ports/packages eddsa:repo.key

.Pp

A signing server for EdDSA could be constructed with the

.Xr pkg-key 8

.Fl -sign

option.