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.
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.
@ -14,23 +16,28 @@ Creates a credentials object, with the optional details being a dictionary with
* `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
Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests.
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.
`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.
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'.
Calculates the digest of all of the passed data to be hashed.
The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
### crypto.createHmac(algorithm, key)
@ -42,66 +49,82 @@ Creates and returns a hmac object, a cryptographic hmac with the given algorithm
### hmac.update(data)
Update the hmac content with the given `data`. This can be called many times with new data as it is streamed.
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'.
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.
`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.
On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms.
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'.
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'.
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.
Creates and returns a decipher object, with the given algorithm and key.
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'.
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: `'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'.
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'.
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.
Updates the signer object with data.
This can be called many times with new data as it is streamed.
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.
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'
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.
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.
Updates the verifyer object with data.
This can be called many times with new data as it is streamed.
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'.
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.
@ -123,9 +123,14 @@ when the server has been bound.
### server.setSecure(credentials)
Enables HTTPS support for the server, with the crypto module credentials specifying the private key and certificate of the server, and optionally the CA certificates for use in client authentication.
Enables HTTPS support for the server, with the crypto module credentials
specifying the private key and certificate of the server, and optionally
the CA certificates for use in client authentication.
If the credentials hold one or more CA certificates, then the server will request for the client to submit a client certificate as part of the HTTPS connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate() from the server's request.connection.
If the credentials hold one or more CA certificates, then the server will request
for the client to submit a client certificate as part of the HTTPS connection handshake.
The validity and content of this can be accessed via `verifyPeer()`
and `getPeerCertificate()` from the server's `request.connection`.
### server.close()
@ -134,8 +139,8 @@ Stops the server from accepting new connections.
## http.ServerRequest
This object is created internally by a HTTP server--not by
the user--and passed as the first argument to a `'request'` listener.
This object is created internally by a HTTP server--not by
the user--and passed as the first argument to a `'request'` listener.
This is an `EventEmitter` with the following events:
@ -382,9 +387,13 @@ Constructs a new HTTP client. `port` and
`host` refer to the server to be connected to. A
stream is not established until a request is issued.
`secure` is an optional boolean flag to enable https support and `credentials` is an optional credentials object from the crypto module, which may hold the client's private key, certificate, and a list of trusted CA certificates.
`secure` is an optional boolean flag to enable https support and `credentials` is an optional
credentials object from the crypto module, which may hold the client's private key,
certificate, and a list of trusted CA certificates.
If the connection is secure, but no explicit CA certificates are passed in the credentials, then node.js will default to the publicly trusted list of CA certificates, as given in http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
If the connection is secure, but no explicit CA certificates are passed
in the credentials, then node.js will default to the publicly trusted list
of CA certificates, as given in <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
@ -407,11 +416,13 @@ the user to stream a body to the server with `request.write()`.)
### client.verifyPeer()
Returns true or false depending on the validity of the server's certificate in the context of the defined or default list of trusted CA certificates.
Returns true or false depending on the validity of the server's certificate
in the context of the defined or default list of trusted CA certificates.
### client.getPeerCertificate()
Returns a JSON structure detailing the server's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
Returns a JSON structure detailing the server's certificate, containing a dictionary
with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`.
@ -170,14 +170,17 @@ The shell that executed node should see the exit code as 1.
### process.getgid()
Gets the group identity of the process. (See getgid(2).) This is the numerical group id, not the group name.
Gets the group identity of the process. (See getgid(2).)
This is the numerical group id, not the group name.
console.log('Current gid: ' + process.getgid());
### process.setgid(id)
Sets the group identity of the process. (See setgid(2).) This accepts either a numerical ID or a groupname string. If a groupname is specified, this method blocks while resolving it to a numerical ID.
Sets the group identity of the process. (See setgid(2).) This accepts either
a numerical ID or a groupname string. If a groupname is specified, this method
blocks while resolving it to a numerical ID.
console.log('Current gid: ' + process.getgid());
try {
@ -191,14 +194,17 @@ Sets the group identity of the process. (See setgid(2).) This accepts either a
### process.getuid()
Gets the user identity of the process. (See getuid(2).) This is the numerical userid, not the username.
Gets the user identity of the process. (See getuid(2).)
This is the numerical userid, not the username.
console.log('Current uid: ' + process.getuid());
### process.setuid(id)
Sets the user identity of the process. (See setuid(2).) This accepts either a numerical ID or a username string. If a username is specified, this method blocks while resolving it to a numerical ID.
Sets the user identity of the process. (See setuid(2).) This accepts either
a numerical ID or a username string. If a username is specified, this method
Oleg Efimov
14 years ago
Ryan Dahl