Plugins/All-Inkl.ps1
|
function Get-CurrentPluginType { 'dns-01' } function Add-DnsTxt { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [string]$RecordName, [Parameter(Mandatory,Position=1)] [string]$TxtValue, [Parameter(Mandatory,Position=2)] [string]$KasUsername, [Parameter(ParameterSetName='plain',Mandatory,Position=2)] [securestring]$KasPwd, [Parameter(ParameterSetName='sha1',Mandatory,Position=2)] [securestring]$KasPwdHash, [Parameter(ParameterSetName='session',Mandatory,Position=2)] [securestring]$KasSession, [Parameter(ValueFromRemainingArguments)] $ExtraParams ) # get effective KAS login data from parameter sets $loginData = Get-KasLoginDataFromParameters $PSCmdlet.ParameterSetName $KasUsername $KasPwd $KasPwdHash $KasSession # load current DNS settings from KAS API $settingsObj = Get-KASDNSSettings $loginData $RecordName # remove zone from record name $recNameWithoutZone = ($RecordName -ireplace [regex]::Escape($settingsObj.zone), [string]::Empty).TrimEnd('.') # search for existing DNS settings for the record $existingSettingsItem = Find-KASDNSSettingsItemInList $settingsObj.dnsSettings $recNameWithoutZone $TxtValue if ($existingSettingsItem) { Write-Verbose "Record $RecordName already contains $TxtValue. Nothing to do." return } # get zone_host for adding if ($settingsObj.zone.EndsWith(".")) { $zoneHost = $settingsObj.zone } else { $zoneHost = $settingsObj.zone + "." } # create DNS settings entry $addDnsSettingsParameters = @{ 'zone_host'=$zoneHost 'record_type'='TXT' 'record_name'=$recNameWithoutZone 'record_data'=$TxtValue 'record_aux'='0' } $kasAPIResponse = Invoke-KasApiAction $loginData 'add_dns_settings' $addDnsSettingsParameters Write-Debug $kasAPIResponse.OuterXml <# .SYNOPSIS Add a DNS TXT record to All-Inkl.com KAS .DESCRIPTION Uses the All-Inkl.com KAS API to add a DNS TXT record. .PARAMETER RecordName The fully qualified name of the TXT record. .PARAMETER TxtValue The value of the TXT record. .PARAMETER KasUsername The KAS authentication user .PARAMETER KasPwd The password for your All-Inkl KAS account. .PARAMETER KasPwdHash The sha1 hash of the password for your All-Inkl KAS account. .PARAMETER KasSession The session id of an open session on the KAS API. Use this parameter if you want to handle authentication on your own. .PARAMETER ExtraParams This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. .EXAMPLE $pass = Read-Host "Password" -AsSecureString Add-DnsTxt '_acme-challenge.example.com' 'txt-value' -KasUsername 'userName' -KasPwd $pass Adds a TXT record for the specified site with the specified value. #> } function Remove-DnsTxt { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [string]$RecordName, [Parameter(Mandatory,Position=1)] [string]$TxtValue, [Parameter(Mandatory,Position=2)] [string]$KasUsername, [Parameter(ParameterSetName='plain',Mandatory,Position=2)] [securestring]$KasPwd, [Parameter(ParameterSetName='sha1',Mandatory,Position=2)] [securestring]$KasPwdHash, [Parameter(ParameterSetName='session',Mandatory,Position=2)] [securestring]$KasSession, [Parameter(ValueFromRemainingArguments)] $ExtraParams ) # get effective KAS login data from parameter sets $loginData = Get-KasLoginDataFromParameters $PSCmdlet.ParameterSetName $KasUsername $KasPwd $KasPwdHash $KasSession # load current DNS settings from KAS API $settingsObj = Get-KASDNSSettings $loginData $RecordName # remove zone from record name $recNameWithoutZone = ($RecordName -ireplace [regex]::Escape($settingsObj.zone), [string]::Empty).TrimEnd('.') # search for existing DNS settings for the record $existingSettingsItem = Find-KASDNSSettingsItemInList $settingsObj.dnsSettings $recNameWithoutZone $TxtValue if ((-not $existingSettingsItem) -or (-not $existingSettingsItem.Node)) { Write-Verbose "Record $RecordName with value $TxtValue not found. Nothing to do." return } $recordIdElement = Select-XmlFromKASResult $existingSettingsItem.Node ".//item[contains(key, 'record_id')]/value" if ((-not $recordIdElement) -or (-not $recordIdElement.Node)) { throw "Couldn't read record id for $RecordName" } # create DNS settings entry $removeDnsSettingsParameters = @{ 'record_id'=$recordIdElement.Node.InnerText } $kasAPIResponse = Invoke-KasApiAction $loginData 'delete_dns_settings' $removeDnsSettingsParameters Write-Debug $kasAPIResponse.OuterXml <# .SYNOPSIS Remove a DNS TXT record from All-Inkl.com KAS .DESCRIPTION Uses the All-Inkl.com KAS API to remove the DNS TXT record. .PARAMETER RecordName The fully qualified name of the TXT record. .PARAMETER TxtValue The value of the TXT record. .PARAMETER KasUsername The KAS authentication user .PARAMETER KasPwd The password for your All-Inkl KAS account. .PARAMETER KasPwdHash The sha1 hash of the password for your All-Inkl KAS account. .PARAMETER KasSession The session id of an open session on the KAS API. Use this parameter if you want to handle authentication on your own. .PARAMETER ExtraParams This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. .EXAMPLE $pass = Read-Host "Password" -AsSecureString Remove-DnsTxt '_acme-challenge.example.com' 'txt-value' -KasUsername 'userName' -KasPwd $pass Removes a TXT record for the specified site with the specified value. #> } function Save-DnsTxt { [CmdletBinding()] param( [Parameter(ValueFromRemainingArguments)] $ExtraParams ) <# .SYNOPSIS Not required .DESCRIPTION This provider does not require calling this function to commit changes to DNS records. .PARAMETER ExtraParams This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports. #> } ############################ # Helper Functions ############################ # KAS API documentation # https://kasapi.kasserver.com/dokumentation/ function Get-KasLoginDataFromParameters { [CmdletBinding()] param( [string]$paramSetName, [string]$KasUsername, [securestring]$KasPwd, [securestring]$KasPwdHash, [securestring]$KasSession ) # check which parameter to use and set KAS auth type accordingly if ('plain' -eq $paramSetName) { $secureAuthData = $KasPwd $kasAuthType = 'plain' } elseif ('sha1' -eq $paramSetName) { $secureAuthData = $KasPwdHash $kasAuthType = 'sha1' } elseif ('session' -eq $paramSetName) { $secureAuthData = $KasSession $kasAuthType = 'session' } # get plaintext from securestring $kasAuthData = [pscredential]::new('a',$secureAuthData).GetNetworkCredential().Password # return the effective authentication data return @{ kas_login=$KasUsername; kas_auth_type=$kasAuthType; kas_auth_data=$kasAuthData } <# .SYNOPSIS Internal helper function that checks all input parameter sets/combinations and returns the effective login data .DESCRIPTION KAS API supports three different login types: plain/sha1/session see https://kasapi.kasserver.com/dokumentation/phpdoc/ By using the type 'session' it is possible to reuse existing sessions when Posh-ACME is used as a part of a larger script. All-Inkl.com users have received warnings that sha1 auth option may be discontinued as of Dec 2022. .PARAMETER paramSetName The name of the paramSet that was detected by the public methods of this plugin. .PARAMETER KasUsername The username for the KAS API. The username is required for all login types. .PARAMETER KasPwd The plain password as securestring. .PARAMETER KasPwdHash The sha1 hash of the password as securestring. .PARAMETER KasSession The session id of an existing/open session in KAS as securestring. #> } function Get-KASDNSSettings { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [hashtable]$loginData, [Parameter(Mandatory,Position=1)] [string]$RecordName ) # setup a module variable to cache the record to zone_host mapping if (!$script:KASRecordZones) { $script:KASRecordZones = @{} } # check for the record in the zone cache if ($script:KASRecordZones.ContainsKey($RecordName)) { $kasZoneHost = $script:KASRecordZones.$RecordName $kasAPIResponse = Invoke-KASAPIGetDNSSettings $loginData $kasZoneHost return @{ zone = $kasZoneHost dnsSettings = $kasAPIResponse } } else { # Search for the zone from longest to shortest set of FQDN pieces. $pieces = $RecordName.Split('.') for ($i=0; $i -lt ($pieces.Count-1); $i++) { $zoneTest = $pieces[$i..($pieces.Count-1)] -join '.' Write-Debug "Checking zone $zoneTest" # skip calling KAS API for _acme-challenge.* # The API would return an error zone_syntax_incorrect anyway if ($zoneTest.StartsWith("_acme-challenge.")) { continue; } try { $kasAPIResponse = Invoke-KASAPIGetDNSSettings $loginData $zoneTest # check for results if (-not $kasAPIResponse) { continue; } # since the current $zoneTest returned a result, cache it for future calls $script:KASRecordZones.$RecordName = $zoneTest return @{ zone = $zoneTest dnsSettings = $kasAPIResponse } } catch { # Ignore "zone_not_found" and try the next set of FQDN pieces. Throw all other errors if (!$_.Exception.Message.Contains("zone_not_found")) { throw } } } throw "No zone_host found for $RecordName" } <# .SYNOPSIS loads the DNS settings from the KAS API .DESCRIPTION tries to find the correct zone for the given record name and loads the corresponding DNS settings .PARAMETER loginData a hashtable containing the login data .PARAMETER RecordName the record name the settings should be loaded for #> } function Invoke-KASAPIGetDNSSettings { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [hashtable]$loginData, [Parameter(Mandatory,Position=1)] [string]$zoneHost ) # prepare API params $getDnsSettingsParameters = @{ 'zone_host'=$zoneHost } # call API $responseDocument = Invoke-KasApiAction $loginData 'get_dns_settings' $getDnsSettingsParameters # check for results if (-not $responseDocument) { return $null; } # find ReturnInfo in result $returnInfo = Select-XmlFromKASResult $responseDocument "./return/item[contains(key, 'Response')]/value/item[contains(key,'ReturnInfo')]/value" if ($returnInfo -and $returnInfo.Node) { return $returnInfo.Node } else { return $null } <# .SYNOPSIS invokes the action 'get_dns_settings' on the KAS API .DESCRIPTION calls the KAS SOAP API, invokes the 'get_dns_settings' action and returns the result .PARAMETER loginData a hashtable containing the login data .PARAMETER zoneHost the zone_host parameter that is provided to the KAS API #> } function Invoke-KasApiAction { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [hashtable]$loginData, [Parameter(Mandatory,Position=1)] [string]$kasAPIAction, [Parameter(Mandatory,Position=2)] [hashtable]$kasParameters ) # wsdl for the api service: https://kasapi.kasserver.com/soap/wsdl/KasApi.wsdl # wsdl for the auth service: https://kasapi.kasserver.com/soap/wsdl/KasAuth.wsdl $kasAPIUri = "https://kasapi.kasserver.com/soap/KasApi.php" # init KAS flood delay # The KAS API documentation can be read as if the delay is only relevant when calling # the same API action multiple times. But tests have shown that it is also enforced when # calling different API methods. So we use one generic delay for all calls. if (!$script:KASNextRequestTime) { $script:KASNextRequestTime = Get-Date } # create parameter hastable $paramData = @{ 'kas_action' = $kasAPIAction 'KasRequestParams' = $kasParameters } # copy login data to parameters foreach($key in $loginData.keys) { $paramData[$key] = $loginData[$key] } # convert parameters to JSON $paramJson = $paramData | ConvertTo-Json -Depth 2 # put parameters in SOAP envelope $envelopeXml=@' <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="https://kasserver.com/" xmlns:types="https://kasserver.com/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <q1:KasApi xmlns:q1="urn:xmethodsKasApi"> <Params xsi:type="xsd:string"> '@ + $paramJson + @' </Params> </q1:KasApi> </soap:Body> </soap:Envelope> '@ try { # wait for KAS flood delay if necessary $slpFor = (New-TimeSpan -End $script:KASNextRequestTime).TotalMilliseconds if ($slpFor -gt 0) { Write-Verbose "Waiting ${slpFor}ms for KAS API flood delay..." Start-Sleep -Milliseconds $slpFor } # invoke KAS API $response = Invoke-WebRequest "$kasAPIUri" -Body "$envelopeXml" -contentType "text/xml; charset=utf-8" -method POST @Script:UseBasic # parse result content as xml [xml]$xmlDocument = $response.Content # find body element $bdy = Select-XmlFromKASResult $xmlDocument '/envelopeNS:Envelope/envelopeNS:Body' if ((-not $bdy) -or (-not $bdy.Node)) { throw "No body element in KAS API response found." } # check for a 'Fault' element and throw an error if necessary $faultElement = Select-XmlFromKASResult $bdy.Node './envelopeNS:Fault' if ($faultElement) { if (-not $faultElement.Node) { throw "Unexpected error: Fault elementin KAS API response found but Node property was empty." } $faultString = Select-XmlFromKASResult $faultElement.Node './faultstring' $faultDetail = Select-XmlFromKASResult $faultElement.Node './detail' if ($faultString -and $faultString.Node) { if ($faultDetail -and $faultDetail.Node) { $errorMsg = "KAS API error: " + $faultString.Node.InnerText + " (" + $faultDetail.Node.InnerText + ")" } else { $errorMsg = "KAS API error: " + $faultString.Node.InnerText } } else { if ($faultDetail -and $faultDetail.Node) { $errorMsg = "KAS API error: " + $faultDetail.Node.InnerText } else { $errorMsg = "KAS API error: unknown error" } } Set-KASFloodDelay $faultElement.Node throw $errorMsg } # check for a 'KasApiResponse' element $result = Select-XmlFromKASResult $bdy.Node './resultNS:KasApiResponse' if ($result -and $result.Node) { Set-KASFloodDelay $result.Node return $result.Node } else { throw "KAS API error: 'KasApiResponse' not found" } } catch { Set-KASFloodDelay throw "An error occured: " + $_.Exception.Message } <# .SYNOPSIS invokes an action on the KAS API .DESCRIPTION calls the KAS SOAP API, invokes an action and returns the result .PARAMETER loginData a hashtable containing the login data .PARAMETER kasAPIAction the action that should be invoked on the KAS API available actions: https://kasapi.kasserver.com/dokumentation/phpdoc/packages/API%20Funktionen.html .PARAMETER kasParameters a hashtable that contains the parameters for the called API action #> } function Set-KASFloodDelay { [CmdletBinding()] param ( [Parameter(Position=0)] [System.Xml.XmlNode]$elementToSearchIn ) # The documentation of the KAS API could be read as if the delay is only enforced when an API call # was successfull. As expected, testing showed, that it is also enforced for failed calls. # But unfortunately for failed calls the repsonse doesn't include the waiting time. This is why we will # be waiting for the default 2 seconds that succeeded requests normally return when no value was specified. # when a XmlNode was specified search it for the flood delay key/value pair if ($elementToSearchIn) { $floodDelayElement = Select-XmlFromKASResult $elementToSearchIn ".//item[contains(key, 'KasFloodDelay')]/value" if ($floodDelayElement -and $floodDelayElement.Node -and ($floodDelayElement.Node.InnerText -gt 0)) { $script:KASNextRequestTime = (Get-Date).AddSeconds($floodDelayElement.Node.InnerText) return } $floodDelayElement = Select-XmlFromKASResult $elementToSearchIn ".//kasflooddelay" if ($floodDelayElement -and $floodDelayElement.Node -and ($floodDelayElement.Node.InnerText -gt 0)) { $script:KASNextRequestTime = (Get-Date).AddSeconds($floodDelayElement.Node.InnerText) return } } # set next request time to a default value as fallback if ($script:KASNextRequestTime -le (Get-Date)) { $script:KASNextRequestTime = (Get-Date).AddSeconds(2) } <# .SYNOPSIS searches a KAS API result XmlNode for the flood delay and stores the next request time for the KAS API .DESCRIPTION Takes a XmlNode from a KAS API result and searches for the flood delay key/value pair. When found it stores the value for the next API call. Otherwise it sets a default value. .PARAMETER elementToSearchIn the parent XmlNode to search in (search root) #> } function Select-XmlFromKASResult { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [System.Xml.XmlNode]$parentElement, [Parameter(Mandatory,Position=1)] [string]$xPathStr ) $xmlNamespaces = @{ envelopeNS = "http://schemas.xmlsoap.org/soap/envelope/" resultNS = "https://kasapi.kasserver.com/soap/KasApi.php" }; $result = Select-Xml -Xml $parentElement -XPath $xPathStr -Namespace $xmlNamespaces return $result <# .SYNOPSIS executes a given xpath on a given XmlNode .DESCRIPTION Takes a XmlNode and executes a xpath on it. .PARAMETER parentElement the parent XmlNode to search in (search root) .PARAMETER xPathStr the xpath string to execute #> } function Find-KASDNSSettingsItemInList { [CmdletBinding()] param( [Parameter(Mandatory,Position=0)] [System.Xml.XmlNode]$parentDNSSettingsElement, [Parameter(Mandatory,Position=1)] [AllowEmptyString()] [string]$recordNameWithoutZone, [Parameter(Mandatory,Position=2)] [string]$TxtValue ) # search for existing DNS settings for the record return Select-XmlFromKASResult $parentDNSSettingsElement @" ./item[ item[contains(key, 'record_name') and contains(value, '$recordNameWithoutZone')] and item[contains(key, 'record_type') and contains(value, 'TXT')] and item[contains(key, 'record_data') and contains(value, '$TxtValue')] ] "@ <# .SYNOPSIS searches a given XmlNode with KAS DNS Settings for matching child items .DESCRIPTION takes a XmlNode with child items and searches for the correct child by matching record_name, record_type and record_data .PARAMETER parentDNSSettingsElement the parent XmlNode to search in (search root) .PARAMETER recordNameWithoutZone the record_name to search for already truncated by the zone .PARAMETER TxtValue the value of the TXT record #> } |