From 9c9b3a8c636865ad5a0dc322ff5f7b49c455c18f Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Tue, 12 Mar 2019 14:22:37 -0700 Subject: [PATCH 01/10] draft plan to deal with send-mailmessage --- 1-Draft/RFCXXXX-Send-MailMessage.md | 72 +++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 1-Draft/RFCXXXX-Send-MailMessage.md diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md new file mode 100644 index 00000000..c99e0a68 --- /dev/null +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -0,0 +1,72 @@ +--- +RFC: RFCXXXX +Author: Travis Plunk +Status: Draft +SupercededBy: N/A +Version: 1.0 +Area: cmdlets +Comments Due: 4/30/2019 +Plan to implement: No +--- + +# Deprecating `Send-MailMessage` + +`Send-MailMessage` does not support many modern protocols leading to the inability to use this with modern secure mail services. +See [DotNet DE0005](https://github.com/dotnet/platform-compat/blob/master/docs/DE0005.md). +Since the protocols it uses are no longer considered secure, the cmdlet as is should not be used. +I recommend that we implement a plan to remove the cmdlet from powershell core and, if needed, +re-implement as a separate module. + +## Motivation + + Most major mail platforms now have REST methods to send mail allowing existing cmdlets to allow sending mail. + + * gmail + * https://developers.google.com/gmail/api/v1/reference/users/messages/send + * https://stackoverflow.com/questions/24460422/how-to-send-a-message-successfully-using-the-new-gmail-rest-api + * Office365 + * https://docs.microsoft.com/en-us/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#SendMessages + +## Removal Plan + +### Add a warning to 6.2 after the release of 6.2 + +During the 6.3 development time, we will add a warning to `Send-MailMessage` that an alternative should be found. + +### Remove the cmdlet in 6.3 + +During the development of 6.3, remove the `Send-MailMessage` cmdlet. + +### If needed, develop an alternative + +If needed, develop a new cmdlet based on the DotNet recommended solution of [MailKit](https://github.com/jstedfast/MailKit). + +## Alternate Proposals and Considerations + +The community could develop a replacement that can could be incorporated back into PowerShell Core. +This has the disadvantage of increasing the size of PowerShell Core and delaying the solution. + +### GMail REST API + +To use the GMail REST API the following additional items are needed + +### WebSafeBase64 + +For GMail, a MIME message is required to be encoded in this format. +https://code.google.com/p/stringencoders/wiki/WebSafeBase64 + +### Something to compose the MIME message + +For GMail, you have to pass the MIME message. + +--------------- + +## PowerShell Committee Decision + +### Voting Results + +### Majority Decision + +### Minority Decision + +N/A From 9fda6b4f8af115deed6ba207fa97b9d0a9464b58 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Tue, 12 Mar 2019 14:40:17 -0700 Subject: [PATCH 02/10] clarify timing about warning --- 1-Draft/RFCXXXX-Send-MailMessage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index c99e0a68..2d8ad927 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -31,7 +31,7 @@ re-implement as a separate module. ### Add a warning to 6.2 after the release of 6.2 -During the 6.3 development time, we will add a warning to `Send-MailMessage` that an alternative should be found. +In a 6.2 servicing release, we will add a warning to `Send-MailMessage` that an alternative method should be found. ### Remove the cmdlet in 6.3 From 63e97b81ae68364d865bcec06c5c8285bf9f5837 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Tue, 12 Mar 2019 16:28:27 -0700 Subject: [PATCH 03/10] Address grammar issue --- 1-Draft/RFCXXXX-Send-MailMessage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index 2d8ad927..d2c74579 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -19,7 +19,7 @@ re-implement as a separate module. ## Motivation - Most major mail platforms now have REST methods to send mail allowing existing cmdlets to allow sending mail. + Most major mail platforms now have REST methods to send mail, which allows `Invoke-RestMethod' to allow sending mail messages. * gmail * https://developers.google.com/gmail/api/v1/reference/users/messages/send From f32daeacc8a1024ce2b768b96b5b1c7414ff605d Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Tue, 19 Mar 2019 10:27:26 -0700 Subject: [PATCH 04/10] Add an alternative implementation to address feedback --- 1-Draft/RFCXXXX-Send-MailMessage.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index d2c74579..a93ba755 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -19,6 +19,14 @@ re-implement as a separate module. ## Motivation +### Primary + +The underlying API, [`SmtpClient`](https://docs.microsoft.com/dotnet/api/system.net.mail.smtpclient), doesn't support many modern protocols. +It is compat-only. +It's great for one off emails from tools, but doesn't scale to modern requirements of the protocol. + +### Secondary + Most major mail platforms now have REST methods to send mail, which allows `Invoke-RestMethod' to allow sending mail messages. * gmail @@ -29,9 +37,9 @@ re-implement as a separate module. ## Removal Plan -### Add a warning to 6.2 after the release of 6.2 +### Add a warning to 6.2 -In a 6.2 servicing release, we will add a warning to `Send-MailMessage` that an alternative method should be found. +In a 6.2, we will add an obsolete warning to `Send-MailMessage` that an alternative method should be found. ### Remove the cmdlet in 6.3 @@ -43,19 +51,29 @@ If needed, develop a new cmdlet based on the DotNet recommended solution of [Mai ## Alternate Proposals and Considerations +### Alternative to removal + +Instead of removing the cmdlet, +a switch could be added requiring the user to accept the risk of using older less secure implementations. +This switch would be called `-AllowInsecure` and would be mandatory. + +### Community replacement + The community could develop a replacement that can could be incorporated back into PowerShell Core. This has the disadvantage of increasing the size of PowerShell Core and delaying the solution. -### GMail REST API +### Additional considerations + +#### GMail REST API To use the GMail REST API the following additional items are needed -### WebSafeBase64 +#### WebSafeBase64 For GMail, a MIME message is required to be encoded in this format. https://code.google.com/p/stringencoders/wiki/WebSafeBase64 -### Something to compose the MIME message +#### Something to compose the MIME message For GMail, you have to pass the MIME message. From 97682757baa764ff835cb6c42b2384c517f6bf24 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 29 Mar 2019 16:42:35 -0700 Subject: [PATCH 05/10] Update RFC to reflect work which has been done --- 1-Draft/RFCXXXX-Send-MailMessage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index a93ba755..6ed3a545 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -39,7 +39,7 @@ It's great for one off emails from tools, but doesn't scale to modern requiremen ### Add a warning to 6.2 -In a 6.2, we will add an obsolete warning to `Send-MailMessage` that an alternative method should be found. +In a 6.2, we have added an obsolete warning to `Send-MailMessage` that an alternative method should be found. ### Remove the cmdlet in 6.3 From 7c0ba6068e5ac00cec0f69d92923d210c05b24f5 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Thu, 4 Apr 2019 13:19:11 -0700 Subject: [PATCH 06/10] Make it clear that removal is no longer the primary option for 6.3 --- 1-Draft/RFCXXXX-Send-MailMessage.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index 6ed3a545..ec1f3365 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -35,15 +35,20 @@ It's great for one off emails from tools, but doesn't scale to modern requiremen * Office365 * https://docs.microsoft.com/en-us/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#SendMessages -## Removal Plan +## Deprecation Plan ### Add a warning to 6.2 In a 6.2, we have added an obsolete warning to `Send-MailMessage` that an alternative method should be found. -### Remove the cmdlet in 6.3 +**Note:** Adding an obsolete warning should not break compatibility in any way. -During the development of 6.3, remove the `Send-MailMessage` cmdlet. +### Positive confirmation of issue in 6.3 + +We will add a switch requiring the user to accept the risk of using older **possibly** less secure implementations. +This switch would be called `-AllowUnsecureConnection` and would be mandatory + +**Note:** The switch name is based on the [DSC Property](https://docs.microsoft.com/en-us/powershell/dsc/managing-nodes/metaconfig#configuration-server-blocks) ### If needed, develop an alternative @@ -51,11 +56,11 @@ If needed, develop a new cmdlet based on the DotNet recommended solution of [Mai ## Alternate Proposals and Considerations -### Alternative to removal +### Remove the cmdlet during 6.3 + +During the development of 6.3, remove the `Send-MailMessage` cmdlet. -Instead of removing the cmdlet, -a switch could be added requiring the user to accept the risk of using older less secure implementations. -This switch would be called `-AllowInsecure` and would be mandatory. +Feedback on this option was negative and the RFC has been updated with then next most reasonable option. ### Community replacement From 4c85a3d9b8f14d25c368423f64260b4bddf99b11 Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 17 May 2019 12:52:40 -0700 Subject: [PATCH 07/10] replace deprecate with obsolete --- 1-Draft/RFCXXXX-Send-MailMessage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index ec1f3365..83a1d1e9 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -9,7 +9,7 @@ Comments Due: 4/30/2019 Plan to implement: No --- -# Deprecating `Send-MailMessage` +# Obsoleting `Send-MailMessage` `Send-MailMessage` does not support many modern protocols leading to the inability to use this with modern secure mail services. See [DotNet DE0005](https://github.com/dotnet/platform-compat/blob/master/docs/DE0005.md). @@ -35,7 +35,7 @@ It's great for one off emails from tools, but doesn't scale to modern requiremen * Office365 * https://docs.microsoft.com/en-us/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#SendMessages -## Deprecation Plan +## Obsoletion Plan ### Add a warning to 6.2 From 0603bb22631270947fa5ea9a8fb9d2d6597fbaad Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Fri, 31 May 2019 11:08:35 -0700 Subject: [PATCH 08/10] Update 1-Draft/RFCXXXX-Send-MailMessage.md Co-Authored-By: Joel Sallow (/u/ta11ow) <32407840+vexx32@users.noreply.github.com> --- 1-Draft/RFCXXXX-Send-MailMessage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index 83a1d1e9..14aebc90 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -27,7 +27,7 @@ It's great for one off emails from tools, but doesn't scale to modern requiremen ### Secondary - Most major mail platforms now have REST methods to send mail, which allows `Invoke-RestMethod' to allow sending mail messages. + Most major mail platforms now have REST methods to send mail, which allows `Invoke-RestMethod` to allow sending mail messages. * gmail * https://developers.google.com/gmail/api/v1/reference/users/messages/send From 84cb747ee0f12304f14471d8714dc749df5d6615 Mon Sep 17 00:00:00 2001 From: Joey Aiello Date: Thu, 8 Aug 2019 10:59:11 -0700 Subject: [PATCH 09/10] Remove opt-in switch from Send-MailMessage RFC Per conversation with @TravisEz13 and the @PowerShell/powershell-committee, removing the language around an opt-in switch that breaks existing usage. However, we'll be leaving the obsolescence message until an alternative is decided on. --- 1-Draft/RFCXXXX-Send-MailMessage.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/1-Draft/RFCXXXX-Send-MailMessage.md index 14aebc90..8594ad6c 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/1-Draft/RFCXXXX-Send-MailMessage.md @@ -43,13 +43,6 @@ In a 6.2, we have added an obsolete warning to `Send-MailMessage` that an altern **Note:** Adding an obsolete warning should not break compatibility in any way. -### Positive confirmation of issue in 6.3 - -We will add a switch requiring the user to accept the risk of using older **possibly** less secure implementations. -This switch would be called `-AllowUnsecureConnection` and would be mandatory - -**Note:** The switch name is based on the [DSC Property](https://docs.microsoft.com/en-us/powershell/dsc/managing-nodes/metaconfig#configuration-server-blocks) - ### If needed, develop an alternative If needed, develop a new cmdlet based on the DotNet recommended solution of [MailKit](https://github.com/jstedfast/MailKit). @@ -67,6 +60,17 @@ Feedback on this option was negative and the RFC has been updated with then next The community could develop a replacement that can could be incorporated back into PowerShell Core. This has the disadvantage of increasing the size of PowerShell Core and delaying the solution. +### Positive confirmation of issue in 6.3 + +We could add a switch requiring the user to accept the risk of using older **possibly** less secure implementations. +This switch would be called `-AllowUnsecureConnection` and would be mandatory. + +**Note:** The switch name is based on the [DSC Property](https://docs.microsoft.com/en-us/powershell/dsc/managing-nodes/metaconfig#configuration-server-blocks) + +However, given the high usage of `Send-MailMessage` in automated scenarios (like scheduled tasks), +and the plan to work on a `MailKit` based alternative, we'd rather leave the cmdlet working as-is +for the time being. + ### Additional considerations #### GMail REST API From 830c8a3f3b572454ca78fc1f9664667cea7baac0 Mon Sep 17 00:00:00 2001 From: Joey Aiello Date: Mon, 12 Aug 2019 11:44:43 -0700 Subject: [PATCH 10/10] Prepare Send-MailMessage RFC for acceptance --- .../RFC0042-Send-MailMessage.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) rename 1-Draft/RFCXXXX-Send-MailMessage.md => 5-Final/RFC0042-Send-MailMessage.md (95%) diff --git a/1-Draft/RFCXXXX-Send-MailMessage.md b/5-Final/RFC0042-Send-MailMessage.md similarity index 95% rename from 1-Draft/RFCXXXX-Send-MailMessage.md rename to 5-Final/RFC0042-Send-MailMessage.md index 8594ad6c..5a534525 100644 --- a/1-Draft/RFCXXXX-Send-MailMessage.md +++ b/5-Final/RFC0042-Send-MailMessage.md @@ -1,7 +1,7 @@ --- -RFC: RFCXXXX +RFC: RFC0042 Author: Travis Plunk -Status: Draft +Status: Final SupercededBy: N/A Version: 1.0 Area: cmdlets @@ -85,15 +85,3 @@ https://code.google.com/p/stringencoders/wiki/WebSafeBase64 #### Something to compose the MIME message For GMail, you have to pass the MIME message. - ---------------- - -## PowerShell Committee Decision - -### Voting Results - -### Majority Decision - -### Minority Decision - -N/A