mongo 2.12.4 → 2.14.0.rc1

data/spec/README.aws-auth.md

@@ -0,0 +1,318 @@
+# Testing AWS Authentication
+
+## Server Configuration
+
+AWS authentication requires the following to be done on the server side:
+
+1. The AWS authentication mechanism must be enabled on the server. This
+is done by adding `MONGODB-AWS` to the values in `authenticationMechanisms`
+server parameter.
+
+2. A user must be created in the `$external` database with the ARN matching
+the IAM user or role that the client will authenticate as.
+
+Note that the server does not need to have AWS keys provided to it - it
+uses the keys that the client provides during authentication.
+
+An easy way to configure the deployment in the required fashion is to
+configure the deployment to accept both password authentication and
+AWS authentication, and add a bootstrap user:
+
+    mlaunch init --single --auth --username root --password toor \
+      --setParameter authenticationMechanisms=MONGODB-AWS,SCRAM-SHA-1,SCRAM-SHA-256 \
+      --dir /tmp/db
+
+Then connect as the bootstrap user and create AWS-mapped users:
+
+    mongo mongodb://root:toor@localhost:27017
+    
+    # In the mongo shell:
+    use $external
+    db.createUser({
+      user: 'arn:aws:iam::1234567890:user/test',
+      roles: [{role:'root', db:'admin'}]})
+
+The ARN can be retrieved from the AWS management console. Alternatively,
+if the IAM user's access and secret keys are known, trying to authenticate
+as the user will log the user's ARN into the server log when authentication
+fails; this ARN can be then used to create the server user.
+
+With the server user created, it is possible to authenticate using AWS.
+The following example uses regular user credentials for an IAM user
+created as described in the next section;
+
+    mongo 'mongodb://AKIAAAAAAAAAAAA:t9t2mawssecretkey@localhost:27017/?authMechanism=MONGODB-AWS&authsource=$external'
+
+To authenticate, provide the IAM user's access key id as the username and
+secret access key as the password. Note that the username and the password
+must be percent-escaped when they are passed in the URI as the examples here
+show. Also note that the user's ARN is not explicitly specified by the client
+during authentication - the server determines the ARN from the acess
+key id and the secret access key provided by the client.
+
+## Provisioning Tools
+
+The Ruby driver includes tools that set up the resources needed to test
+AWS authentication. These are exposed by the `.evergreen/aws` script.
+To use this script, it must be provided AWS credentials and the region
+to operate in. The credentials and region can be given as command-line
+arguments or set in the environment, as follows:
+
+    export AWS_ACCESS_KEY_ID=AKIAYOURACCESSKEY
+    export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY
+    export AWS_REGION=us-east-1
+
+If you also perform manual testing (for example by following some of the
+instructions in this file), ensure AWS_SESSION_TOKEN is not set
+unless you are intending to invoke the `.evergreen/aws` script with
+temporary credentials:
+
+    unset AWS_SESSION_TOKEN
+
+Note that [AWS CLI](https://aws.amazon.com/cli/) uses a different environment
+variable for the region - `AWS_DEFAULT_REGION` rather than `AWS_REGION`.
+If you also intend to use the AWS CLI, execute:
+
+    export AWS_DEFAULT_REGION=$AWS_REGION
+
+To verify that credentials are correctly set in the environment, you can
+perform the following operations:
+
+    # Test driver tooling
+    ./.evergreen/aws key-pairs
+    
+    # Test AWS CLI
+    aws sts get-caller-identity
+
+Alternatively, to provide the credentials on each call to the driver's
+`aws` script, use the `-a` and `-s` arguments as follows:
+
+    ./.evergreen/aws -a KEY-ID -s SECRET-KEY key-pairs
+
+## Common Setup
+
+In order to test all AWS authentication scenarios, a large number of AWS
+objects needs to be configured. This configuration is split into two parts:
+common setup and scenario-specific setup.
+
+The common setup is performed by running:
+
+    ./.evergreen/aws setup-resources
+
+This creates resources like security groups, IAM users and CloudWatch
+log groups that do not cost money. It is possible to test authentication
+with regular credentials and temporary credentials obtained via an
+AssumeRole request using these resources. In order to test authentication
+from an EC2 instance or an ECS task, the instance and/or the task need
+to be started which costs money and is performed as separate steps as
+detailed below.
+
+## Regular Credentials - IAM User
+
+AWS authentication as a regular IAM user requires having an IAM user to
+authenticate as. This user can be created using the AWS management console.
+The IAM user requires no permissions, but it must have the programmatic
+access enabled (i.e. have an access key ID and the secret access key).
+
+An IAM user is created as part of the common setup described earlier.
+To reset and retrieve the access key ID and secret access key for the
+created user, run:
+
+    ./.evergreen/aws reset-keys
+
+Note that if the user already had an access key, the old credentials are
+removed and replaced with new credentials.
+
+Given the credentials for the test user, the URI for running the driver
+test suite can be formed as follows:
+
+    export "MONGODB_URI=mongodb://$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY@localhost:27017/?authMechanism=MONGODB-AWS&authsource=$external"
+
+## Temporary Credentials - AssumeRole Request
+
+To test a user authenticating with an assumed role, you can follow
+[the example provided in Amazon documentation](https://aws.amazon.com/premiumsupport/knowledge-center/iam-assume-role-cli/)
+to set up the assumed role and related objects and obtain temporary credentials
+or use the driver's tooling using the commands given below.
+Since the temporary credentials expire, the role needs to be re-assumed
+periodically during testing and the new credentials and session token retrieved.
+
+If following the example in Amazon's documentation,
+[jq](https://stedolan.github.io/jq/) can be used to efficiently place the
+credentials from the AssumeRole request into the environment, as follows:
+
+    # Call given in the example guide
+    aws sts assume-role --role-arn arn:aws:iam::YOUR-ACCOUNT-ID:role/example-role --role-session-name AWSCLI-Session >~/.aws-assumed-role.json
+    
+    # Extract the credentials
+    export AWS_ACCESS_KEY_ID=`jq .Credentials.AccessKeyId  ~/.aws-assumed-role.json -r`
+    export AWS_SECRET_ACCESS_KEY=`jq .Credentials.SecretAccessKey  ~/.aws-assumed-role.json -r`
+    export AWS_SESSION_TOKEN=`jq .Credentials.SessionToken ~/.aws-assumed-role.json -r`
+
+Alternatively, the `./evergreen/aws` script can be used to assume the role.
+By default, it will assume the role that `setup-resources` action configured.
+
+Note: The ability to assume this role is granted to the
+[IAM user](#regular-credentials-iam-user) that the provisioning tool creates.
+Therefore the shell must be configured with credentials of the test user,
+not with credentials of the master user that performed the provisioning.
+
+To assume the role created by the common setup, run:
+
+    ./.evergreen/aws assume-role
+
+It is also possible to specify the ARN of the role to assume manually, if
+you created the role using other means:
+
+    ./.evergreen/aws assume-role ASSUME-ROLE-ARN
+
+To place the credentials into the environment:
+
+    eval $(./.evergreen/aws assume-role)
+    export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
+
+With the credentials in the environment, to verify that the role was assumed
+and the credentials are complete and correct, perform a `GetCallerIdentity`
+call:
+
+    aws sts get-caller-identity
+
+Given the credentials for the test user, the URI for running the driver
+test suite can be formed as follows:
+
+    export "MONGODB_URI=mongodb://$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY@localhost:27017/?authMechanism=MONGODB-AWS&authsource=$external&authMechanismProperties=AWS_SESSION_TOKEN:$AWS_SESSION_TOKEN"
+
+## Temporary Credentials - EC2 Instance Role
+
+To test authentication [using temporary credentials for an EC2 instance
+role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html),
+an EC2 instance launched with an IAM role or an EC2 instance configured
+with an instance profile is required. No permissions are needed for the
+IAM role used with the EC2 instance.
+
+To create an EC2 instance with an attached role using the AWS console:
+
+1. Crate an IAM role that the instance will use. It is not necessary to
+specify any permissions.
+2. Launch an instance, choosing the IAM role created in the launch wizard.
+
+To define an instance profile which allows adding and removing an IAM role
+to/from an instance at runtime, follow Amazon documentation
+[here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#attach-iam-role).
+To test temporary credentials obtained via an EC2 instance role in Evergreen,
+an instance profile must be associated with the running instance as per
+this guide.
+
+The driver provides tooling to configure a suitable instance profile and
+launch an EC2 instance that can have this instance profile attached to it.
+
+The instance profile and associated IAM role are created by the common
+setup described above. To launch an EC2 instance suitable for testing
+authentication via an EC2 role, run:
+
+    ./.evergreen/aws launch-ec2 path/to/ssh.key.pub
+
+The `launch-ec2` command takes one argument which is the path to the
+public key for the key pair to use for SSH access to the instance.
+
+This script will output the instance ID of the launched instance. The
+instance initially does not have an instance profile assigned; to assign
+the instance profile created in the common setup to the instance, run:
+
+    ./.evergreen/aws set-instance-profile i-instanceid
+
+To remove the instance profile from the instance, run:
+
+    ./.evergreen/aws clear-instance-profile i-instanceid
+
+To provision the instance for running the driver's test suite via Docker, run:
+
+    ip=12.34.56.78
+    ./.evergreen/provision-remote ubuntu@$ip docker
+
+To run the AWS auth tests using the EC2 instance role credentials, run:
+
+    ./.evergreen/test-docker-remote ubuntu@$ip \
+      MONGODB_VERSION=4.4 AUTH=aws-ec2 \
+      -s .evergreen/run-tests-aws-auth.sh \
+      -a .env.private
+
+Note that if if you are not using MongoDB AWS account for testing, you
+would need to specify MONGO_RUBY_DRIVER_AWS_AUTH_USER_ARN in your
+`.env.private` file with the ARN of the user to add to MongoDB. The easiest
+way to find out this value is to run the tests and note which username the
+test suite is trying to authenticate as.
+
+To terminate the instance, run:
+
+    ./.evergreen/aws stop-ec2
+
+## Temporary Credentials - ECS Task Role
+
+The basic procedure for setting up an ECS cluster is described in
+[this guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_AWSCLI_Fargate.html).
+For testing AWS auth, the ECS task must have a role assigned to it which is
+covered in [this guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
+and additionally [here](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html).
+
+Although not required for testing AWS auth specifically, it is very helpful
+for general troubleshooting of ECS provisioning to have log output from the
+tasks. Logging to CloudWatch is covered by [this Amazon guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/QuickStartEC2Instance.html)
+with these potentially helpful [additional](https://stackoverflow.com/questions/50397217/how-to-determine-the-cloudwatch-log-stream-for-a-fargate-service#50704804)
+[resources](https://help.sumologic.com/03Send-Data/Collect-from-Other-Data-Sources/AWS_Fargate_log_collection).
+A log group must be manually created, the steps for which are described
+[here](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
+
+Additional references:
+
+- [Task definition CPU and memory values](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html)
+
+The common setup creates all of the necessary prerequisites to test
+authentication using ECS task credentials, which includes an empty ECS
+cluster. To test authentication, a service needs to be created in the
+ECS cluster that runs the SSH daemon, which can be done by running:
+
+    ./.evergreen/aws launch-ecs path/to/ssh.key.pub
+
+The `launch-ecs` command takes one argument which is the path to the
+public key for the key pair to use for SSH access to the instance.
+
+This script generally produces no output if it succeeds. As the service takes
+some time to start, run the following command to check its status:
+
+    ./.evergreen/aws ecs-status
+
+The status output shows the tasks running in the ECS cluster ordered by their
+generation, with the newest ones first. Event log for the cluster is displayed,
+as well as event stream for the running task of the latest available generation
+which includes the Docker execution output collected via CloudWatch.
+The status output includes the public IP of the running task once it is
+available, which can be used to SSH into the container and run the tests.
+
+Note that when AWS auth from an ECS task is tested in Evergreen, the task is
+accessed via its private IP; when the test is performed using the provisioning
+tooling described in this document, the task is accessed via its public IP.
+
+If the public IP address is in the `IP` shell variable, provision the task:
+
+    ./.evergreen/provision-remote root@$IP local
+
+To run the credentials retrieval test on the ECS task, execute:
+
+    ./.evergreen/test-remote root@$IP env AUTH=aws-ecs RVM_RUBY=ruby-2.7 MONGODB_VERSION=4.4 TEST_CMD='rspec spec/integration/aws*spec.rb' .evergreen/run-tests.sh
+
+To run the test again without rebuilding the remote environment, execute:
+
+    ./.evergreen/test-remote -e root@$IP \
+      env AUTH=aws-ecs RVM_RUBY=ruby-2.7 sh -c '\
+        export PATH=`pwd`/rubies/ruby-2.7/bin:$PATH && \
+        eval export `strings /proc/1/environ |grep ^AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` && \
+        bundle exec rspec spec/integration/aws*spec.rb'
+
+Note that this command retrieves the value of `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`
+from the PID 1 environment and places it into the current environment prior to
+running the tests.
+
+To terminate the AWS auth-related ECS tasks, run:
+
+    ./.evergreen/aws stop-ecs

data/spec/README.md

@@ -107,7 +107,7 @@ other tests require a sharded cluster with more than one shard. Tests requiring
 a single shard can be run against a deployment with multiple shards by
 specifying only one mongos address in MONGODB_URI.
 
-## Note Regarding SSL/TLS Arguments
+## Note Regarding TLS/SSL Arguments
 
 MongoDB 4.2 (server and shell) added new command line options for setting TLS
 parameters. These options follow the naming of URI options used by both the
@@ -185,6 +185,51 @@ verification, run:
 Note that there are tests in the test suite that cover TLS verification, and
 they may fail if the test suite is run in this way.
 
+## OCSP
+
+There are several types of OCSP tests implemented in the test suite.
+
+OCSP unit tests are in `spec/integration/ocsp_verifier_spec.rb`. To run
+these, set `OCSP_VERIFIER=1` in the environment. There must NOT be a process
+running on the host port 8100 as that port will be used by the OCSP responder
+launched by the tests.
+
+For the remaining OCSP tests, the following environment variables must be set
+to the possible values indicated below:
+
+    OCSP_ALGORITHM=rsa|ecdsa
+    OCSP_STATUS=valid|revoked|unknown
+    OCSP_DELEGATE=0|1
+    OCSP_MUST_STAPLE=0|1
+
+These tests also require the mock OCSP responder running on the host machine
+on port 8100 with the configuration that matches the environment variables
+just described. Please refer to the Docker and Evergreen scripts in the
+driver repository for further details.
+
+Additionally, the server must be configured to use the appropriate server
+certificate and CA certificate from the respective subdirectory of
+`spec/support/ocsp`. This is easiest to achieve by using the Docker tooling
+described in `.evergreen/README.md`.
+
+OCSP connectivity tests are in `spec/integration/ocsp_connectivity.rb`.
+These test the combinations described
+[here](https://github.com/mongodb/specifications/blob/master/source/ocsp-support/tests/README.rst#integration-tests-permutations-to-be-tested).
+To run these tests, set `OCSP_CONNECTIVITY=pass` environment variable if
+the tests are expected to connect successfully or `OCSP_CONNECTIVITY=fail` if
+the tests are expected to not connect.
+Note that some of these configurations require OCSP responder to return
+the failure response; in such configurations, ONLY the OCSP connectivity tests
+may pass (since the driver may reject connections to servers when OCSP
+responder returns the failure response, or OCSP verification otherwise
+definitively fails).
+
+When not running either OCSP verifier tests or OCSP connectivity tests but
+when OCSP algorithm is configured, the test suite will execute normally
+using the provided `MONGO_URI`. This configuration may be used to exercise
+OCSP while running the full test suite. In this case, setting `OCSP_STATUS`
+to `revoked` will generally cause the test suite to fail.
+
 ## Authentication
 
 mlaunch can configure authentication on the server:
@@ -302,30 +347,50 @@ The driver test suite includes a number of Kerberos-related integration tests
 in the `spec/kerberos` directory. These require a provisioned Kerberos
 deployment and appropriately configured MongoDB deployment. One such deployment
 is provided internally by MongoDB and is used in the driver's Evergreen
-configuration; it is also possible to provision a test deployment locally.
+configuration; it is also possible to provision a test deployment locally,
+either via the Docker tooling provided by the driver test suite or manually.
+
+#### Via Docker
+
+Run:
+
+    ./.evergreen/test-on-docker -s .evergreen/run-tests-kerberos-integration.sh -pd rhel70
+
+When `SASL_HOST` environment variable is not set, the Kerberos integration
+test script `.evergreen/run-tests-kerberos-integration.sh` provisions a
+local Kerberos deployment in the Docker container and configures the test suite
+to use it.
+
+Note: the tooling is currently set up to provision a working `rhel70`
+container. Ubuntu distros are not presently supported.
+
+#### Locally
 
 The following additional environment variables must be set to run the
 Kerberos integration tests:
 
 - `MONGO_RUBY_DRIVER_KERBEROS_INTEGRATION=1`
-- `SASL_HOST`: the host name of the MongoDB server that is configured to
+- `SASL_HOST`: the FQDN host name of the MongoDB server that is configured to
 use Kerberos. Note that this is NOT the Kerberos domain controller (KDC).
+- `SASL_REALM`: the Kerberos realm. Depending on how Kerberos is configured,
+this can be the same as or different from `SASL_HOST`. The Evergreen
+configuration uses the same host and realm; Docker configuration provided
+by the Ruby driver uses different host and realm.
 - `SASL_PORT`: the port number that the Kerberized MongoDB server is
-listenin on.
+listening on.
 - `SASL_USER`: the username to provide to MongoDB for authentication.
-- `SASL_PASS`: the password to provide to MongoDB for authentication.
+This must match the username of the principal.
 - `SASL_DB`: the database that stores the user used for authentication. This
 is the "auth soure" in MongoDB parlance. Normally this should be `$external`.
 - `PRINCIPAL`: the Kerberos principal to use for authentication, in the
 form of `username@realm`. Note that the realm is commonly uppercased.
 - `KERBEROS_DB`: the database that the user has access to.
-- `KEYTAB_BASE64`: Base64 encoded keytab for the user. Used instead of the
-password.
 
-There are several steps that must be taken in order to set up Kerberos on
-the client side before it is usable by the driver for authentication against
-a Kerberized server. Consult the `.evergreen/run-tests-kerberos-integration.sh`
-file for details.
+Note that the driver does not directly provide a password to the MongoDB
+server when using Kerberos authentication, and because of this there is no
+user password provided to the test suite either when Kerberos authentication
+is used. Instead, there must be a local session established via e.g. `kinit`.
+Consult the `.evergreen/run-tests-kerberos-integration.sh` file for details.
 
 ## Client-Side Encryption
 
@@ -470,11 +535,54 @@ set names:
 However, as noted in the caveats section, changing the database name used by
 the test suite is not supported.
 
+## Special Tests
+
 Some tests require internet connectivity, for example to test DNS seed lists
 and SRV URIs. These tests can be skipped by setting the following environment
 variable:
 
-    EXTERNAL_DISABLED=true
+    EXTERNAL_DISABLED=1
+
+Some tests are designed to validate the driver's behavior under load, or
+otherwise execute a large number of operations which may take a sizable amount
+of time. Such tests are skipped by default and can be run by setting the
+following environment variable:
+
+    STRESS=1
+
+Some tests fork the process to validate the driver's behavior when forking is
+involved. These tests are skipped by default and can be run by setting the
+following environment variable:
+
+    FORK=1
+
+OCSP tests require Python 3 with asn1crypto, oscrypto and flask packages
+installed, and they require the drivers-evergreen-tools submodule to be
+checked out. To run these tests, set the following environment variable:
+
+    OCSP=1
+
+To check out the submodule, run:
+
+    git submodule update --init --recursive
+
+## Debug Logging
+
+The test suite is run with the driver log level set to `WARN` by default.
+This produces a fair amount of output as many tests trigger various conditions
+resulting in the driver outputting warnings. This is expected behavior.
+
+To increase the driver log level to `DEBUG`, set the
+`MONGO_RUBY_DRIVER_CLIENT_DEBUG` environment variable to `1`, `true` or `yes`.
+This will produce additional log output pertaining to, for example, SDAM
+events and transitions performed by the driver, as well as log all
+commands sent to and responses received from the database.
+
+To debug authentication and user management commands, set the
+`MONGO_RUBY_DRIVER_UNREDACT_EVENTS` environment variable to `1`, `true` or
+`yes`. This will disable redaction of command monitoring payloads for sensitive
+commands. Normally this environment variable should be used with
+`MONGO_RUBY_DRIVER_CLIENT_DEBUG` to see the command payloads.
 
 ## Caveats
 
@@ -515,12 +623,6 @@ enabled. This is accomplished by starting `mongod` with the following option:
 
     --setParameter enableTestCommands=1
 
-### Log Output
-
-The test suite is run with the driver log level set to WARN by default.
-This produces a fair amount of output as many tests trigger various conditions
-resulting in the driver outputting warnings. This is expected behavior.
-
 ## Running Individual Examples
 
 Individual examples can be run by invoking `rspec` instead of `rake`. Prior