diff options
| -rw-r--r-- | lib/libcrypto/des/des.pod | 217 | ||||
| -rw-r--r-- | lib/libcrypto/doc/EVP_OpenInit.pod | 51 | ||||
| -rw-r--r-- | lib/libcrypto/doc/EVP_SealInit.pod | 70 | ||||
| -rw-r--r-- | lib/libcrypto/doc/EVP_SignInit.pod | 85 | ||||
| -rw-r--r-- | lib/libcrypto/doc/EVP_VerifyInit.pod | 71 |
5 files changed, 494 insertions, 0 deletions
diff --git a/lib/libcrypto/des/des.pod b/lib/libcrypto/des/des.pod new file mode 100644 index 00000000000..bf479e83d26 --- /dev/null +++ b/lib/libcrypto/des/des.pod @@ -0,0 +1,217 @@ +=pod + +=head1 NAME + +des - encrypt or decrypt data using Data Encryption Standard + +=head1 SYNOPSIS + +B<des> +( +B<-e> +| +B<-E> +) | ( +B<-d> +| +B<-D> +) | ( +B<->[B<cC>][B<ckname>] +) | +[ +B<-b3hfs> +] [ +B<-k> +I<key> +] +] [ +B<-u>[I<uuname>] +[ +I<input-file> +[ +I<output-file> +] ] + +=head1 NOTE + +This page describes the B<des> stand-alone program, not the B<openssl des> +command. + +=head1 DESCRIPTION + +B<des> +encrypts and decrypts data using the +Data Encryption Standard algorithm. +One of +B<-e>, B<-E> +(for encrypt) or +B<-d>, B<-D> +(for decrypt) must be specified. +It is also possible to use +B<-c> +or +B<-C> +in conjunction or instead of the a encrypt/decrypt option to generate +a 16 character hexadecimal checksum, generated via the +I<des_cbc_cksum>. + +Two standard encryption modes are supported by the +B<des> +program, Cipher Block Chaining (the default) and Electronic Code Book +(specified with +B<-b>). + +The key used for the DES +algorithm is obtained by prompting the user unless the +B<-k> +I<key> +option is given. +If the key is an argument to the +B<des> +command, it is potentially visible to users executing +ps(1) +or a derivative. To minimise this possibility, +B<des> +takes care to destroy the key argument immediately upon entry. +If your shell keeps a history file be careful to make sure it is not +world readable. + +Since this program attempts to maintain compatibility with sunOS's +des(1) command, there are 2 different methods used to convert the user +supplied key to a des key. +Whenever and one or more of +B<-E>, B<-D>, B<-C> +or +B<-3> +options are used, the key conversion procedure will not be compatible +with the sunOS des(1) version but will use all the user supplied +character to generate the des key. +B<des> +command reads from standard input unless +I<input-file> +is specified and writes to standard output unless +I<output-file> +is given. + +=head1 OPTIONS + +=over 4 + +=item B<-b> + +Select ECB +(eight bytes at a time) encryption mode. + +=item B<-3> + +Encrypt using triple encryption. +By default triple cbc encryption is used but if the +B<-b> +option is used then triple ECB encryption is performed. +If the key is less than 8 characters long, the flag has no effect. + +=item B<-e> + +Encrypt data using an 8 byte key in a manner compatible with sunOS +des(1). + +=item B<-E> + +Encrypt data using a key of nearly unlimited length (1024 bytes). +This will product a more secure encryption. + +=item B<-d> + +Decrypt data that was encrypted with the B<-e> option. + +=item B<-D> + +Decrypt data that was encrypted with the B<-E> option. + +=item B<-c> + +Generate a 16 character hexadecimal cbc checksum and output this to +stderr. +If a filename was specified after the +B<-c> +option, the checksum is output to that file. +The checksum is generated using a key generated in a sunOS compatible +manner. + +=item B<-C> + +A cbc checksum is generated in the same manner as described for the +B<-c> +option but the DES key is generated in the same manner as used for the +B<-E> +and +B<-D> +options + +=item B<-f> + +Does nothing - allowed for compatibility with sunOS des(1) command. + +=item B<-s> + +Does nothing - allowed for compatibility with sunOS des(1) command. + +=item B<-k> I<key> + +Use the encryption +I<key> +specified. + +=item B<-h> + +The +I<key> +is assumed to be a 16 character hexadecimal number. +If the +B<-3> +option is used the key is assumed to be a 32 character hexadecimal +number. + +=item B<-u> + +This flag is used to read and write uuencoded files. If decrypting, +the input file is assumed to contain uuencoded, DES encrypted data. +If encrypting, the characters following the B<-u> are used as the name of +the uuencoded file to embed in the begin line of the uuencoded +output. If there is no name specified after the B<-u>, the name text.des +will be embedded in the header. + +=head1 SEE ALSO + +ps(1), +L<des_crypt(3)|des_crypt(3)> + +=head1 BUGS + +The problem with using the +B<-e> +option is the short key length. +It would be better to use a real 56-bit key rather than an +ASCII-based 56-bit pattern. Knowing that the key was derived from ASCII +radically reduces the time necessary for a brute-force cryptographic attack. +My attempt to remove this problem is to add an alternative text-key to +DES-key function. This alternative function (accessed via +B<-E>, B<-D>, B<-S> +and +B<-3>) +uses DES to help generate the key. + +Be carefully when using the B<-u> option. Doing B<des -ud> I<filename> will +not decrypt filename (the B<-u> option will gobble the B<-d> option). + +The VMS operating system operates in a world where files are always a +multiple of 512 bytes. This causes problems when encrypted data is +send from Unix to VMS since a 88 byte file will suddenly be padded +with 424 null bytes. To get around this problem, use the B<-u> option +to uuencode the data before it is send to the VMS system. + +=head1 AUTHOR + +Eric Young (eay@cryptsoft.com) + +=cut diff --git a/lib/libcrypto/doc/EVP_OpenInit.pod b/lib/libcrypto/doc/EVP_OpenInit.pod new file mode 100644 index 00000000000..9707a4b3997 --- /dev/null +++ b/lib/libcrypto/doc/EVP_OpenInit.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, + int ekl,unsigned char *iv,EVP_PKEY *priv); + void EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + void EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +decryption. They decrypt a public key encrypted symmetric key and +then decrypt data using it. + +EVP_OpenInit() initialises a cipher context B<ctx> for decryption +with cipher B<type>. It decrypts the encrypted symmetric key of length +B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>. +The IV is supplied in the B<iv> parameter. + +EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties +as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual +page. + +=head1 RETURN VALUES + +EVP_OpenInit() returns -1 on error or an non zero integer (actually the +recovered secret key size) if successful. + +EVP_SealUpdate() does not return a value. + +EVP_SealFinal() returns 0 if the decrypt failed or 1 for success. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>,L<rand(3)|rand(3)> +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, +L<EVP_SealInit(3)|EVP_SealInit(3)> + +=head1 HISTORY + +=cut diff --git a/lib/libcrypto/doc/EVP_SealInit.pod b/lib/libcrypto/doc/EVP_SealInit.pod new file mode 100644 index 00000000000..1579d110fa2 --- /dev/null +++ b/lib/libcrypto/doc/EVP_SealInit.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, + int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk); + void EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + void EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +encryption. They generate a random key and then "envelope" it by +using public key encryption. Data can then be encrypted using this +key. + +EVP_SealInit() initialises a cipher context B<ctx> for encryption +with cipher B<type> using a random secret key and IV supplied in +the B<iv> parameter. B<type> is normally supplied by a function such +as EVP_des_cbc(). The secret key is encrypted using one or more public +keys, this allows the same encrypted data to be decrypted using any +of the corresponding private keys. B<ek> is an array of buffers where +the public key encrypted secret key will be written, each buffer must +contain enough room for the corresponding encrypted key: that is +B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual +size of each encrypted secret key is written to the array B<ekl>. B<pubk> is +an array of B<npubk> public keys. + +EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties +as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual +page. + +=head1 RETURN VALUES + +EVP_SealInit() returns -1 on error or B<npubk> if successful. + +EVP_SealUpdate() and EVP_SealFinal() do not return values. + +=head1 NOTES + +Because a random secret key is generated the random number generator +must be seeded before calling EVP_SealInit(). + +The public key must be RSA because it is the only OpenSSL public key +algorithm that supports key transport. + +Envelope encryption is the usual method of using public key encryption +on large amounts of data, this is because public key encryption is slow +but symmetric encryption is fast. So symmetric encryption is used for +bulk encryption and the small random symmetric key used is transferred +using public key encryption. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>,L<rand(3)|rand(3)> +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)|EVP_OpenInit(3)> + +=head1 HISTORY + +=cut diff --git a/lib/libcrypto/doc/EVP_SignInit.pod b/lib/libcrypto/doc/EVP_SignInit.pod new file mode 100644 index 00000000000..bbc9203c9ca --- /dev/null +++ b/lib/libcrypto/doc/EVP_SignInit.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); + + int EVP_PKEY_size(EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital +signatures. + +EVP_SignInit() initialises a signing context B<ctx> to using digest +B<type>: this will typically be supplied by a function such as +EVP_sha1(). + +EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the +signature context B<ctx>. This funtion can be called several times on the +same B<ctx> to include additional data. + +EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> +and places the signature in B<sig>. If the B<s> parameter is not NULL +then the number of bytes of data written (i.e. the length of the signature) +will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes +will be written. After calling EVP_SignFinal() no additional calls to +EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialiase +a new signature operation. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual +signature returned by EVP_SignFinal() may be smaller. + +=head1 RETURN VALUES + +EVP_SignInit() and EVP_SignUpdate() do not return values. + +EVP_SignFinal() returns 1 for success and 0 for failure. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L<EVP_DigestInit(3)|EVP_DigestInit(3)>. + +When signing with DSA private keys the random number generator must be seeded +or the operation will fail. The random number generator does not need to be +seeded for RSA signatures. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<digest(1)|digest(1)> + +=head1 HISTORY + +EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/lib/libcrypto/doc/EVP_VerifyInit.pod b/lib/libcrypto/doc/EVP_VerifyInit.pod new file mode 100644 index 00000000000..3b5e07f4ade --- /dev/null +++ b/lib/libcrypto/doc/EVP_VerifyInit.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature verification routines are a high level interface to digital +signatures. + +EVP_VerifyInit() initialises a verification context B<ctx> to using digest +B<type>: this will typically be supplied by a function such as EVP_sha1(). + +EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the +verification context B<ctx>. This funtion can be called several times on the +same B<ctx> to include additional data. + +EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey> +and against the B<siglen> bytes at B<sigbuf>. After calling EVP_VerifyFinal() +no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit() +can be called to initialiase a new verification operation. + +=head1 RETURN VALUES + +EVP_VerifyInit() and EVP_VerifyUpdate() do not return values. + +EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some +other error occurred. + +The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L<EVP_DigestInit(3)|EVP_DigestInit(3)>. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L<EVP_SignInit(3)|EVP_SignInit(3)>, +L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, +L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, +L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, +L<sha(3)|sha(3)>, L<digest(1)|digest(1)> + +=head1 HISTORY + +EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut |