Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 346 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/openssl-pkcs8.1ssl b/upstream/archlinux/man1/openssl-pkcs8.1ssl
new file mode 100644
index 00000000..4dcf8c5a
--- /dev/null
+++ b/upstream/archlinux/man1/openssl-pkcs8.1ssl
@@ -0,0 +1,346 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "OPENSSL-PKCS8 1ssl"
+.TH OPENSSL-PKCS8 1ssl 2024-01-30 3.2.1 OpenSSL
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+openssl\-pkcs8 \- PKCS#8 format private key conversion command
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+\&\fBopenssl\fR \fBpkcs8\fR
+[\fB\-help\fR]
+[\fB\-topk8\fR]
+[\fB\-inform\fR \fBDER\fR|\fBPEM\fR]
+[\fB\-outform\fR \fBDER\fR|\fBPEM\fR]
+[\fB\-in\fR \fIfilename\fR]
+[\fB\-passin\fR \fIarg\fR]
+[\fB\-out\fR \fIfilename\fR]
+[\fB\-passout\fR \fIarg\fR]
+[\fB\-iter\fR \fIcount\fR]
+[\fB\-noiter\fR]
+[\fB\-nocrypt\fR]
+[\fB\-traditional\fR]
+[\fB\-v2\fR \fIalg\fR]
+[\fB\-v2prf\fR \fIalg\fR]
+[\fB\-v1\fR \fIalg\fR]
+[\fB\-scrypt\fR]
+[\fB\-scrypt_N\fR \fIN\fR]
+[\fB\-scrypt_r\fR \fIr\fR]
+[\fB\-scrypt_p\fR \fIp\fR]
+[\fB\-saltlen\fR \fIsize\fR]
+[\fB\-rand\fR \fIfiles\fR]
+[\fB\-writerand\fR \fIfile\fR]
+[\fB\-engine\fR \fIid\fR]
+[\fB\-provider\fR \fIname\fR]
+[\fB\-provider\-path\fR \fIpath\fR]
+[\fB\-propquery\fR \fIpropq\fR]
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This command processes private keys in PKCS#8 format. It can handle
+both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
+format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
+.SH OPTIONS
+.IX Header "OPTIONS"
+.IP \fB\-help\fR 4
+.IX Item "-help"
+Print out a usage message.
+.IP \fB\-topk8\fR 4
+.IX Item "-topk8"
+Normally a PKCS#8 private key is expected on input and a private key will be
+written to the output file. With the \fB\-topk8\fR option the situation is
+reversed: it reads a private key and writes a PKCS#8 format key.
+.IP "\fB\-inform\fR \fBDER\fR|\fBPEM\fR, \fB\-outform\fR \fBDER\fR|\fBPEM\fR" 4
+.IX Item "-inform DER|PEM, -outform DER|PEM"
+The input and formats; the default is \fBPEM\fR.
+See \fBopenssl\-format\-options\fR\|(1) for details.
+.Sp
+If a key is being converted from PKCS#8 form (i.e. the \fB\-topk8\fR option is
+not used) then the input file must be in PKCS#8 format. An encrypted
+key is expected unless \fB\-nocrypt\fR is included.
+.Sp
+If \fB\-topk8\fR is not used and \fBPEM\fR mode is set the output file will be an
+unencrypted private key in PKCS#8 format. If the \fB\-traditional\fR option is
+used then a traditional format private key is written instead.
+.Sp
+If \fB\-topk8\fR is not used and \fBDER\fR mode is set the output file will be an
+unencrypted private key in traditional DER format.
+.Sp
+If \fB\-topk8\fR is used then any supported private key can be used for the input
+file in a format specified by \fB\-inform\fR. The output file will be encrypted
+PKCS#8 format using the specified encryption parameters unless \fB\-nocrypt\fR
+is included.
+.IP \fB\-traditional\fR 4
+.IX Item "-traditional"
+When this option is present and \fB\-topk8\fR is not a traditional format private
+key is written.
+.IP "\fB\-in\fR \fIfilename\fR" 4
+.IX Item "-in filename"
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+.IP "\fB\-passin\fR \fIarg\fR, \fB\-passout\fR \fIarg\fR" 4
+.IX Item "-passin arg, -passout arg"
+The password source for the input and output file.
+For more information about the format of \fBarg\fR
+see \fBopenssl\-passphrase\-options\fR\|(1).
+.IP "\fB\-out\fR \fIfilename\fR" 4
+.IX Item "-out filename"
+This specifies the output filename to write a key to or standard output by
+default. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should \fBnot\fR be the same as the input
+filename.
+.IP "\fB\-iter\fR \fIcount\fR" 4
+.IX Item "-iter count"
+When creating new PKCS#8 containers, use a given number of iterations on
+the password in deriving the encryption key for the PKCS#8 output.
+High values increase the time required to brute-force a PKCS#8 container.
+.IP \fB\-noiter\fR 4
+.IX Item "-noiter"
+When creating new PKCS#8 containers, use 1 as iteration count.
+.IP \fB\-nocrypt\fR 4
+.IX Item "-nocrypt"
+PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
+structures using an appropriate password based encryption algorithm. With
+this option an unencrypted PrivateKeyInfo structure is expected or output.
+This option does not encrypt private keys at all and should only be used
+when absolutely necessary. Certain software such as some versions of Java
+code signing software used unencrypted private keys.
+.IP "\fB\-v2\fR \fIalg\fR" 4
+.IX Item "-v2 alg"
+This option sets the PKCS#5 v2.0 algorithm.
+.Sp
+The \fIalg\fR argument is the encryption algorithm to use, valid values include
+\&\fBaes128\fR, \fBaes256\fR and \fBdes3\fR. If this option isn't specified then \fBaes256\fR
+is used.
+.IP "\fB\-v2prf\fR \fIalg\fR" 4
+.IX Item "-v2prf alg"
+This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
+value would be \fBhmacWithSHA256\fR. If this option isn't set then the default
+for the cipher is used or \fBhmacWithSHA256\fR if there is no default.
+.Sp
+Some implementations may not support custom PRF algorithms and may require
+the \fBhmacWithSHA1\fR option to work.
+.IP "\fB\-v1\fR \fIalg\fR" 4
+.IX Item "-v1 alg"
+This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used.  Some
+older implementations may not support PKCS#5 v2.0 and may require this option.
+If not specified PKCS#5 v2.0 form is used.
+.IP \fB\-scrypt\fR 4
+.IX Item "-scrypt"
+Uses the \fBscrypt\fR algorithm for private key encryption using default
+parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
+key. These parameters can be modified using the \fB\-scrypt_N\fR, \fB\-scrypt_r\fR,
+\&\fB\-scrypt_p\fR and \fB\-v2\fR options.
+.IP "\fB\-scrypt_N\fR \fIN\fR, \fB\-scrypt_r\fR \fIr\fR, \fB\-scrypt_p\fR \fIp\fR" 4
+.IX Item "-scrypt_N N, -scrypt_r r, -scrypt_p p"
+Sets the scrypt \fIN\fR, \fIr\fR or \fIp\fR parameters.
+.IP \fB\-saltlen\fR 4
+.IX Item "-saltlen"
+Sets the length (in bytes) of the salt to use for the PBE algorithm.
+If this value is not specified, the default for PBES2 is 16 (128 bits)
+and 8 (64 bits) for PBES1.
+.IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
+.IX Item "-rand files, -writerand file"
+See "Random State Options" in \fBopenssl\fR\|(1) for details.
+.IP "\fB\-engine\fR \fIid\fR" 4
+.IX Item "-engine id"
+See "Engine Options" in \fBopenssl\fR\|(1).
+This option is deprecated.
+.IP "\fB\-provider\fR \fIname\fR" 4
+.IX Item "-provider name"
+.PD 0
+.IP "\fB\-provider\-path\fR \fIpath\fR" 4
+.IX Item "-provider-path path"
+.IP "\fB\-propquery\fR \fIpropq\fR" 4
+.IX Item "-propquery propq"
+.PD
+See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7).
+.SH NOTES
+.IX Header "NOTES"
+By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
+AES with HMAC and SHA256 is used.
+.PP
+Some older implementations do not support PKCS#5 v2.0 format and require
+the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
+encryption algorithms such as 56 bit DES.
+.PP
+Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
+counts are more secure that those encrypted using the traditional
+SSLeay compatible formats. So if additional security is considered
+important the keys should be converted.
+.PP
+It is possible to write out DER encoded encrypted private keys in
+PKCS#8 format because the encryption details are included at an ASN1
+level whereas the traditional format includes them at a PEM level.
+.SH "PKCS#5 V1.5 AND PKCS#12 ALGORITHMS"
+.IX Header "PKCS#5 V1.5 AND PKCS#12 ALGORITHMS"
+Various algorithms can be used with the \fB\-v1\fR command line option,
+including PKCS#5 v1.5 and PKCS#12. These are described in more detail
+below.
+.IP "\fBPBE\-MD2\-DES PBE\-MD5\-DES\fR" 4
+.IX Item "PBE-MD2-DES PBE-MD5-DES"
+These algorithms were included in the original PKCS#5 v1.5 specification.
+They only offer 56 bits of protection since they both use DES.
+.IP "\fBPBE\-SHA1\-RC2\-64\fR, \fBPBE\-MD2\-RC2\-64\fR, \fBPBE\-MD5\-RC2\-64\fR, \fBPBE\-SHA1\-DES\fR" 4
+.IX Item "PBE-SHA1-RC2-64, PBE-MD2-RC2-64, PBE-MD5-RC2-64, PBE-SHA1-DES"
+These algorithms are not mentioned in the original PKCS#5 v1.5 specification
+but they use the same key derivation algorithm and are supported by some
+software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
+56 bit DES.
+.IP "\fBPBE\-SHA1\-RC4\-128\fR, \fBPBE\-SHA1\-RC4\-40\fR, \fBPBE\-SHA1\-3DES\fR, \fBPBE\-SHA1\-2DES\fR, \fBPBE\-SHA1\-RC2\-128\fR, \fBPBE\-SHA1\-RC2\-40\fR" 4
+.IX Item "PBE-SHA1-RC4-128, PBE-SHA1-RC4-40, PBE-SHA1-3DES, PBE-SHA1-2DES, PBE-SHA1-RC2-128, PBE-SHA1-RC2-40"
+These algorithms use the PKCS#12 password based encryption algorithm and
+allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+Convert a private key to PKCS#8 format using default parameters (AES with
+256 bit key and \fBhmacWithSHA256\fR):
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 unencrypted format:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-nocrypt \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#5 v2.0 format using triple DES:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-v2 des3 \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
+mode and \fBhmacWithSHA512\fR PRF:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-v2prf hmacWithSHA512 \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
+(DES):
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-v1 PBE\-MD5\-DES \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem \-v1 PBE\-SHA1\-3DES
+.Ve
+.PP
+Read a DER unencrypted PKCS#8 format private key:
+.PP
+.Vb 1
+\& openssl pkcs8 \-inform DER \-nocrypt \-in key.der \-out key.pem
+.Ve
+.PP
+Convert a private key from any PKCS#8 encrypted format to traditional format:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in pk8.pem \-traditional \-out key.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 format, encrypting with AES\-256 and with
+one million iterations of the password:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-iter 1000000 \-out pk8.pem
+.Ve
+.SH STANDARDS
+.IX Header "STANDARDS"
+Test vectors from this PKCS#5 v2.0 implementation were posted to the
+pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
+counts, several people confirmed that they could decrypt the private
+keys produced and therefore, it can be assumed that the PKCS#5 v2.0
+implementation is reasonably accurate at least as far as these
+algorithms are concerned.
+.PP
+The format of PKCS#8 DSA (and other) private keys is not well documented:
+it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
+PKCS#8 private key format complies with this standard.
+.SH BUGS
+.IX Header "BUGS"
+There should be an option that prints out the encryption algorithm
+in use and other details such as the iteration count.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBopenssl\fR\|(1),
+\&\fBopenssl\-dsa\fR\|(1),
+\&\fBopenssl\-rsa\fR\|(1),
+\&\fBopenssl\-genrsa\fR\|(1),
+\&\fBopenssl\-gendsa\fR\|(1)
+.SH HISTORY
+.IX Header "HISTORY"
+The \fB\-iter\fR option was added in OpenSSL 1.1.0.
+.PP
+The \fB\-engine\fR option was deprecated in OpenSSL 3.0.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+<https://www.openssl.org/source/license.html>.