mirror of
https://github.com/nodejs/node.git
synced 2024-11-29 15:06:33 +01:00
108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
## Crypto
|
|
|
|
Use `require('crypto')` to access this module.
|
|
|
|
The crypto module requires OpenSSL to be available on the underlying platform. It offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection.
|
|
|
|
It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.
|
|
|
|
### crypto.createCredentials(details)
|
|
|
|
Creates a credentials object, with the optional details being a dictionary with keys:
|
|
|
|
* `key` : a string holding the PEM encoded private key
|
|
* `cert` : a string holding the PEM encoded certificate
|
|
* `ca` : either a string or list of strings of PEM encoded CA certificates to trust.
|
|
|
|
If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in
|
|
http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
|
|
|
|
|
|
### crypto.createHash(algorithm)
|
|
|
|
Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests.
|
|
|
|
`algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are sha1, md5, sha256, sha512, etc. On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms.
|
|
|
|
### hash.update(data)
|
|
|
|
Updates the hash content with the given `data`. This can be called many times with new data as it is streamed.
|
|
|
|
### hash.digest(encoding='binary')
|
|
|
|
Calculates the digest of all of the passed data to be hashed. The `encoding` can be 'hex', 'binary' or 'base64'.
|
|
|
|
|
|
### crypto.createHmac(algorithm, key)
|
|
|
|
Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.
|
|
|
|
`algorithm` is dependent on the available algorithms supported by OpenSSL - see createHash above.
|
|
`key` is the hmac key to be used.
|
|
|
|
### hmac.update(data)
|
|
|
|
Update the hmac content with the given `data`. This can be called many times with new data as it is streamed.
|
|
|
|
### hmac.digest(encoding='binary')
|
|
|
|
Calculates the digest of all of the passed data to the hmac. The `encoding` can be 'hex', 'binary' or 'base64'.
|
|
|
|
|
|
### crypto.createCipher(algorithm, key)
|
|
|
|
Creates and returns a cipher object, with the given algorithm and key.
|
|
|
|
`algorithm` is dependent on OpenSSL, examples are aes192, etc. On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms.
|
|
|
|
### cipher.update(data, input_encoding='binary', output_encoding='binary')
|
|
|
|
Updates the cipher with `data`, the encoding of which is given in `input_encoding` and can be 'utf8', 'ascii' or 'binary'. The `output_encoding` specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'.
|
|
|
|
Returns the enciphered contents, and can be called many times with new data as it is streamed.
|
|
|
|
### cipher.final(output_encoding='binary')
|
|
|
|
Returns any remaining enciphered contents, with `output_encoding` being one of: 'binary', 'ascii' or 'utf8'.
|
|
|
|
### crypto.createDecipher(algorithm, key)
|
|
|
|
Creates and returns a decipher object, with the given algorithm and key. This is the mirror of the cipher object above.
|
|
|
|
### decipher.update(data, input_encoding='binary', output_encoding='binary')
|
|
|
|
Updates the decipher with `data`, which is encoded in 'binary', 'base64' or 'hex'. The `output_decoding` specifies in what format to return the deciphered plaintext - either 'binary', 'ascii' or 'utf8'.
|
|
|
|
### decipher.final(output_encoding='binary')
|
|
|
|
Returns any remaining plaintext which is deciphered, with `output_encoding' being one of: 'binary', 'ascii' or 'utf8'.
|
|
|
|
|
|
### crypto.createSign(algorithm)
|
|
|
|
Creates and returns a signing object, with the given algorithm. On recent OpenSSL releases, `openssl list-public-key-algorithms` will display the available signing algorithms. Examples are 'RSA-SHA256'.
|
|
|
|
### signer.update(data)
|
|
|
|
Updates the signer object with data. This can be called many times with new data as it is streamed.
|
|
|
|
### signer.sign(private_key, output_format='binary')
|
|
|
|
Calculates the signature on all the updated data passed through the signer. `private_key` is a string containing the PEM encoded private key for signing.
|
|
|
|
Returns the signature in `output_format` which can be 'binary', 'hex' or 'base64'
|
|
|
|
### crypto.createVerify(algorithm)
|
|
|
|
Creates and returns a verification object, with the given algorithm. This is the mirror of the signing object above.
|
|
|
|
### verifier.update(data)
|
|
|
|
Updates the verifyer object with data. This can be called many times with new data as it is streamed.
|
|
|
|
### verifier.verify(public_key, signature, signature_format='binary')
|
|
|
|
Verifies the signed data by using the `public_key` which is a string containing the PEM encoded public key, and `signature`, which is the previously calculates signature for the data, in the `signature_format` which can be 'binary', 'hex' or 'base64'.
|
|
|
|
Returns true or false depending on the validity of the signature for the data and public key.
|